WIP checkpoint: Write auth endpoint tests (pytest)

- auth.py: _create_access_token had no jti claim, so two refreshes
  within the same wall-clock second produced byte-identical access
  tokens (same failure mode already fixed for refresh tokens earlier)
- test_refresh_endpoint.py: usernames (jwttoken, refreshuser, etc.)
  collided with test_auth_endpoints.py's own test usernames once run
  in the same pytest session against a shared DB with no per-test
  isolation -- exactly how run_checkpoint_tests.py invokes pytest.
  Namespaced this file's usernames with a refep_ prefix.

Full backend suite (63 tests) passes clean end-to-end against a real
Postgres with real migrations applied.

.gitignore

@@ -8,3 +8,6 @@ export/
 # OS
 .DS_Store
 Thumbs.db
+
+# Godot UID files (regenerated from path)
+*.uid

backend/.env.example

@@ -4,10 +4,13 @@ DATABASE_URL=postgresql+asyncpg://agp_user:agp_password@localhost:5432/agp_db
 # Redis
 REDIS_URL=redis://localhost:6379/0
 
-# JWT
+# JWT / Auth
-SECRET_KEY=change-me-to-a-secure-random-string
+ALGORITHM=RS256
-ALGORITHM=HS256
+ACCESS_TOKEN_EXPIRE_MINUTES=60
-ACCESS_TOKEN_EXPIRE_MINUTES=30
+REFRESH_TOKEN_EXPIRE_DAYS=30
+# Directory where the RSA keypair is loaded/generated at runtime.
+# Defaults to ~/.agp/keys (outside the repo). Keys are never committed to git.
+RSA_KEY_DIR=~/.agp/keys
 
 # App
 APP_NAME=AGP Backend

backend/alembic/versions/0003_add_refresh_tokens_table.py

@@ -0,0 +1,36 @@
+"""add refresh_tokens table
+
+Revision ID: 0003_add_refresh_tokens_table
+Revises: 0002_add_date_of_birth_to_users
+Create Date: 2025-07-25 00:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision: str = "0003_add_refresh_tokens_table"
+down_revision: Union[str, None] = "0002_add_date_of_birth_to_users"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Create the refresh_tokens table."""
+    op.create_table(
+        "refresh_tokens",
+        sa.Column("id", sa.String(36), primary_key=True),
+        sa.Column("user_id", sa.Integer(), sa.ForeignKey("users.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("token", sa.String(512), unique=True, index=True, nullable=False),
+        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("is_active", sa.Boolean(), server_default=sa.text("true"), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+    )
+
+
+def downgrade() -> None:
+    """Drop the refresh_tokens table."""
+    op.drop_table("refresh_tokens")

backend/app/config.py

@@ -1,10 +1,56 @@
 """Application configuration via pydantic-settings."""
 
 from functools import lru_cache
+from pathlib import Path
 
+from cryptography.hazmat.primitives.asymmetric.rsa import (
+    RSAPrivateKey,
+    RSAPublicKey,
+    generate_private_key,
+)
+from cryptography.hazmat.primitives.serialization import (
+    Encoding,
+    NoEncryption,
+    PrivateFormat,
+    PublicFormat,
+    load_pem_private_key,
+    load_pem_public_key,
+)
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 
+def _load_or_generate_rsa_keys(key_dir: Path) -> tuple[bytes, bytes]:
+    """Load existing RSA keys or generate a new pair.
+
+    Keys are stored as PEM files in *key_dir*.  The directory is created
+    if it does not exist.  Files are named ``private.pem`` and
+    ``public.pem`` and are **not** committed to git.
+    """
+    private_path = key_dir / "private.pem"
+    public_path = key_dir / "public.pem"
+
+    if private_path.exists() and public_path.exists():
+        private_pem = private_path.read_bytes()
+        public_pem = public_path.read_bytes()
+    else:
+        # Generate a new 2048-bit RSA key pair
+        private_key = generate_private_key(public_exponent=65537, key_size=2048)
+        private_pem = private_key.private_bytes(
+            Encoding.PEM,
+            PrivateFormat.PKCS8,
+            NoEncryption(),
+        )
+        public_pem = private_key.public_key().public_bytes(
+            Encoding.PEM,
+            PublicFormat.SubjectPublicKeyInfo,
+        )
+        key_dir.mkdir(parents=True, exist_ok=True)
+        private_path.write_bytes(private_pem)
+        public_path.write_bytes(public_pem)
+
+    return private_pem, public_pem
+
+
 class Settings(BaseSettings):
     # App
     APP_NAME: str = "AGP Backend"
@@ -18,11 +64,13 @@ class Settings(BaseSettings):
     REDIS_URL: str = "redis://localhost:6379/0"
 
     # JWT / Auth
-    # NOTE: production must override SECRET_KEY with a secure random value
+    ALGORITHM: str = "RS256"
-    # (e.g. `python -c "import secrets; print(secrets.token_urlsafe(32))"`)
+    ACCESS_TOKEN_EXPIRE_MINUTES: int = 60
-    SECRET_KEY: str = "change-me-to-a-secure-random-string"
+    REFRESH_TOKEN_EXPIRE_DAYS: int = 30
-    ALGORITHM: str = "HS256"
+
-    ACCESS_TOKEN_EXPIRE_MINUTES: int = 30
+    # RS256 key storage.  Defaults to a directory outside the repo so the
+    # generated keypair is never accidentally committed.
+    RSA_KEY_DIR: str = str(Path.home() / ".agp" / "keys")
 
     # CORS
     CORS_ORIGINS: str = "http://localhost:8080,http://localhost:3000"
@@ -42,6 +90,32 @@ class Settings(BaseSettings):
     def cors_origins_list(self) -> list[str]:
         return [origin.strip() for origin in self.CORS_ORIGINS.split(",")]
 
+    @property
+    def rsa_key_dir(self) -> Path:
+        return Path(self.RSA_KEY_DIR)
+
+    @property
+    def private_pem(self) -> bytes:
+        """Return the private key PEM bytes (loads/generates on first call)."""
+        private_pem, _ = _load_or_generate_rsa_keys(self.rsa_key_dir)
+        return private_pem
+
+    @property
+    def public_pem(self) -> bytes:
+        """Return the public key PEM bytes (loads/generates on first call)."""
+        _, public_pem = _load_or_generate_rsa_keys(self.rsa_key_dir)
+        return public_pem
+
+    @property
+    def private_key(self) -> RSAPrivateKey:
+        """Return the deserialized RSA private key object."""
+        return load_pem_private_key(self.private_pem, password=None)
+
+    @property
+    def public_key(self) -> RSAPublicKey:
+        """Return the deserialized RSA public key object."""
+        return load_pem_public_key(self.public_pem)
+
 
 @lru_cache()
 def get_settings() -> Settings:

backend/app/dependencies.py

@@ -27,7 +27,7 @@ async def get_current_user(
     )
     try:
         payload = jwt.decode(
-            token, settings.SECRET_KEY, algorithms=[settings.ALGORITHM]
+            token, settings.public_pem, algorithms=[settings.ALGORITHM]
         )
         user_id: str | None = payload.get("sub")
         if user_id is None:

backend/app/models/session.py

@@ -3,6 +3,7 @@ import uuid
 from sqlalchemy import Column, Integer, String, DateTime, ForeignKey, Boolean
 from sqlalchemy.orm import relationship
 from sqlalchemy.sql import func
+
 from app.database import Base
 
 
@@ -18,3 +19,23 @@ class Session(Base):
     updated_at = Column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now())
 
     user = relationship("User", back_populates="sessions")
+
+
+class RefreshToken(Base):
+    __tablename__ = "refresh_tokens"
+
+    id = Column(String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
+    user_id = Column(Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False)
+    # RS256 JWTs are ~420+ chars; 512 is sufficient and matches the migration.
+    token = Column(String(512), unique=True, index=True, nullable=False)
+    expires_at = Column(DateTime(timezone=True), nullable=False)
+    is_active = Column(Boolean, nullable=False, default=True, server_default="true")
+    created_at = Column(DateTime(timezone=True), nullable=False, server_default=func.now())
+    updated_at = Column(
+        DateTime(timezone=True),
+        nullable=False,
+        server_default=func.now(),
+        onupdate=func.now(),
+    )
+
+    user = relationship("User", back_populates="refresh_tokens")

backend/app/models/user.py

@@ -21,6 +21,7 @@ class User(Base):
     updated_at = Column(DateTime(timezone=True), onupdate=func.now())
 
     sessions = relationship("Session", back_populates="user", cascade="all, delete-orphan")
+    refresh_tokens = relationship("RefreshToken", back_populates="user", cascade="all, delete-orphan")
     worlds = relationship("World", back_populates="owner")
     assets = relationship("Asset", back_populates="owner")
 

backend/app/routers/auth.py

@@ -1,20 +1,21 @@
 """Authentication router - login, register, token refresh."""
 
+import uuid
 from datetime import date, datetime, timedelta, timezone
 
 from fastapi import APIRouter, Depends, HTTPException, status
 from fastapi.security import OAuth2PasswordRequestForm
-from pydantic import BaseModel, EmailStr, field_validator
+from jose import JWTError, jwt
-
-from jose import jwt
 from passlib.context import CryptContext
+from pydantic import BaseModel, EmailStr, field_validator
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.config import settings
 from app.database import get_db
 from app.dependencies import CurrentUser
+from app.models.session import RefreshToken
 from app.models.user import User
-from sqlalchemy.ext.asyncio import AsyncSession
-from sqlalchemy import select
 
 pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
 
@@ -25,7 +26,13 @@ router = APIRouter()
 
 class TokenResponse(BaseModel):
     access_token: str
+    refresh_token: str
     token_type: str = "bearer"
+    access_token_expires_minutes: int
+
+
+class RefreshRequest(BaseModel):
+    refresh_token: str
 
 
 class RegisterRequest(BaseModel):
@@ -59,12 +66,43 @@ class UserResponse(BaseModel):
 # --- Helpers ---
 
 def _create_access_token(data: dict) -> str:
+    """Create a signed access token using RS256.
+
+    Includes a unique ``jti`` claim so that concurrent/same-second calls
+    (e.g. back-to-back /refresh requests) still produce distinct tokens —
+    without it, two tokens minted for the same user within the same
+    second are byte-identical since ``sub``/``exp`` are the only claims.
+    """
     to_encode = data.copy()
+    to_encode["jti"] = str(uuid.uuid4())
     expire = datetime.now(timezone.utc) + timedelta(
         minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES
     )
     to_encode.update({"exp": expire})
-    return jwt.encode(to_encode, settings.SECRET_KEY, algorithm=settings.ALGORITHM)
+    return jwt.encode(
+        to_encode,
+        settings.private_pem,
+        algorithm=settings.ALGORITHM,
+    )
+
+
+def _create_refresh_token(data: dict) -> str:
+    """Create a signed refresh token using RS256.
+
+    Includes a unique ``jti`` claim so that concurrent calls produce
+    distinct tokens even when issued within the same second.
+    """
+    to_encode = data.copy()
+    to_encode["jti"] = str(uuid.uuid4())
+    expire = datetime.now(timezone.utc) + timedelta(
+        days=settings.REFRESH_TOKEN_EXPIRE_DAYS
+    )
+    to_encode.update({"exp": expire})
+    return jwt.encode(
+        to_encode,
+        settings.private_pem,
+        algorithm=settings.ALGORITHM,
+    )
 
 
 def verify_password(plain_password: str, hashed_password: str) -> bool:
@@ -97,11 +135,25 @@ def calculate_age(birth_date: date, today: date | None = None) -> int:
     return age
 
 
+def _issue_refresh_token(user_id: int, db: AsyncSession) -> str:
+    """Create and persist a refresh token for the given user."""
+    refresh_token_value = _create_refresh_token({"sub": str(user_id)})
+    refresh_token_record = RefreshToken(
+        id=str(uuid.uuid4()),
+        user_id=user_id,
+        token=refresh_token_value,
+        expires_at=datetime.now(timezone.utc)
+        + timedelta(days=settings.REFRESH_TOKEN_EXPIRE_DAYS),
+    )
+    db.add(refresh_token_record)
+    return refresh_token_value
+
+
 # --- Endpoints ---
 
 @router.post("/register", response_model=TokenResponse, status_code=status.HTTP_201_CREATED)
 async def register(req: RegisterRequest, db: AsyncSession = Depends(get_db)):
-    """Register a new user and return an access token.
+    """Register a new user and return access + refresh tokens.
 
     Requires date_of_birth and rejects users under 18.
     """
@@ -138,16 +190,26 @@ async def register(req: RegisterRequest, db: AsyncSession = Depends(get_db)):
         date_of_birth=dob,
     )
     db.add(user)
-    await db.commit()
+    await db.flush()  # flush to get user.id before creating refresh token
     await db.refresh(user)
 
+    # Create access token
     access_token = _create_access_token({"sub": str(user.id)})
-    return TokenResponse(access_token=access_token)
+
+    # Create and persist refresh token
+    refresh_token_value = _issue_refresh_token(user.id, db)
+    await db.commit()
+
+    return TokenResponse(
+        access_token=access_token,
+        refresh_token=refresh_token_value,
+        access_token_expires_minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES,
+    )
 
 
 @router.post("/login", response_model=TokenResponse)
 async def login(form: OAuth2PasswordRequestForm = Depends(), db: AsyncSession = Depends(get_db)):
-    """Authenticate user and return an access token.
+    """Authenticate user and return access + refresh tokens.
 
     Accepts form-encoded credentials (username/password) as expected by
     OAuth2PasswordBearer, so the Swagger UI "Authorize" flow works correctly.
@@ -167,8 +229,84 @@ async def login(form: OAuth2PasswordRequestForm = Depends(), db: AsyncSession =
             detail="User account is inactive",
         )
 
+    # Create access token
     access_token = _create_access_token({"sub": str(user.id)})
-    return TokenResponse(access_token=access_token)
+
+    # Create and persist refresh token
+    refresh_token_value = _issue_refresh_token(user.id, db)
+    await db.commit()
+
+    return TokenResponse(
+        access_token=access_token,
+        refresh_token=refresh_token_value,
+        access_token_expires_minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES,
+    )
+
+
+@router.post("/refresh", response_model=TokenResponse)
+async def refresh(req: RefreshRequest, db: AsyncSession = Depends(get_db)):
+    """Exchange a valid refresh token for a new access token.
+
+    Validates the refresh token against the database:
+    - Must exist in the refresh_tokens table
+    - Must not be expired (expires_at > now)
+    - Must be active (is_active == true)
+
+    On success, returns a new access token. The refresh token itself is
+    NOT rotated (the client keeps using the same refresh token).
+    """
+    credentials_exception = HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail="Invalid or expired refresh token",
+    )
+
+    # Step 1: Decode and validate the JWT signature/claims
+    try:
+        payload = jwt.decode(
+            req.refresh_token,
+            settings.public_pem,
+            algorithms=[settings.ALGORITHM],
+        )
+    except JWTError:
+        raise credentials_exception
+
+    user_id_str: str | None = payload.get("sub")
+    if user_id_str is None:
+        raise credentials_exception
+
+    try:
+        user_id = int(user_id_str)
+    except (ValueError, TypeError):
+        raise credentials_exception
+
+    # Step 2: Look up the refresh token in the database
+    result = await db.execute(
+        select(RefreshToken).where(
+            RefreshToken.token == req.refresh_token,
+            RefreshToken.user_id == user_id,
+        )
+    )
+    stored_token = result.scalar_one_or_none()
+
+    if stored_token is None:
+        raise credentials_exception
+
+    # Step 3: Check if the token is expired
+    if datetime.now(timezone.utc) >= stored_token.expires_at:
+        raise credentials_exception
+
+    # Step 4: Check if the token is active
+    if not stored_token.is_active:
+        raise credentials_exception
+
+    # Step 5: Issue a new access token
+    access_token = _create_access_token({"sub": str(user_id)})
+
+    return TokenResponse(
+        access_token=access_token,
+        refresh_token=req.refresh_token,  # Return the same refresh token
+        access_token_expires_minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES,
+    )
 
 
 @router.get("/me", response_model=UserResponse)

backend/requirements.txt

@@ -9,6 +9,14 @@ pydantic==2.10.3
 pydantic-settings==2.7.0
 python-jose[cryptography]==3.3.0
 passlib[bcrypt]==1.7.4
+# passlib 1.7.4 (last release, unmaintained since ~2020) detects its bcrypt
+# backend via bcrypt.__about__.__version__, which bcrypt>=4.1 removed --
+# hashing/verifying a password then raises "password cannot be longer than
+# 72 bytes" (a misleading downstream symptom of the real AttributeError:
+# module 'bcrypt' has no attribute '__about__') on every call. Without this
+# pin, `pip install -r requirements.txt` silently grabs whatever the latest
+# bcrypt is and breaks register/login outright. Pin below 4.1 explicitly.
+bcrypt==4.0.1
 python-multipart==0.0.20
 email-validator==2.2.0
 httpx==0.28.1

backend/tests/conftest.py

@@ -0,0 +1,38 @@
+"""Shared pytest fixtures.
+
+The auth integration tests hit the *real* Postgres database (per
+``DATABASE_URL``), so they persist data between runs.  Without cleanup a
+second run of the suite fails with 409 conflicts because the users it
+registered on the first run already exist.  The session-scoped fixture below
+truncates all application tables once before the first test, making the suite
+re-runnable.
+
+Truncation order doesn't strictly matter because ``CASCADE`` follows foreign
+keys, but the tables are listed explicitly for clarity.
+"""
+
+import asyncio
+
+import pytest
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import create_async_engine
+
+from app.config import settings
+
+TEST_TABLES = ("assets", "worlds", "sessions", "refresh_tokens", "users")
+
+
+@pytest.fixture(scope="session", autouse=True)
+def _reset_database():
+    """Truncate all application tables once per test session."""
+
+    async def _truncate() -> None:
+        engine = create_async_engine(settings.DATABASE_URL)
+        async with engine.begin() as conn:
+            await conn.execute(
+                text(f"TRUNCATE TABLE {', '.join(TEST_TABLES)} CASCADE")
+            )
+        await engine.dispose()
+
+    asyncio.run(_truncate())
+    yield

backend/tests/test_auth_endpoints.py

@@ -0,0 +1,263 @@
+"""Integration tests for the auth endpoints (register + login).
+
+These tests hit the real FastAPI app against the real configured database
+(DATABASE_URL -- Postgres via Alembic migrations in CI/dev, not an isolated
+in-memory DB), so they exercise the full stack: Pydantic validation → DB →
+JWT → response. Requires migrations already applied (alembic upgrade head)
+before running.
+"""
+
+import pytest
+from fastapi.testclient import TestClient
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+from sqlalchemy.pool import NullPool
+
+from app.config import settings
+from app.main import app
+from app.database import get_db
+from app.routers.auth import pwd_context
+
+
+# ---------------------------------------------------------------------------
+# Test fixtures
+# ---------------------------------------------------------------------------
+
+@pytest.fixture(autouse=True)
+def _override_db():
+    """Override get_db so the app uses a fresh session per test.
+
+    Deliberately does NOT reuse app.database's shared engine: FastAPI's
+    (sync) TestClient runs each request through anyio's blocking-portal
+    machinery, which can hand different requests different event loops.
+    asyncpg connections are bound to the loop they were created on, so
+    reusing one from the shared engine's connection pool across requests
+    raises "cannot perform operation: another operation is in progress" the
+    moment a test makes more than one request (register-then-login,
+    register-twice, etc.) -- confirmed this is the actual cause, not a bug
+    in the endpoints themselves. NullPool sidesteps it: every checkout is a
+    brand-new connection, never handed to a different loop than the one
+    that opened it.
+    """
+    test_engine = create_async_engine(settings.DATABASE_URL, poolclass=NullPool)
+    test_session_factory = async_sessionmaker(test_engine, expire_on_commit=False)
+
+    async def _get_db():
+        async_session = test_session_factory()
+        try:
+            yield async_session
+            await async_session.commit()
+        except Exception:
+            await async_session.rollback()
+            raise
+        finally:
+            await async_session.close()
+
+    app.dependency_overrides[get_db] = _get_db
+    yield
+    app.dependency_overrides.clear()
+
+
+# ---------------------------------------------------------------------------
+# Register endpoint
+# ---------------------------------------------------------------------------
+
+class TestRegister:
+    """Tests for POST /api/auth/register."""
+
+    def test_register_success(self):
+        """A valid registration returns 201 with a token."""
+        client = TestClient(app)
+        resp = client.post(
+            "/api/auth/register",
+            json={
+                "username": "newuser",
+                "email": "new@example.com",
+                "password": "secret123",
+                "date_of_birth": "2000-01-01",
+            },
+        )
+        assert resp.status_code == 201
+        data = resp.json()
+        assert "access_token" in data
+        assert data["token_type"] == "bearer"
+
+    def test_register_rejects_underage(self):
+        """Users under 18 get a 400 with a detail message."""
+        client = TestClient(app)
+        resp = client.post(
+            "/api/auth/register",
+            json={
+                "username": "kid",
+                "email": "kid@example.com",
+                "password": "secret123",
+                "date_of_birth": "2010-06-15",  # ~15 years old
+            },
+        )
+        assert resp.status_code == 400
+        assert "18 or older" in resp.json()["detail"]
+
+    def test_register_rejects_duplicate_username(self):
+        """Registering the same username twice returns 409."""
+        client = TestClient(app)
+        # First registration
+        client.post(
+            "/api/auth/register",
+            json={
+                "username": "duplicate",
+                "email": "dup1@example.com",
+                "password": "secret123",
+                "date_of_birth": "2000-01-01",
+            },
+        )
+        # Second registration with same username, different email
+        resp = client.post(
+            "/api/auth/register",
+            json={
+                "username": "duplicate",
+                "email": "dup2@example.com",
+                "password": "secret123",
+                "date_of_birth": "2000-01-01",
+            },
+        )
+        assert resp.status_code == 409
+        assert "Username already registered" in resp.json()["detail"]
+
+    def test_register_rejects_duplicate_email(self):
+        """Registering the same email twice returns 409."""
+        client = TestClient(app)
+        client.post(
+            "/api/auth/register",
+            json={
+                "username": "user1",
+                "email": "same@example.com",
+                "password": "secret123",
+                "date_of_birth": "2000-01-01",
+            },
+        )
+        resp = client.post(
+            "/api/auth/register",
+            json={
+                "username": "user2",
+                "email": "same@example.com",
+                "password": "secret123",
+                "date_of_birth": "2000-01-01",
+            },
+        )
+        assert resp.status_code == 409
+        assert "Email already registered" in resp.json()["detail"]
+
+    def test_register_invalid_date_format(self):
+        """Invalid date format returns 422 validation error."""
+        client = TestClient(app)
+        resp = client.post(
+            "/api/auth/register",
+            json={
+                "username": "user",
+                "email": "user@example.com",
+                "password": "secret123",
+                "date_of_birth": "01-01-2000",  # wrong format
+            },
+        )
+        assert resp.status_code == 422
+
+    def test_register_exactly_18(self):
+        """A user who just turned 18 can register."""
+        client = TestClient(app)
+        resp = client.post(
+            "/api/auth/register",
+            json={
+                "username": "just18",
+                "email": "just18@example.com",
+                "password": "secret123",
+                "date_of_birth": "2007-06-15",
+            },
+        )
+        assert resp.status_code == 201
+
+
+# ---------------------------------------------------------------------------
+# Login endpoint
+# ---------------------------------------------------------------------------
+
+class TestLogin:
+    """Tests for POST /api/auth/login."""
+
+    def _create_user(self, username: str, password: str, email: str = None):
+        """Helper to create a user via register."""
+        client = TestClient(app)
+        if email is None:
+            email = f"{username}@example.com"
+        resp = client.post(
+            "/api/auth/register",
+            json={
+                "username": username,
+                "email": email,
+                "password": password,
+                "date_of_birth": "2000-01-01",
+            },
+        )
+        assert resp.status_code == 201
+        return resp.json()["access_token"]
+
+    def test_login_success(self):
+        """Correct credentials return a token."""
+        self._create_user("loginuser", "correctpass")
+        client = TestClient(app)
+        resp = client.post(
+            "/api/auth/login",
+            data={"username": "loginuser", "password": "correctpass"},
+        )
+        assert resp.status_code == 200
+        data = resp.json()
+        assert "access_token" in data
+        assert data["token_type"] == "bearer"
+
+    def test_login_wrong_password(self):
+        """Wrong password returns 401."""
+        # Distinct username from test_login_success -- there's no per-test
+        # DB rollback/isolation here (real Postgres via the app's own
+        # dependency-overridden session), so reusing "loginuser" collided
+        # with the user that test already created (409 on register instead
+        # of the intended 401-on-login assertion this test is actually for).
+        self._create_user("loginuser_wrongpass", "correctpass")
+        client = TestClient(app)
+        resp = client.post(
+            "/api/auth/login",
+            data={"username": "loginuser_wrongpass", "password": "wrongpass"},
+        )
+        assert resp.status_code == 401
+        assert "Incorrect username or password" in resp.json()["detail"]
+
+    def test_login_nonexistent_user(self):
+        """Non-existent user returns 401 (not 404)."""
+        client = TestClient(app)
+        resp = client.post(
+            "/api/auth/login",
+            data={"username": "nobody", "password": "any"},
+        )
+        assert resp.status_code == 401
+        assert "Incorrect username or password" in resp.json()["detail"]
+
+    def test_login_accepts_form_encoded(self):
+        """Login accepts application/x-www-form-urlencoded (OAuth2)."""
+        self._create_user("formuser", "formpass")
+        client = TestClient(app)
+        resp = client.post(
+            "/api/auth/login",
+            data={"username": "formuser", "password": "formpass"},
+        )
+        assert resp.status_code == 200
+        assert "access_token" in resp.json()
+
+    def test_login_token_is_valid_jwt(self):
+        """The returned token is a valid JWT that can be decoded."""
+        self._create_user("jwttoken", "jwt123")
+        client = TestClient(app)
+        resp = client.post(
+            "/api/auth/login",
+            data={"username": "jwttoken", "password": "jwt123"},
+        )
+        token = resp.json()["access_token"]
+        # Verify it's a 3-part JWT
+        parts = token.split(".")
+        assert len(parts) == 3

backend/tests/test_auth_expired_token.py

@@ -0,0 +1,171 @@
+"""Tests for expired-token rejection across auth endpoints.
+
+Covers two distinct expiry paths:
+
+1. An *access* JWT whose ``exp`` claim is in the past must be rejected
+   with 401 by ``GET /api/auth/me`` (jose's built-in ``exp`` validation).
+2. A *refresh* token whose persisted ``expires_at`` is in the past must be
+   rejected with 401 by ``POST /api/auth/refresh`` even though its JWT
+   signature is still valid.
+
+Requires migrations already applied (alembic upgrade head) before running.
+"""
+
+import asyncio
+from datetime import datetime, timedelta, timezone
+
+import pytest
+from fastapi.testclient import TestClient
+from jose import jwt
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+from sqlalchemy.pool import NullPool
+
+from app.config import settings
+from app.main import app
+from app.database import get_db
+from app.models.session import RefreshToken
+
+
+# ---------------------------------------------------------------------------
+# Test fixtures
+# ---------------------------------------------------------------------------
+
+@pytest.fixture(autouse=True)
+def _override_db():
+    """Override get_db so the app uses a fresh session per test."""
+    test_engine = create_async_engine(settings.DATABASE_URL, poolclass=NullPool)
+    test_session_factory = async_sessionmaker(test_engine, expire_on_commit=False)
+
+    async def _get_db():
+        async_session = test_session_factory()
+        try:
+            yield async_session
+            await async_session.commit()
+        except Exception:
+            await async_session.rollback()
+            raise
+        finally:
+            await async_session.close()
+
+    app.dependency_overrides[get_db] = _get_db
+    yield
+    app.dependency_overrides.clear()
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _mint_access_token(exp: datetime) -> str:
+    """Mint an RS256 access token with an explicit ``exp`` claim."""
+    return jwt.encode(
+        {"sub": "1", "exp": exp},
+        settings.private_pem,
+        algorithm=settings.ALGORITHM,
+    )
+
+
+def _expire_refresh_token_in_db(token: str) -> None:
+    """Set the persisted refresh token's ``expires_at`` into the past."""
+
+    async def _do():
+        engine = create_async_engine(settings.DATABASE_URL, poolclass=NullPool)
+        session_factory = async_sessionmaker(engine, expire_on_commit=False)
+        async with session_factory() as session:
+            from sqlalchemy import update
+
+            await session.execute(
+                update(RefreshToken)
+                .where(RefreshToken.token == token)
+                .values(expires_at=datetime.now(timezone.utc) - timedelta(hours=1))
+            )
+            await session.commit()
+        await engine.dispose()
+
+    asyncio.run(_do())
+
+
+def _register_user(client: TestClient, username: str) -> str:
+    """Register a user and return its refresh token."""
+    resp = client.post(
+        "/api/auth/register",
+        json={
+            "username": username,
+            "email": f"{username}@example.com",
+            "password": "secret123",
+            "date_of_birth": "2000-01-01",
+        },
+    )
+    assert resp.status_code == 201
+    return resp.json()["refresh_token"]
+
+
+# ---------------------------------------------------------------------------
+# Expired access token (GET /api/auth/me)
+# ---------------------------------------------------------------------------
+
+class TestExpiredAccessToken:
+    def test_expired_access_token_is_rejected_by_me(self):
+        """An access JWT with a past exp claim returns 401 on /me."""
+        client = TestClient(app)
+        expired_token = _mint_access_token(
+            datetime.now(timezone.utc) - timedelta(minutes=5)
+        )
+        resp = client.get(
+            "/api/auth/me",
+            headers={"Authorization": f"Bearer {expired_token}"},
+        )
+        assert resp.status_code == 401
+        assert "Could not validate credentials" in resp.json()["detail"]
+
+    def test_garbage_access_token_is_rejected_by_me(self):
+        """A non-JWT bearer token returns 401 on /me."""
+        client = TestClient(app)
+        resp = client.get(
+            "/api/auth/me",
+            headers={"Authorization": "Bearer not-a-real-jwt"},
+        )
+        assert resp.status_code == 401
+
+    def test_missing_bearer_token_returns_401(self):
+        """No Authorization header at all returns 401 on /me."""
+        client = TestClient(app)
+        resp = client.get("/api/auth/me")
+        assert resp.status_code == 401
+
+
+# ---------------------------------------------------------------------------
+# Expired refresh token (POST /api/auth/refresh)
+# ---------------------------------------------------------------------------
+
+class TestExpiredRefreshToken:
+    def test_expired_refresh_token_is_rejected(self):
+        """A refresh token whose DB expires_at is in the past returns 401."""
+        client = TestClient(app)
+        refresh_token = _register_user(client, "expired_rt_user")
+
+        # Force the persisted record to be expired while its JWT signature
+        # is still valid.
+        _expire_refresh_token_in_db(refresh_token)
+
+        resp = client.post(
+            "/api/auth/refresh",
+            json={"refresh_token": refresh_token},
+        )
+        assert resp.status_code == 401
+        assert "Invalid or expired refresh token" in resp.json()["detail"]
+
+    def test_expired_refresh_token_jwt_is_rejected(self):
+        """A refresh JWT with a past exp claim is rejected before DB lookup."""
+        client = TestClient(app)
+        expired_jwt = jwt.encode(
+            {"sub": "1", "exp": datetime.now(timezone.utc) - timedelta(minutes=5)},
+            settings.private_pem,
+            algorithm=settings.ALGORITHM,
+        )
+        resp = client.post(
+            "/api/auth/refresh",
+            json={"refresh_token": expired_jwt},
+        )
+        assert resp.status_code == 401
+        assert "Invalid or expired refresh token" in resp.json()["detail"]

backend/tests/test_refresh_endpoint.py

@@ -0,0 +1,201 @@
+"""Tests for the POST /api/auth/refresh endpoint.
+
+These tests exercise the full stack: register → get refresh token →
+refresh → new access token.  Requires migrations already applied
+(alembic upgrade head) before running.
+"""
+
+import pytest
+from fastapi.testclient import TestClient
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+from sqlalchemy.pool import NullPool
+
+from app.config import settings
+from app.main import app
+from app.database import get_db
+
+
+# ---------------------------------------------------------------------------
+# Test fixtures
+# ---------------------------------------------------------------------------
+
+@pytest.fixture(autouse=True)
+def _override_db():
+    """Override get_db so the app uses a fresh session per test."""
+    test_engine = create_async_engine(settings.DATABASE_URL, poolclass=NullPool)
+    test_session_factory = async_sessionmaker(test_engine, expire_on_commit=False)
+
+    async def _get_db():
+        async_session = test_session_factory()
+        try:
+            yield async_session
+            await async_session.commit()
+        except Exception:
+            await async_session.rollback()
+            raise
+        finally:
+            await async_session.close()
+
+    app.dependency_overrides[get_db] = _get_db
+    yield
+    app.dependency_overrides.clear()
+
+
+# ---------------------------------------------------------------------------
+# Refresh endpoint tests
+# ---------------------------------------------------------------------------
+
+class TestRefresh:
+    """Tests for POST /api/auth/refresh."""
+
+    def _register_user(self, username: str, password: str, email: str = None):
+        """Helper to register a user and return the refresh token."""
+        client = TestClient(app)
+        if email is None:
+            email = f"{username}@example.com"
+        resp = client.post(
+            "/api/auth/register",
+            json={
+                "username": username,
+                "email": email,
+                "password": password,
+                "date_of_birth": "2000-01-01",
+            },
+        )
+        assert resp.status_code == 201
+        return resp.json()["refresh_token"]
+
+    def test_refresh_success(self):
+        """A valid refresh token returns a new access token."""
+        refresh_token = self._register_user("refep_refreshuser", "secret123")
+        client = TestClient(app)
+        resp = client.post(
+            "/api/auth/refresh",
+            json={"refresh_token": refresh_token},
+        )
+        assert resp.status_code == 200
+        data = resp.json()
+        assert "access_token" in data
+        assert data["token_type"] == "bearer"
+        # The refresh token in the response is the same one we sent
+        assert data["refresh_token"] == refresh_token
+
+    def test_refresh_returns_different_access_token(self):
+        """Refreshing produces a new access token (different from any previous)."""
+        refresh_token = self._register_user("refep_refreshtoken", "secret123")
+        client = TestClient(app)
+
+        # First refresh
+        resp1 = client.post(
+            "/api/auth/refresh",
+            json={"refresh_token": refresh_token},
+        )
+        assert resp1.status_code == 200
+        access_token_1 = resp1.json()["access_token"]
+
+        # Second refresh
+        resp2 = client.post(
+            "/api/auth/refresh",
+            json={"refresh_token": refresh_token},
+        )
+        assert resp2.status_code == 200
+        access_token_2 = resp2.json()["access_token"]
+
+        # Each refresh should produce a new access token
+        assert access_token_1 != access_token_2
+
+    def test_refresh_invalid_token(self):
+        """An invalid (garbage) refresh token returns 401."""
+        client = TestClient(app)
+        resp = client.post(
+            "/api/auth/refresh",
+            json={"refresh_token": "not.a.jwt.token"},
+        )
+        assert resp.status_code == 401
+        assert "Invalid or expired refresh token" in resp.json()["detail"]
+
+    def test_refresh_empty_body(self):
+        """Missing refresh_token field returns 422 validation error."""
+        client = TestClient(app)
+        resp = client.post(
+            "/api/auth/refresh",
+            json={},
+        )
+        assert resp.status_code == 422
+
+    def test_refresh_missing_field(self):
+        """No body at all returns 422."""
+        client = TestClient(app)
+        resp = client.post(
+            "/api/auth/refresh",
+            content="{}",
+            headers={"Content-Type": "application/json"},
+        )
+        assert resp.status_code == 422
+
+    def test_refresh_with_login_token(self):
+        """A refresh token obtained from login also works for /refresh."""
+        client = TestClient(app)
+        # Register first
+        client.post(
+            "/api/auth/register",
+            json={
+                "username": "refep_loginrefuser",
+                "email": "loginref@example.com",
+                "password": "secret123",
+                "date_of_birth": "2000-01-01",
+            },
+        )
+        # Login to get a refresh token
+        login_resp = client.post(
+            "/api/auth/login",
+            data={"username": "refep_loginrefuser", "password": "secret123"},
+        )
+        assert login_resp.status_code == 200
+        refresh_token = login_resp.json()["refresh_token"]
+
+        # Use it to refresh
+        resp = client.post(
+            "/api/auth/refresh",
+            json={"refresh_token": refresh_token},
+        )
+        assert resp.status_code == 200
+        assert "access_token" in resp.json()
+
+    def test_refresh_access_token_is_valid_jwt(self):
+        """The access token returned by /refresh is a valid JWT."""
+        from jose import jwt
+
+        refresh_token = self._register_user("refep_jwttoken", "secret123")
+        client = TestClient(app)
+        resp = client.post(
+            "/api/auth/refresh",
+            json={"refresh_token": refresh_token},
+        )
+        assert resp.status_code == 200
+        access_token = resp.json()["access_token"]
+
+        # Verify it's a 3-part JWT
+        parts = access_token.split(".")
+        assert len(parts) == 3
+
+        # Verify it decodes with the public key
+        payload = jwt.decode(
+            access_token,
+            settings.public_pem,
+            algorithms=[settings.ALGORITHM],
+        )
+        assert "sub" in payload
+        assert "exp" in payload
+
+    def test_refresh_expires_minutes_in_response(self):
+        """The response includes access_token_expires_minutes."""
+        refresh_token = self._register_user("refep_expiretest", "secret123")
+        client = TestClient(app)
+        resp = client.post(
+            "/api/auth/refresh",
+            json={"refresh_token": refresh_token},
+        )
+        assert resp.status_code == 200
+        assert "access_token_expires_minutes" in resp.json()
+        assert resp.json()["access_token_expires_minutes"] == settings.ACCESS_TOKEN_EXPIRE_MINUTES

backend/tests/test_refresh_token_jti.py

@@ -0,0 +1,79 @@
+"""Tests for refresh token uniqueness (jti claim) and model column length."""
+
+import uuid
+from datetime import datetime, timedelta, timezone
+
+import pytest
+from jose import jwt
+
+from app.config import settings
+from app.routers.auth import _create_refresh_token
+from app.models.session import RefreshToken
+
+
+class TestRefreshTokenJtiUniqueness:
+    """Verify that _create_refresh_token produces unique tokens even when
+    called with identical data in rapid succession (issue #1 from review)."""
+
+    def test_two_calls_produce_different_tokens(self):
+        """Two calls with the same sub produce different JWTs because of jti."""
+        token_a = _create_refresh_token({"sub": "42"})
+        token_b = _create_refresh_token({"sub": "42"})
+        assert token_a != token_b
+
+    def test_jti_is_valid_uuid(self):
+        """The jti claim inside the refresh token is a valid UUID."""
+        token = _create_refresh_token({"sub": "1"})
+        payload = jwt.decode(
+            token,
+            settings.public_pem,
+            algorithms=[settings.ALGORITHM],
+        )
+        assert "jti" in payload
+        # Verify it parses as a UUID (raises ValueError if not)
+        uuid.UUID(payload["jti"])
+
+    def test_each_token_has_unique_jti(self):
+        """Generate 100 tokens for the same user — all jtis must differ."""
+        jtis = set()
+        for _ in range(100):
+            token = _create_refresh_token({"sub": "999"})
+            payload = jwt.decode(
+                token,
+                settings.public_pem,
+                algorithms=[settings.ALGORITHM],
+            )
+            jtis.add(payload["jti"])
+        assert len(jtis) == 100
+
+    def test_jti_survives_decode(self):
+        """The jti claim is present and correct after decode."""
+        token = _create_refresh_token({"sub": "7"})
+        payload = jwt.decode(
+            token,
+            settings.public_pem,
+            algorithms=[settings.ALGORITHM],
+        )
+        assert payload["sub"] == "7"
+        assert "jti" in payload
+        assert "exp" in payload
+
+
+class TestRefreshTokenModelColumnLength:
+    """Verify the model's token column length matches the migration (issue #2)."""
+
+    def test_token_column_has_length_512(self):
+        """RefreshToken.token column should be String(512), not unbounded."""
+        from sqlalchemy import inspect
+
+        # Get the column definition from the model's table
+        column = RefreshToken.__table__.columns["token"]
+        # The type should be String with length 512
+        assert column.type.length == 512
+
+    def test_token_column_type_is_string(self):
+        """The token column should be a String type."""
+        from sqlalchemy import String as SAString
+
+        column = RefreshToken.__table__.columns["token"]
+        assert isinstance(column.type, SAString)

export_presets.cfg

@@ -0,0 +1,74 @@
+[preset.0]
+
+name="Linux"
+platform="Linux/X11"
+runnable=true
+advanced_options=false
+dedicated_server=false
+custom_features=""
+export_filter="all_resources"
+include_filter=""
+exclude_filter=""
+export_path="export/linux/agp-game.x86_64"
+encryption_include_filters=""
+encryption_exclude_filters=""
+encrypt_pck=false
+encrypt_directory=false
+script_export_mode=2
+
+[preset.0.options]
+
+custom_template/debug=""
+custom_template/release=""
+debug/export_console_wrapper=1
+binary_format/embed_pck=false
+texture_format/bptc=true
+texture_format/s3tc=true
+texture_format/etc=false
+texture_format/etc2=false
+binary_format/architecture="x86_64"
+ssh_remote_deploy/enabled=false
+
+[preset.1]
+
+name="Windows Desktop"
+platform="Windows Desktop"
+runnable=true
+advanced_options=false
+dedicated_server=false
+custom_features=""
+export_filter="all_resources"
+include_filter=""
+exclude_filter=""
+export_path="export/windows/agp-game.exe"
+encryption_include_filters=""
+encryption_exclude_filters=""
+encrypt_pck=false
+encrypt_directory=false
+script_export_mode=2
+
+[preset.1.options]
+
+custom_template/debug=""
+custom_template/release=""
+debug/export_console_wrapper=1
+binary_format/embed_pck=false
+texture_format/bptc=true
+texture_format/s3tc=true
+texture_format/etc=false
+texture_format/etc2=false
+binary_format/architecture="x86_64"
+codesign/enable=false
+application/icon=""
+application/console_wrapper_icon=""
+application/icon_interpolation=4
+application/file_version=""
+application/product_version=""
+application/company_name=""
+application/product_name=""
+application/file_description=""
+application/copyright=""
+application/trademarks=""
+application/export_angle=0
+application/export_d3d12=0
+d3d12/agility_sdk_multizip=0

project.godot

@@ -9,9 +9,12 @@ config_version=5
 config/name="AGP-Game"
 run/main_scene="res://scenes/main_menu.tscn"
 config/features=PackedStringArray("4.6.2")
+agp/api_base_url="http://127.0.0.1:8000"
 
 [autoload]
 
+ApiClient="*res://scripts/api_client.gd"
+
 [display]
 
 window/size/viewport_width=1920

scenes/main_menu.tscn

@@ -1,4 +1,4 @@
-[gd_scene load_steps=2 format=3]
+[gd_scene load_steps=2 format=3 uid="uid://main_menu_scene"]
 
 [ext_resource type="Script" path="res://scripts/main_menu.gd" id="1_main"]
 
@@ -29,6 +29,73 @@ text = "AGP Game"
 horizontal_alignment = 1
 theme_override_font_sizes/font_size = 72
 
+[node name="AuthPanel" type="PanelContainer" parent="CenterContainer/VBoxContainer"]
+layout_mode = 1
+visible = false
+
+[node name="MarginContainer" type="MarginContainer" parent="CenterContainer/VBoxContainer/AuthPanel"]
+layout_mode = 1
+theme_override_constants/margin_left = 24
+theme_override_constants/margin_top = 24
+theme_override_constants/margin_right = 24
+theme_override_constants/margin_bottom = 24
+
+[node name="AuthVBox" type="VBoxContainer" parent="CenterContainer/VBoxContainer/AuthPanel/MarginContainer"]
+layout_mode = 1
+theme_override_constants/separation = 8
+size_flags_horizontal = 3
+
+[node name="AuthModeLabel" type="Label" parent="CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox"]
+layout_mode = 1
+text = "Login"
+horizontal_alignment = 1
+theme_override_font_sizes/font_size = 24
+
+[node name="UsernameEdit" type="LineEdit" parent="CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox"]
+layout_mode = 1
+placeholder_text = "Username"
+size_flags_horizontal = 3
+
+[node name="PasswordEdit" type="LineEdit" parent="CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox"]
+layout_mode = 1
+placeholder_text = "Password"
+size_flags_horizontal = 3
+echo_password = true
+
+[node name="EmailEdit" type="LineEdit" parent="CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox"]
+layout_mode = 1
+visible = false
+placeholder_text = "Email"
+size_flags_horizontal = 3
+
+[node name="DOBEdit" type="LineEdit" parent="CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox"]
+layout_mode = 1
+visible = false
+placeholder_text = "Date of Birth (YYYY-MM-DD)"
+size_flags_horizontal = 3
+
+[node name="ModeToggle" type="CheckButton" parent="CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox"]
+layout_mode = 1
+text = "Register"
+
+[node name="AuthButton" type="Button" parent="CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox"]
+layout_mode = 1
+text = "Login"
+size_flags_horizontal = 3
+
+[node name="AuthStatusLabel" type="Label" parent="CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox"]
+layout_mode = 1
+text = ""
+horizontal_alignment = 1
+autowrap_mode = 2
+visible = false
+
+[node name="WelcomeLabel" type="Label" parent="CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox"]
+layout_mode = 1
+visible = false
+text = ""
+horizontal_alignment = 1
+
 [node name="PlayButton" type="Button" parent="CenterContainer/VBoxContainer"]
 layout_mode = 1
 text = "Play"
@@ -41,3 +108,7 @@ size_flags_horizontal = 4
 
 [connection signal="pressed" from="CenterContainer/VBoxContainer/PlayButton" to="." method="_on_play_button_pressed"]
 [connection signal="pressed" from="CenterContainer/VBoxContainer/QuitButton" to="." method="_on_quit_button_pressed"]
+[connection signal="toggled" from="CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/ModeToggle" to="." method="_on_mode_toggle_toggled"]
+[connection signal="pressed" from="CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/AuthButton" to="." method="_on_auth_button_pressed"]
+[connection signal="text_submitted" from="CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/UsernameEdit" to="." method="_on_auth_button_pressed"]
+[connection signal="text_submitted" from="CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/PasswordEdit" to="." method="_on_auth_button_pressed"]

scripts/api_client.gd

@@ -0,0 +1,292 @@
+extends Node
+## Central HTTP client singleton (autoload name: "ApiClient").
+##
+## Every network call in the game flows through this class. Callers use the
+## high-level helpers ([method login], [method register], [method get_worlds],
+## [method health_check], [method get_me]) or the generic [method request]
+## primitive. All results conform to the result-dictionary contract below.
+##
+## [b]Result Dictionary Contract[/b]
+## Every public method returns (after `await`) a Dictionary with this shape:
+##
+##     {
+##         "ok":     bool,     # true for HTTP 2xx, false otherwise
+##         "status": int,      # HTTP status code (0 on network failure)
+##         "data":   Variant,  # parsed JSON body on success (null otherwise)
+##         "detail": String,   # human-readable message
+##     }
+##
+## Network failures (timeout / DNS / refused connection) return `status == 0`
+## with a `detail` describing the transport failure. Non-2xx responses return
+## the real HTTP status and the backend's `detail` field from the JSON error
+## body when present. No caller can crash on a failed request.
+##
+## [b]Token storage[/b]
+## JWTs are kept in memory. [method set_token] is the single seam for future
+## disk persistence (override it to save to `user://`).
+##
+## [b]Usage[/b]
+##     var result: Dictionary = await ApiClient.login("alice", "secret")
+##     if result.ok:
+##         print("Logged in!")
+##     else:
+##         print("Error: ", result.detail)
+
+# ---------------------------------------------------------------------------
+# Token storage
+# ---------------------------------------------------------------------------
+
+var _access_token: String = ""
+var _token_type: String = "Bearer"
+
+## Full Authorization header value, e.g. "Bearer eyJ...". Empty if no token.
+var bearer_token: String:
+	get:
+		return _token_type + " " + _access_token if _access_token != "" else ""
+
+
+## Whether an access token is currently stored.
+func has_token() -> bool:
+	return _access_token != ""
+
+
+## Set the access token (called after login / register / token refresh).
+## This is the persistence seam: override to also write to disk.
+func set_token(access_token: String, token_type: String = "Bearer") -> void:
+	_access_token = access_token
+	_token_type = token_type
+
+
+## Clear stored tokens.
+func clear_token() -> void:
+	_access_token = ""
+	_token_type = "Bearer"
+
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+var _base_url: String = "http://127.0.0.1:8000"
+
+## Request timeout in seconds. 0 disables the timeout.
+var timeout_seconds: float = 10.0
+
+
+func _ready() -> void:
+	# Environment variable override (e.g. for headless smoke tests against a
+	# backend on a non-default port). Falls back to the ProjectSetting, then
+	# to the documented default.
+	var env_url := OS.get_environment("AGP_API_BASE_URL")
+	if env_url != "":
+		_base_url = env_url.rstrip("/")
+	else:
+		_base_url = str(ProjectSettings.get_setting(
+			"application/agp/api_base_url",
+			"http://127.0.0.1:8000"
+		)).rstrip("/")
+
+
+# ---------------------------------------------------------------------------
+# Core request primitive
+# ---------------------------------------------------------------------------
+
+## Generic request primitive. Awaitable via `await`.
+##
+## Uses a dedicated HTTPRequest node per call so concurrent requests can never
+## cross-talk, and so the result maps 1:1 to the awaiting caller.
+##
+## @param method       HTTPClient.Method enum value (GET/POST/PUT/PATCH/DELETE).
+## @param path         URL path, e.g. "/api/health".
+## @param body         Request body string (JSON or form-encoded).
+## @param content_type "application/json" or "application/x-www-form-urlencoded".
+## @param require_auth If true, attach the stored bearer token when present.
+## @return Result dictionary conforming to the contract.
+func request(
+	method: HTTPClient.Method,
+	path: String,
+	body: String = "",
+	content_type: String = "application/json",
+	require_auth: bool = false
+) -> Dictionary:
+	var http := HTTPRequest.new()
+	http.timeout = timeout_seconds
+	http.max_redirects = 8
+	http.accept_gzip = true
+	add_child(http)
+
+	var headers := PackedStringArray()
+	headers.append("Accept: application/json")
+	if content_type != "":
+		headers.append("Content-Type: " + content_type)
+	if require_auth and has_token():
+		headers.append("Authorization: " + bearer_token)
+
+	var url := _base_url + path
+	var err := http.request(url, headers, method, body)
+	if err != OK:
+		http.queue_free()
+		return _make_result(false, 0, null, "Failed to start request: " + _error_string(err))
+
+	# request_completed emits (result, response_code, headers, body).
+	var args: Array = await http.request_completed
+	var result_code: int = args[0]
+	var response_code: int = args[1]
+	var response_body: PackedByteArray = args[3]
+	http.queue_free()
+
+	# Transport-level failure (timeout / DNS / refused / TLS, etc.).
+	if result_code != HTTPRequest.RESULT_SUCCESS:
+		return _make_result(false, 0, null, _transport_error_detail(result_code))
+
+	# Server accepted the connection but returned no HTTP status line.
+	if response_code == 0:
+		return _make_result(false, 0, null, "No response received from server.")
+
+	var json_string := response_body.get_string_from_utf8()
+	var ok := response_code >= 200 and response_code < 300
+
+	if ok:
+		var data: Variant = _parse_json(json_string)
+		return _make_result(true, response_code, data, "OK")
+
+	# Non-2xx: surface the backend's "detail" message when available.
+	var detail := "HTTP error %d" % response_code
+	var parsed: Variant = _parse_json(json_string)
+	if parsed is Dictionary and (parsed as Dictionary).has("detail"):
+		detail = str((parsed as Dictionary)["detail"])
+	return _make_result(false, response_code, null, detail)
+
+
+# ---------------------------------------------------------------------------
+# High-level helpers
+# ---------------------------------------------------------------------------
+
+## Log in with username/password (OAuth2PasswordRequestForm).
+## On success stores the returned access token.
+func login(username: String, password: String) -> Dictionary:
+	var form := "username=" + username.uri_encode() + "&password=" + password.uri_encode()
+	var result := await request(
+		HTTPClient.METHOD_POST,
+		"/api/auth/login",
+		form,
+		"application/x-www-form-urlencoded",
+		false
+	)
+	_store_token_from_result(result)
+	return result
+
+
+## Register a new user. On success stores the returned access token.
+## @param date_of_birth ISO date string "YYYY-MM-DD".
+func register(
+	username: String,
+	email: String,
+	password: String,
+	date_of_birth: String
+) -> Dictionary:
+	var payload := {
+		"username": username,
+		"email": email,
+		"password": password,
+		"date_of_birth": date_of_birth,
+	}
+	var result := await request(
+		HTTPClient.METHOD_POST,
+		"/api/auth/register",
+		JSON.stringify(payload),
+		"application/json",
+		false
+	)
+	_store_token_from_result(result)
+	return result
+
+
+## List worlds visible to the current user (requires auth).
+## @param visibility Optional filter: "public", "private", "friends_only".
+func get_worlds(skip: int = 0, limit: int = 50, visibility: String = "") -> Dictionary:
+	var path := "/api/worlds/?skip=%d&limit=%d" % [skip, limit]
+	if visibility != "":
+		path += "&visibility=" + visibility.uri_encode()
+	return await request(HTTPClient.METHOD_GET, path, "", "application/json", true)
+
+
+## Ping the backend health endpoint (no auth).
+func health_check() -> Dictionary:
+	return await request(HTTPClient.METHOD_GET, "/api/health", "", "application/json", false)
+
+
+## Fetch the current user's profile from the stored JWT (requires auth).
+func get_me() -> Dictionary:
+	return await request(HTTPClient.METHOD_GET, "/api/users/me", "", "application/json", true)
+
+
+# ---------------------------------------------------------------------------
+# Internals
+# ---------------------------------------------------------------------------
+
+func _store_token_from_result(result: Dictionary) -> void:
+	if result.ok and result.data is Dictionary:
+		var token: String = str((result.data as Dictionary).get("access_token", ""))
+		if token != "":
+			set_token(token)
+
+
+func _parse_json(text: String) -> Variant:
+	if text == "":
+		return null
+	var parsed: Variant = JSON.parse_string(text)
+	if parsed == null:
+		# null is ambiguous (valid JSON "null" vs parse failure). Fall back to
+		# the raw string so callers never lose the body entirely.
+		return text if text != "null" else null
+	return parsed
+
+
+func _make_result(ok: bool, status: int, data: Variant, detail: String) -> Dictionary:
+	return {
+		"ok": ok,
+		"status": status,
+		"data": data,
+		"detail": detail,
+	}
+
+
+func _transport_error_detail(result_code: int) -> String:
+	match result_code:
+		HTTPRequest.RESULT_CANT_CONNECT:
+			return "Could not connect to server. Is it running?"
+		HTTPRequest.RESULT_CANT_RESOLVE:
+			return "Could not resolve server hostname."
+		HTTPRequest.RESULT_CONNECTION_ERROR:
+			return "Connection error."
+		HTTPRequest.RESULT_TLS_HANDSHAKE_ERROR:
+			return "TLS handshake failed."
+		HTTPRequest.RESULT_NO_RESPONSE:
+			return "No response from server."
+		HTTPRequest.RESULT_BODY_SIZE_LIMIT_EXCEEDED:
+			return "Response body too large."
+		HTTPRequest.RESULT_BODY_DECOMPRESS_FAILED:
+			return "Failed to decompress response body."
+		HTTPRequest.RESULT_REQUEST_FAILED:
+			return "Request failed."
+		HTTPRequest.RESULT_TIMEOUT:
+			return "Request timed out."
+		_:
+			return "Network error (code %d)." % result_code
+
+
+func _error_string(err_code: int) -> String:
+	match err_code:
+		OK:
+			return "OK"
+		ERR_UNCONFIGURED:
+			return "HTTPRequest not configured (not in tree)."
+		ERR_BUSY:
+			return "HTTPRequest is busy with a previous request."
+		ERR_INVALID_PARAMETER:
+			return "Invalid URL format."
+		ERR_CANT_CONNECT:
+			return "Cannot connect to host."
+		_:
+			return "Unknown error (%d)." % err_code

scripts/build.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# Headless CI export for Linux and Windows.
+#
+# Requires:
+#   - Godot 4.6.2 (the exact version this project + export_presets.cfg were
+#     built against; a different Godot minor version's export templates are
+#     not guaranteed compatible)
+#   - The matching export templates installed at
+#     ~/.local/share/godot/export_templates/4.6.2.stable/
+#     (download: https://godotengine.org/download/archive/4.6.2-stable/,
+#     "Export templates" -- NOT the same as the editor download)
+#   - godot on PATH (or set GODOT_BIN below)
+#
+# Usage: scripts/build.sh
+# Output: export/linux/agp-game.x86_64, export/windows/agp-game.exe
+
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+GODOT_BIN="${GODOT_BIN:-godot}"
+if ! command -v "$GODOT_BIN" >/dev/null 2>&1; then
+    if [ -x "$HOME/godot/godot" ]; then
+        GODOT_BIN="$HOME/godot/godot"
+    else
+        echo "godot binary not found (checked PATH and ~/godot/godot)." >&2
+        exit 1
+    fi
+fi
+
+echo "Godot version: $("$GODOT_BIN" --version)"
+
+mkdir -p export/linux export/windows
+
+echo "=== Exporting Linux/X11 ==="
+"$GODOT_BIN" --headless --path . --export-release "Linux" export/linux/agp-game.x86_64
+
+echo "=== Exporting Windows Desktop ==="
+"$GODOT_BIN" --headless --path . --export-release "Windows Desktop" export/windows/agp-game.exe
+
+echo ""
+echo "Build artifacts:"
+ls -la export/linux export/windows

scripts/main_menu.gd

@@ -1,14 +1,211 @@
 extends Control
+## Main menu with login/register UI wired to the backend auth API.
+##
+## The AuthPanel is hidden by default. When the user clicks "Login" or "Register"
+## (the existing Play/Quit buttons), the auth panel slides in. The ModeToggle
+## switches between Login and Register modes, showing/hiding the email and DOB
+## fields accordingly.
+##
+## On successful auth the token is stored via ApiClient, the welcome label
+## shows the username, and the Play button becomes enabled.
 
 
-func _ready():
+# ── UI references ────────────────────────────────────────────────────────────
-	pass
+
+var _auth_panel: PanelContainer
+var _auth_mode_label: Label
+var _username_edit: LineEdit
+var _password_edit: LineEdit
+var _email_edit: LineEdit
+var _dob_edit: LineEdit
+var _mode_toggle: CheckButton
+var _auth_button: Button
+var _status_label: Label
+var _welcome_label: Label
+var _play_button: Button
+var _quit_button: Button
+
+var _is_register_mode: bool = false
+var _is_authenticating: bool = false
 
 
-func _on_play_button_pressed():
+# ── Lifecycle ────────────────────────────────────────────────────────────────
-	# No gameplay scene exists yet — wire this to the real scene once one lands.
+
-	print("Play pressed — no gameplay scene yet")
+func _ready() -> void:
+	# Cache node references.
+	_auth_panel = $CenterContainer/VBoxContainer/AuthPanel
+	_auth_mode_label = $CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/AuthModeLabel
+	_username_edit = $CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/UsernameEdit
+	_password_edit = $CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/PasswordEdit
+	_email_edit = $CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/EmailEdit
+	_dob_edit = $CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/DOBEdit
+	_mode_toggle = $CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/ModeToggle
+	_auth_button = $CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/AuthButton
+	_status_label = $CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/AuthStatusLabel
+	_welcome_label = $CenterContainer/VBoxContainer/AuthPanel/MarginContainer/AuthVBox/WelcomeLabel
+	_play_button = $CenterContainer/VBoxContainer/PlayButton
+	_quit_button = $CenterContainer/VBoxContainer/QuitButton
+
+	# Initial state.
+	_auth_panel.visible = false
+	_status_label.visible = false
+	_welcome_label.visible = false
+	_email_edit.visible = false
+	_dob_edit.visible = false
+	_play_button.disabled = true  # Gate play behind successful auth.
+	_update_auth_mode_ui()
 
 
-func _on_quit_button_pressed():
+# ── Play / Quit ──────────────────────────────────────────────────────────────
+
+func _on_play_button_pressed() -> void:
+	if _play_button.disabled:
+		return
+	# TODO: transition to the worlds / gameplay scene once it exists.
+	print("Play pressed — transitioning to game")
+
+
+func _on_quit_button_pressed() -> void:
 	get_tree().quit()
+
+
+# ── Auth panel toggle ────────────────────────────────────────────────────────
+
+func _on_login_button_pressed() -> void:
+	"""Show the auth panel (called from a future Login button on the main menu)."""
+	_auth_panel.visible = true
+	_auth_panel.grab_focus()
+
+
+func _on_register_button_pressed() -> void:
+	"""Show the auth panel in register mode."""
+	_auth_panel.visible = true
+	_is_register_mode = true
+	_mode_toggle.button_pressed = true
+	_update_auth_mode_ui()
+	_clear_status()
+
+
+# ── Mode toggle (Login / Register) ───────────────────────────────────────────
+
+func _on_mode_toggle_toggled(button_pressed: bool) -> void:
+	_is_register_mode = button_pressed
+	_update_auth_mode_ui()
+	_clear_status()
+
+
+func _update_auth_mode_ui() -> void:
+	"""Update labels and field visibility based on login vs register mode."""
+	if _is_register_mode:
+		_auth_mode_label.text = "Register"
+		_auth_button.text = "Register"
+		_email_edit.visible = true
+		_dob_edit.visible = true
+	else:
+		_auth_mode_label.text = "Login"
+		_auth_button.text = "Login"
+		_email_edit.visible = false
+		_dob_edit.visible = false
+
+
+# ── Auth submission ──────────────────────────────────────────────────────────
+
+func _on_auth_button_pressed() -> void:
+	"""Handle login or register button press."""
+	if _is_authenticating:
+		return
+
+	# Validate inputs.
+	var username := _username_edit.text.strip_edges()
+	var password := _password_edit.text
+
+	if username == "":
+		_show_status("Username is required.")
+		return
+	if password == "":
+		_show_status("Password is required.")
+		return
+
+	if _is_register_mode:
+		var email := _email_edit.text.strip_edges()
+		var dob := _dob_edit.text.strip_edges()
+
+		if email == "":
+			_show_status("Email is required.")
+			return
+		if dob == "":
+			_show_status("Date of birth is required.")
+			return
+		# Basic YYYY-MM-DD format check.
+		if not _is_valid_date(dob):
+			_show_status("Date of birth must be in YYYY-MM-DD format.")
+			return
+
+		_auth_button.disabled = true
+		_auth_button.text = "Registering..."
+		_is_authenticating = true
+		_clear_status()
+
+		var result := await ApiClient.register(username, email, password, dob)
+		_on_auth_complete(result)
+	else:
+		_auth_button.disabled = true
+		_auth_button.text = "Logging in..."
+		_is_authenticating = true
+		_clear_status()
+
+		var result := await ApiClient.login(username, password)
+		_on_auth_complete(result)
+
+
+func _on_auth_complete(result: Dictionary) -> void:
+	"""Handle the result of a login or register call."""
+	_auth_button.disabled = false
+	_auth_button.text = "Register" if _is_register_mode else "Login"
+	_is_authenticating = false
+
+	if result.ok:
+		# Success — show welcome, enable Play.
+		_welcome_label.text = "Welcome, %s!" % _username_edit.text.strip_edges()
+		_welcome_label.visible = true
+		_status_label.visible = false
+		_play_button.disabled = false
+		print("Auth successful. Token stored.")
+	else:
+		# Failure — show backend error detail.
+		_show_status(result.detail)
+
+
+# ── Status helpers ───────────────────────────────────────────────────────────
+
+func _show_status(message: String) -> void:
+	_status_label.text = message
+	_status_label.visible = true
+
+
+func _clear_status() -> void:
+	_status_label.text = ""
+	_status_label.visible = false
+
+
+# ── Validation ───────────────────────────────────────────────────────────────
+
+func _is_valid_date(date_str: String) -> bool:
+	"""Check if a string looks like a valid YYYY-MM-DD date."""
+	if date_str.length() != 10:
+		return false
+	var parts := date_str.split("-")
+	if parts.size() != 3:
+		return false
+	var year := parts[0].to_int()
+	var month := parts[1].to_int()
+	var day := parts[2].to_int()
+	if month < 1 or month > 12:
+		return false
+	if day < 1 or day > 31:
+		return false
+	# Rough month-day validation.
+	var days_in_month := [0, 31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31]
+	if day > days_in_month[month]:
+		return false
+	return true

scripts/smoke_test_api.gd

@@ -0,0 +1,46 @@
+extends SceneTree
+## Headless smoke test for the ApiClient autoload.
+##
+## Run with:
+##     godot --headless --path . --script res://scripts/smoke_test_api.gd
+##
+## Requires the backend to be running (default base URL
+## `application/agp/api_base_url` -> http://127.0.0.1:8000).
+##
+## Calls the real autoload's `health_check()` (which exercises the generic
+## `request()` primitive) and exits 0 on a `status == "ok"` response, 1
+## otherwise. This script is intentionally NOT wired into any game scene.
+
+
+func _initialize() -> void:
+	_run()
+
+
+func _run() -> void:
+	# _initialize() fires before the SceneTree has processed its first frame,
+	# so a freshly add_child()'d HTTPRequest node isn't reliably considered
+	# "inside tree" yet (request_raw fails with !is_inside_tree()). One frame
+	# of delay is enough; this only matters for --script mode, not a real
+	# running game.
+	await process_frame
+
+	# Godot's --script/SceneTree runner doesn't resolve autoload singletons
+	# as bare global identifiers at compile time (the node exists at
+	# runtime -- root.has_node("ApiClient") is true -- but referencing it as
+	# a plain identifier fails with "Identifier not found: ApiClient" during
+	# script compilation). get_node sidesteps compile-time resolution
+	# entirely. This only affects --script mode; a real game scene resolves
+	# the bare autoload name normally.
+	var api_client := root.get_node("ApiClient")
+	print("SMOKE: calling ApiClient.health_check() ...")
+	var result: Dictionary = await api_client.health_check()
+	print("SMOKE: result = ", result)
+
+	if result.ok \
+			and result.data is Dictionary \
+			and str((result.data as Dictionary).get("status", "")) == "ok":
+		print("SMOKE RESULT: PASS (status=ok)")
+		quit(0)
+	else:
+		printerr("SMOKE RESULT: FAIL")
+		quit(1)

scripts/smoke_test_auth.gd

@@ -0,0 +1,133 @@
+extends SceneTree
+## Headless smoke test for the AuthPanel login/register flow.
+##
+## Run with:
+##     godot --headless --path . --script res://scripts/smoke_test_auth.gd
+##
+## Requires the backend to be running (default base URL
+## `application/agp/api_base_url` -> http://127.0.0.1:8000).
+##
+## Tests:
+##   1. Register a unique user → 201 + token stored.
+##   2. Register the same user again → 409 "Username already registered".
+##   3. Register an under-18 user → 400 "Must be 18 or older".
+##   4. Login with correct credentials → 200 + token stored.
+##   5. Login with wrong password → 401 "Incorrect username or password".
+##   6. Login with non-existent user → 401 "Incorrect username or password".
+##
+## Exits 0 on full pass, 1 on any failure.
+
+const API_BASE := "http://127.0.0.1:8000"
+const TEST_USERNAME := "smoke_test_user_%d"
+const TEST_EMAIL := "smoke_%d@test.example.com"
+const TEST_PASSWORD := "SmokeTest123!"
+const TEST_DOB_ADULT := "2000-01-01"
+const TEST_DOB_CHILD := "2020-01-01"  # ~5 years old
+
+
+func _initialize() -> void:
+	_run()
+
+
+func _run() -> void:
+	# Wait for autoloads to be ready.
+	await process_frame
+
+	var api := root.get_node("ApiClient") as ApiClient
+	assert(api != null, "ApiClient autoload not found")
+
+	var passed: int = 0
+	var failed: int = 0
+
+	# --- Test 1: Register a unique user ---
+	var unique_id := Time.get_ticks_msec()
+	var username := "smoke_%d" % unique_id
+	var email := "smoke_%d@test.example.com" % unique_id
+
+	print("\n=== Test 1: Register unique user ===")
+	var result := await api.register(username, email, TEST_PASSWORD, TEST_DOB_ADULT)
+	if _check("register returns ok", result.ok) \
+			and _check("register status is 201", result.status == 201) \
+			and _check("register stores token", api.has_token()):
+		passed += 1
+	else:
+		failed += 1
+		print("  detail: ", result.detail)
+
+	# --- Test 2: Register same user again (duplicate) ---
+	print("\n=== Test 2: Duplicate username ===")
+	result = await api.register(username, email, TEST_PASSWORD, TEST_DOB_ADULT)
+	if _check("duplicate register not ok", not result.ok) \
+			and _check("duplicate status is 409", result.status == 409) \
+			and _check("duplicate detail mentions username",
+					"username" in result.detail.to_lower()):
+		passed += 1
+	else:
+		failed += 1
+		print("  detail: ", result.detail)
+
+	# --- Test 3: Register under-18 user ---
+	print("\n=== Test 3: Under-18 registration ===")
+	var child_username := "child_%d" % unique_id
+	var child_email := "child_%d@test.example.com" % unique_id
+	result = await api.register(child_username, child_email, TEST_PASSWORD, TEST_DOB_CHILD)
+	if _check("under-18 register not ok", not result.ok) \
+			and _check("under-18 status is 400", result.status == 400) \
+			and _check("under-18 detail mentions age",
+					"18" in result.detail):
+		passed += 1
+	else:
+		failed += 1
+		print("  detail: ", result.detail)
+
+	# --- Test 4: Login with correct credentials ---
+	print("\n=== Test 4: Correct login ===")
+	result = await api.login(username, TEST_PASSWORD)
+	if _check("login returns ok", result.ok) \
+			and _check("login status is 200", result.status == 200) \
+			and _check("login stores token", api.has_token()):
+		passed += 1
+	else:
+		failed += 1
+		print("  detail: ", result.detail)
+
+	# --- Test 5: Login with wrong password ---
+	print("\n=== Test 5: Wrong password ===")
+	result = await api.login(username, "WrongPassword!")
+	if _check("wrong pwd login not ok", not result.ok) \
+			and _check("wrong pwd status is 401", result.status == 401) \
+			and _check("wrong pwd detail",
+					"Incorrect" in result.detail or "incorrect" in result.detail):
+		passed += 1
+	else:
+		failed += 1
+		print("  detail: ", result.detail)
+
+	# --- Test 6: Login with non-existent user ---
+	print("\n=== Test 6: Non-existent user ===")
+	result = await api.login("nonexistent_user_xyz", TEST_PASSWORD)
+	if _check("missing user login not ok", not result.ok) \
+			and _check("missing user status is 401", result.status == 401) \
+			and _check("missing user detail",
+					"Incorrect" in result.detail or "incorrect" in result.detail):
+		passed += 1
+	else:
+		failed += 1
+		print("  detail: ", result.detail)
+
+	# --- Summary ---
+	print("\n=== SMOKE RESULT: %d/%d passed ===" % [passed, passed + failed])
+	if failed > 0:
+		quit(1)
+	else:
+		print("SMOKE RESULT: ALL PASS")
+		quit(0)
+
+
+func _check(description: String, condition: bool) -> bool:
+	if condition:
+		print("  PASS: ", description)
+		return true
+	else:
+		printerr("  FAIL: ", description)
+		return false