WIP checkpoint: Upgrade auth to RS256 signing, age-verification field, refresh-token sessions

- Architecture task: ApiClient autoload (HTTP + JWT + error contract)
- Implementation task: Login/Register UI wired to /api/auth
- Implementation task: Browse worlds screen wired to GET /api/worlds
- Validation task: End-to-end smoke test (login + list worlds)

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
-SECRET_KEY=change-me-to-a-secure-random-string
-ALGORITHM=HS256
-ACCESS_TOKEN_EXPIRE_MINUTES=30
+# JWT / Auth
+ALGORITHM=RS256
+ACCESS_TOKEN_EXPIRE_MINUTES=60
+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/0001_initial.py

@@ -69,7 +69,8 @@ def upgrade() -> None:
         sa.Column(
             "visibility",
             postgresql.ENUM(
-                "public", "private", "friends_only", name="world_visibility"
+                "public", "private", "friends_only", name="world_visibility",
+                create_type=False,
             ),
             nullable=True,
         ),
@@ -89,7 +90,7 @@ def upgrade() -> None:
             "asset_type",
             postgresql.ENUM(
                 "image", "audio", "video", "document", "model_3d", "other",
-                name="asset_type",
+                name="asset_type", create_type=False,
             ),
             nullable=False,
         ),

backend/alembic/versions/0002_add_date_of_birth_to_users.py

@@ -0,0 +1,30 @@
+"""add date_of_birth column to users table
+
+Revision ID: 0002_add_date_of_birth_to_users
+Revises: 0001_initial
+Create Date: 2025-01-01 00:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision: str = "0002_add_date_of_birth_to_users"
+down_revision: Union[str, None] = "0001_initial"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Add date_of_birth column to users table."""
+    op.add_column(
+        "users",
+        sa.Column("date_of_birth", sa.Date(), nullable=True),
+    )
+
+
+def downgrade() -> None:
+    """Remove date_of_birth column from users table."""
+    op.drop_column("users", "date_of_birth")

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
-    # (e.g. `python -c "import secrets; print(secrets.token_urlsafe(32))"`)
-    SECRET_KEY: str = "change-me-to-a-secure-random-string"
-    ALGORITHM: str = "HS256"
-    ACCESS_TOKEN_EXPIRE_MINUTES: int = 30
+    ALGORITHM: str = "RS256"
+    ACCESS_TOKEN_EXPIRE_MINUTES: int = 60
+    REFRESH_TOKEN_EXPIRE_DAYS: 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"
@@ -30,6 +78,7 @@ class Settings(BaseSettings):
     # File uploads
     UPLOAD_DIR: str = "uploads"
     MAX_UPLOAD_SIZE_MB: int = 100
+    GLTF_MAX_FILE_SIZE_MB: int = 200
 
     model_config = SettingsConfigDict(
         env_file=".env",
@@ -41,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,19 @@ 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; Text avoids length issues and is fine for
+    # a UUID-indexed lookup by hash in the future.
+    token = Column(String, unique=True, index=True, nullable=False)
+    expires_at = Column(DateTime(timezone=True), nullable=False)
+    is_active = Column(Boolean, default=True)
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+    updated_at = Column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now())
+
+    user = relationship("User", back_populates="refresh_tokens")

backend/app/models/user.py

@@ -1,4 +1,7 @@
-from sqlalchemy import Column, Integer, String, Boolean, DateTime
+from datetime import date
+from typing import Optional
+
+from sqlalchemy import Column, Integer, String, Boolean, DateTime, Date
 from sqlalchemy.orm import relationship
 from sqlalchemy.sql import func
 
@@ -12,10 +15,24 @@ class User(Base):
     username = Column(String(50), unique=True, index=True, nullable=False)
     email = Column(String(120), unique=True, index=True, nullable=False)
     hashed_password = Column(String(255), nullable=False)
+    date_of_birth = Column(Date, nullable=True)
     is_active = Column(Boolean, default=True)
     created_at = Column(DateTime(timezone=True), server_default=func.now())
     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")
+
+    @property
+    def is_adult(self) -> bool:
+        """Return True if the user is 18 or older based on date_of_birth."""
+        if self.date_of_birth is None:
+            return False
+        today = date.today()
+        age = today.year - self.date_of_birth.year
+        # Adjust if birthday hasn't occurred yet this year
+        if (today.month, today.day) < (self.date_of_birth.month, self.date_of_birth.day):
+            age -= 1
+        return age >= 18

backend/app/routers/assets.py

@@ -1,5 +1,6 @@
 """Asset management router."""
 
+import json
 import os
 from pathlib import Path
 from typing import Optional
@@ -13,6 +14,7 @@ from app.database import get_db
 from app.dependencies import CurrentUser
 from app.models.asset import Asset, AssetType
 from app.models.world import World
+from app.services import gltf as gltf_service
 from pydantic import BaseModel, Field
 
 router = APIRouter()
@@ -64,6 +66,14 @@ def _sanitize_filename(filename: str) -> str:
     return safe or "file"
 
 
+def _detect_asset_type(filename: Optional[str], content: bytes) -> AssetType:
+    """Detect the asset type from filename and content."""
+    if filename and gltf_service.looks_like_gltf(content, filename):
+        return AssetType.MODEL_3D
+    # Fallback: let the caller decide based on mime_type or default.
+    return AssetType.OTHER
+
+
 # --- Endpoints ---
 
 @router.post("/", response_model=AssetResponse, status_code=201)
@@ -183,10 +193,16 @@ async def upload_asset_file(
     # Sanitize filename to prevent path traversal.
     safe_filename = _sanitize_filename(file.filename or f"asset_{asset_id}")
 
-    # Validate file size against configured maximum.
-    max_bytes = settings.MAX_UPLOAD_SIZE_MB * 1024 * 1024
+    # Read the file content.
     content = await file.read()
     file_size = len(content)
+
+    # Determine which size limit to apply.
+    if gltf_service.looks_like_gltf(content, file.filename):
+        max_bytes = settings.GLTF_MAX_FILE_SIZE_MB * 1024 * 1024
+    else:
+        max_bytes = settings.MAX_UPLOAD_SIZE_MB * 1024 * 1024
+
     if file_size > max_bytes:
         raise HTTPException(
             status_code=413,
@@ -200,10 +216,28 @@ async def upload_asset_file(
     file_path = upload_dir / stored_name
     file_path.write_bytes(content)
 
+    # Detect asset type from content/filename.
+    detected_type = _detect_asset_type(file.filename, content)
+
+    # Update asset record.
     asset.file_path = str(file_path)
     asset.mime_type = file.content_type
     asset.file_size = file_size
 
+    # If this is a glTF file, extract and store metadata.
+    if detected_type == AssetType.MODEL_3D:
+        try:
+            metadata = gltf_service.extract_gltf_metadata(content)
+            asset.metadata_json = json.dumps(metadata)
+            # Also set the asset type to model_3d if it was auto-detected.
+            if asset.asset_type == AssetType.OTHER:
+                asset.asset_type = AssetType.MODEL_3D
+        except ValueError as exc:
+            raise HTTPException(
+                status_code=400,
+                detail=f"Invalid glTF file: {exc}",
+            )
+
     await db.commit()
     await db.refresh(asset)
     return asset

backend/app/routers/auth.py

@@ -1,20 +1,21 @@
 """Authentication router - login, register, token refresh."""
 
+import uuid
 from datetime import datetime, timedelta, timezone
 
 from fastapi import APIRouter, Depends, HTTPException, status
 from fastapi.security import OAuth2PasswordRequestForm
-from pydantic import BaseModel, EmailStr
-
 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,19 +26,33 @@ router = APIRouter()
 
 class TokenResponse(BaseModel):
     access_token: str
+    refresh_token: str
     token_type: str = "bearer"
+    access_token_expires_minutes: int
 
 
 class RegisterRequest(BaseModel):
     username: str
     email: EmailStr
     password: str
+    date_of_birth: str  # ISO format date string (YYYY-MM-DD)
+
+    @field_validator("date_of_birth")
+    @classmethod
+    def validate_date_of_birth(cls, v: str) -> str:
+        """Validate that the date string is a valid date in YYYY-MM-DD format."""
+        try:
+            datetime.strptime(v, "%Y-%m-%d")
+        except ValueError:
+            raise ValueError("date_of_birth must be in YYYY-MM-DD format")
+        return v
 
 
 class UserResponse(BaseModel):
     id: int
     username: str
     email: str
+    date_of_birth: str | None = None
     is_active: bool
     created_at: datetime | None = None
 
@@ -47,12 +62,31 @@ class UserResponse(BaseModel):
 # --- Helpers ---
 
 def _create_access_token(data: dict) -> str:
+    """Create a signed access token using RS256."""
     to_encode = data.copy()
     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."""
+    to_encode = data.copy()
+    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:
@@ -65,11 +99,58 @@ def hash_password(password: str) -> str:
     return pwd_context.hash(password)
 
 
+def calculate_age(birth_date, today=None) -> int:
+    """Calculate age in years from a birth date.
+
+    Args:
+        birth_date: The person's date of birth.
+        today: The reference date. Defaults to today's date (UTC).
+
+    Returns:
+        Age in whole years as of the reference date.
+    """
+    if today is None:
+        today = datetime.now(timezone.utc).date()
+
+    age = today.year - birth_date.year
+    # Adjust if birthday hasn't occurred yet this year
+    if (today.month, today.day) < (birth_date.month, birth_date.day):
+        age -= 1
+    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.
+    """
+    # Parse and validate date_of_birth
+    dob = datetime.strptime(req.date_of_birth, "%Y-%m-%d").date()
+    age = calculate_age(dob)
+
+    if age < 18:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Must be 18 or older to register (provided date of birth: {req.date_of_birth})",
+        )
+
     # Check if username already exists
     result = await db.execute(select(User).where(User.username == req.username))
     if result.scalar_one_or_none():
@@ -90,18 +171,29 @@ async def register(req: RegisterRequest, db: AsyncSession = Depends(get_db)):
         username=req.username,
         email=req.email,
         hashed_password=hash_password(req.password),
+        date_of_birth=dob,
     )
     db.add(user)
     await db.commit()
     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.
@@ -121,8 +213,18 @@ 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.get("/me", response_model=UserResponse)

backend/app/services/gltf.py

@@ -0,0 +1,197 @@
+"""Lightweight glTF / GLB metadata extraction.
+
+This module intentionally avoids heavyweight dependencies such as trimesh or
+pygltflib. For the metadata fields the asset upload pipeline needs (mesh and
+vertex counts, animation presence, texture references, and the bounding box)
+a small amount of glTF-specific parsing is sufficient and keeps the backend
+dependency-free.
+"""
+
+from __future__ import annotations
+
+import json
+import struct
+from typing import Any, Optional
+
+# GLB binary header magic bytes ("glTF").
+_GLB_MAGIC = b"glTF"
+_GLB_MAGIC_INT = 0x46546C67  # b"glTF" interpreted as little-endian uint32
+_GLB_JSON_CHUNK_TYPE = 0x4E4F534A  # "JSON"
+_GLB_BIN_CHUNK_TYPE = 0x004E4942  # "BIN\0"
+
+# Whitespace allowed around a GLB JSON chunk. The spec pads with spaces (0x20),
+# but be lenient with null bytes and other whitespace that real exporters emit.
+_JSON_CHUNK_TRIM = b" \t\r\n\x00"
+
+
+def looks_like_gltf(content: bytes, filename: Optional[str] = None) -> bool:
+    """Return True when the bytes or filename indicate a glTF/GLB asset."""
+    if content.startswith(_GLB_MAGIC):
+        return True
+
+    if filename:
+        lowered = filename.lower()
+        if lowered.endswith(".gltf") or lowered.endswith(".glb"):
+            return True
+
+    # A bare JSON buffer (e.g. uploaded without an extension) that has the
+    # glTF asset marker is also a glTF file.
+    stripped = content.lstrip()
+    if stripped.startswith(b"{"):
+        try:
+            payload = json.loads(stripped.decode("utf-8"))
+        except (ValueError, UnicodeDecodeError):
+            return False
+        return isinstance(payload, dict) and "asset" in payload and "version" in payload.get("asset", {})
+
+    return False
+
+
+def _parse_glb(content: bytes) -> dict[str, Any]:
+    """Parse the JSON chunk of a GLB binary container."""
+    if len(content) < 12:
+        raise ValueError("GLB file is too short")
+
+    magic, _version, _length = struct.unpack_from("<III", content, 0)
+    if magic != _GLB_MAGIC_INT:
+        raise ValueError("invalid GLB magic")
+
+    offset = 12
+    json_chunk: Optional[dict[str, Any]] = None
+
+    while offset + 8 <= len(content):
+        chunk_length, chunk_type = struct.unpack_from("<II", content, offset)
+        offset += 8
+        chunk_end = offset + chunk_length
+        if chunk_end > len(content):
+            raise ValueError("GLB chunk overruns file boundary")
+
+        chunk_data = content[offset:chunk_end]
+        if chunk_type == _GLB_JSON_CHUNK_TYPE:
+            try:
+                json_chunk = json.loads(chunk_data.strip(_JSON_CHUNK_TRIM).decode("utf-8"))
+            except (ValueError, UnicodeDecodeError) as exc:
+                raise ValueError(f"invalid GLB JSON chunk: {exc}") from exc
+
+        offset = chunk_end
+
+    if json_chunk is None:
+        raise ValueError("GLB file does not contain a JSON chunk")
+
+    return json_chunk
+
+
+def _parse_gltf_json(content: bytes) -> dict[str, Any]:
+    """Parse a plain .gltf JSON file."""
+    stripped = content.lstrip()
+    try:
+        payload = json.loads(stripped.decode("utf-8"))
+    except (ValueError, UnicodeDecodeError) as exc:
+        raise ValueError(f"invalid glTF JSON: {exc}") from exc
+
+    if not isinstance(payload, dict):
+        raise ValueError("glTF JSON root must be an object")
+    return payload
+
+
+def _position_accessor_counts(gltf: dict[str, Any]) -> list[int]:
+    """Return POSITION accessor counts for every mesh primitive."""
+    counts: list[int] = []
+    accessors = gltf.get("accessors", [])
+    for mesh in gltf.get("meshes", []):
+        for primitive in mesh.get("primitives", []):
+            attributes = primitive.get("attributes", {})
+            position_index = attributes.get("POSITION")
+            if position_index is None:
+                continue
+            try:
+                accessor = accessors[int(position_index)]
+            except (IndexError, TypeError, ValueError):
+                continue
+            count = accessor.get("count")
+            if isinstance(count, int):
+                counts.append(count)
+    return counts
+
+
+def _position_bounds(gltf: dict[str, Any]) -> list[list[float]]:
+    """Return min/max bounds for every POSITION accessor that declares them."""
+    bounds: list[list[float]] = []
+    accessors = gltf.get("accessors", [])
+    for mesh in gltf.get("meshes", []):
+        for primitive in mesh.get("primitives", []):
+            attributes = primitive.get("attributes", {})
+            position_index = attributes.get("POSITION")
+            if position_index is None:
+                continue
+            try:
+                accessor = accessors[int(position_index)]
+            except (IndexError, TypeError, ValueError):
+                continue
+            minimum = accessor.get("min")
+            maximum = accessor.get("max")
+            if isinstance(minimum, list) and isinstance(maximum, list):
+                bounds.append([float(x) for x in minimum])
+                bounds.append([float(x) for x in maximum])
+    return bounds
+
+
+def _texture_refs(gltf: dict[str, Any]) -> list[str]:
+    """Collect external texture source references from the image array."""
+    refs: list[str] = []
+    for index, image in enumerate(gltf.get("images", [])):
+        uri = image.get("uri")
+        if isinstance(uri, str) and not uri.startswith("data:"):
+            refs.append(uri)
+            continue
+
+        name = image.get("name")
+        if isinstance(name, str) and name:
+            refs.append(name)
+            continue
+
+        if isinstance(uri, str):
+            # Embedded data URI; keep a stable, non-huge reference.
+            refs.append(f"data:{index}")
+            continue
+
+        buffer_view = image.get("bufferView")
+        if buffer_view is not None:
+            refs.append(f"bufferView:{buffer_view}")
+            continue
+
+        refs.append(f"image:{index}")
+
+    return refs
+
+
+def extract_gltf_metadata(content: bytes) -> dict[str, Any]:
+    """Extract upload-relevant metadata from glTF/GLB bytes.
+
+    Raises ValueError for malformed glTF content. The returned dict contains:
+        mesh_count, vertex_count, has_animation, texture_refs,
+        bounding_box_min, bounding_box_max.
+    """
+    if content.startswith(_GLB_MAGIC):
+        gltf = _parse_glb(content)
+    else:
+        gltf = _parse_gltf_json(content)
+
+    position_counts = _position_accessor_counts(gltf)
+    bounds = _position_bounds(gltf)
+
+    if bounds:
+        bounding_box_min = [min(axis) for axis in zip(*bounds[::2])]
+        bounding_box_max = [max(axis) for axis in zip(*bounds[1::2])]
+    else:
+        bounding_box_min = [0.0, 0.0, 0.0]
+        bounding_box_max = [0.0, 0.0, 0.0]
+
+    return {
+        "mesh_count": len(gltf.get("meshes", [])),
+        "vertex_count": sum(position_counts),
+        "has_animation": bool(gltf.get("animations")),
+        "texture_refs": _texture_refs(gltf),
+        "bounding_box_min": bounding_box_min,
+        "bounding_box_max": bounding_box_max,
+    }

backend/docker-compose.yml

@@ -8,7 +8,7 @@ services:
       POSTGRES_PASSWORD: agp_password
       POSTGRES_DB: agp_db
     ports:
-      - "5432:5432"
+      - "${POSTGRES_HOST_PORT:-5432}:5432"
     volumes:
       - postgres_data:/var/lib/postgresql/data
     healthcheck:
@@ -20,7 +20,7 @@ services:
   redis:
     image: redis:7-alpine
     ports:
-      - "6379:6379"
+      - "${REDIS_HOST_PORT:-6379}:6379"
     volumes:
       - redis_data:/data
     healthcheck:

backend/pytest.ini

@@ -0,0 +1,3 @@
+[pytest]
+asyncio_mode = auto
+testpaths = tests

backend/tests/test_auth_age_gate.py

@@ -0,0 +1,94 @@
+"""Tests for the 18+ age gate on user registration."""
+
+from datetime import date, timedelta
+
+import pytest
+
+from app.routers.auth import calculate_age
+
+
+class TestCalculateAge:
+    """Unit tests for the calculate_age helper."""
+
+    def test_exactly_18(self):
+        """A person born exactly 18 years ago today is 18."""
+        today = date(2025, 6, 15)
+        dob = today.replace(year=today.year - 18)
+        assert calculate_age(dob, today=today) == 18
+
+    def test_just_turned_18(self):
+        """A person who turned 18 yesterday is 18."""
+        today = date(2025, 6, 15)
+        dob = today.replace(year=today.year - 18) - timedelta(days=1)
+        assert calculate_age(dob, today=today) == 18
+
+    def test_one_day_short_of_18(self):
+        """A person born one day after their 18th birthday is 17."""
+        today = date(2025, 6, 15)
+        dob = today.replace(year=today.year - 18) + timedelta(days=1)
+        assert calculate_age(dob, today=today) == 17
+
+    def test_17_years_old(self):
+        """A person who is 17 years old today is 17."""
+        today = date(2025, 6, 15)
+        dob = date(2008, 6, 15)
+        assert calculate_age(dob, today=today) == 17
+
+    def test_65_years_old(self):
+        """A person who is 65 is correctly calculated."""
+        today = date(2025, 6, 15)
+        dob = today.replace(year=today.year - 65)
+        assert calculate_age(dob, today=today) == 65
+
+    def test_newborn(self):
+        """A newborn is 0."""
+        today = date(2025, 6, 15)
+        dob = today
+        assert calculate_age(dob, today=today) == 0
+
+    def test_birthday_not_yet_this_year(self):
+        """Person born Dec 31, 2000 — on Jan 1, 2025 they are still 24."""
+        dob = date(2000, 12, 31)
+        assert calculate_age(dob, today=date(2025, 1, 1)) == 24
+
+    def test_birthday_today(self):
+        """Person born Dec 31, 2000 — on Dec 31, 2024 they turn 24."""
+        dob = date(2000, 12, 31)
+        assert calculate_age(dob, today=date(2024, 12, 31)) == 24
+
+
+class TestRegisterRequestDateValidation:
+    """Tests for the RegisterRequest date_of_birth field validator."""
+
+    @pytest.mark.parametrize(
+        "dob",
+        [
+            "2000-01-01",
+            "1990-12-31",
+            "2004-02-29",  # leap day
+        ],
+    )
+    def test_valid_dates(self, dob):
+        """Valid YYYY-MM-DD dates pass validation."""
+        from app.routers.auth import RegisterRequest
+
+        req = RegisterRequest(username="u", email="u@example.com", password="p", date_of_birth=dob)
+        assert req.date_of_birth == dob
+
+    @pytest.mark.parametrize(
+        "dob",
+        [
+            "01-01-2000",
+            "2000/01/01",
+            "2000-13-01",
+            "2000-00-10",
+            "not-a-date",
+            "",
+        ],
+    )
+    def test_invalid_dates_rejected(self, dob):
+        """Invalid dates are rejected by the validator."""
+        from app.routers.auth import RegisterRequest
+
+        with pytest.raises(ValueError):
+            RegisterRequest(username="u", email="u@example.com", password="p", date_of_birth=dob)

backend/tests/test_gltf_metadata.py

@@ -0,0 +1,220 @@
+"""Tests for the lightweight glTF metadata extraction service."""
+
+import json
+import struct
+import pytest
+
+from app.services.gltf import (
+    extract_gltf_metadata,
+    looks_like_gltf,
+    _parse_glb,
+    _parse_gltf_json,
+)
+
+
+# ---------------------------------------------------------------------------
+# Test data helpers
+# ---------------------------------------------------------------------------
+
+def _make_gltf_json(
+    meshes: int = 1,
+    vertices_per_mesh: int = 24,
+    has_animations: bool = False,
+    images: list[dict] | None = None,
+) -> dict:
+    """Build a minimal glTF JSON structure."""
+    accessors = []
+    meshes_data = []
+    for i in range(meshes):
+        acc_index = len(accessors)
+        accessors.append({
+            "bufferView": 0,
+            "componentType": 5126,  # FLOAT
+            "count": vertices_per_mesh,
+            "type": "VEC3",
+            "max": [1.0, 1.0, 1.0],
+            "min": [-1.0, -1.0, -1.0],
+        })
+        meshes_data.append({
+            "primitives": [{
+                "attributes": {"POSITION": acc_index},
+            }],
+        })
+    gltf = {
+        "asset": {"version": "2.0"},
+        "accessors": accessors,
+        "meshes": meshes_data,
+    }
+    if has_animations:
+        gltf["animations"] = [{"name": "anim1", "channels": [], "samplers": []}]
+    if images:
+        gltf["images"] = images
+    return gltf
+
+
+def _make_glb(gltf_json: dict) -> bytes:
+    """Wrap *gltf_json* in a minimal GLB binary container."""
+    json_bytes = json.dumps(gltf_json).encode("utf-8")
+    json_length = len(json_bytes)
+    # Pad JSON chunk to 4-byte boundary.
+    json_padding = (4 - json_length % 4) % 4
+    json_chunk = json_bytes + b"\x00" * json_padding
+    json_chunk_type = 0x4E4F534A  # "JSON"
+    # No BIN chunk.
+    bin_length = 0
+    bin_chunk_type = 0x004E4942
+    total_length = 12 + 8 + len(json_chunk) + 8 + bin_length
+    header = struct.pack("<III", 0x46546C67, 2, total_length)  # magic, version, length
+    json_header = struct.pack("<II", len(json_chunk), json_chunk_type)
+    if bin_length > 0:
+        bin_header = struct.pack("<II", bin_length, bin_chunk_type)
+    else:
+        bin_header = b""
+    return header + json_header + json_chunk + bin_header
+
+
+# ---------------------------------------------------------------------------
+# looks_like_gltf
+# ---------------------------------------------------------------------------
+
+class TestLooksLikeGltf:
+    def test_glb_magic(self):
+        assert looks_like_gltf(b"glTF\x00\x00\x00\x00") is True
+
+    def test_gltf_extension(self):
+        assert looks_like_gltf(b'{"asset":{"version":"2.0"}}', "model.gltf") is True
+
+    def test_glb_extension(self):
+        assert looks_like_gltf(b"some binary", "model.glb") is True
+
+    def test_json_with_asset_version(self):
+        payload = json.dumps({"asset": {"version": "2.0"}}).encode()
+        assert looks_like_gltf(payload) is True
+
+    def test_plain_json_no_asset(self):
+        payload = json.dumps({"foo": "bar"}).encode()
+        assert looks_like_gltf(payload) is False
+
+    def test_non_json_bytes(self):
+        assert looks_like_gltf(b"\x89PNG\r\n\x1a\n") is False
+
+
+# ---------------------------------------------------------------------------
+# _parse_glb
+# ---------------------------------------------------------------------------
+
+class TestParseGlb:
+    def test_parses_valid_glb(self):
+        gltf_json = _make_gltf_json()
+        glb = _make_glb(gltf_json)
+        result = _parse_glb(glb)
+        assert result["asset"]["version"] == "2.0"
+        assert len(result["meshes"]) == 1
+
+    def test_rejects_too_short(self):
+        with pytest.raises(ValueError, match="too short"):
+            _parse_glb(b"glTF\x00\x00")
+
+    def test_rejects_invalid_magic(self):
+        with pytest.raises(ValueError, match="invalid GLB magic"):
+            _parse_glb(b"NOTglTF\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00")
+
+
+# ---------------------------------------------------------------------------
+# _parse_gltf_json
+# ---------------------------------------------------------------------------
+
+class TestParseGltfJson:
+    def test_parses_valid_gltf(self):
+        gltf_json = _make_gltf_json()
+        result = _parse_gltf_json(json.dumps(gltf_json).encode())
+        assert result["asset"]["version"] == "2.0"
+
+    def test_rejects_non_object(self):
+        with pytest.raises(ValueError, match="root must be an object"):
+            _parse_gltf_json(b"[1, 2, 3]")
+
+
+# ---------------------------------------------------------------------------
+# extract_gltf_metadata  (GLB path)
+# ---------------------------------------------------------------------------
+
+class TestExtractGltfMetadataGlb:
+    def test_basic_glb(self):
+        gltf_json = _make_gltf_json(meshes=1, vertices_per_mesh=24)
+        glb = _make_glb(gltf_json)
+        meta = extract_gltf_metadata(glb)
+        assert meta["mesh_count"] == 1
+        assert meta["vertex_count"] == 24
+        assert meta["has_animation"] is False
+        assert meta["bounding_box_min"] == [-1.0, -1.0, -1.0]
+        assert meta["bounding_box_max"] == [1.0, 1.0, 1.0]
+        assert meta["texture_refs"] == []
+
+    def test_multiple_meshes(self):
+        gltf_json = _make_gltf_json(meshes=3, vertices_per_mesh=12)
+        glb = _make_glb(gltf_json)
+        meta = extract_gltf_metadata(glb)
+        assert meta["mesh_count"] == 3
+        assert meta["vertex_count"] == 36
+
+    def test_with_animation(self):
+        gltf_json = _make_gltf_json(has_animations=True)
+        glb = _make_glb(gltf_json)
+        meta = extract_gltf_metadata(glb)
+        assert meta["has_animation"] is True
+
+    def test_with_external_texture(self):
+        gltf_json = _make_gltf_json(images=[{"uri": "textures/rock.png"}])
+        glb = _make_glb(gltf_json)
+        meta = extract_gltf_metadata(glb)
+        assert meta["texture_refs"] == ["textures/rock.png"]
+
+    def test_with_named_texture(self):
+        gltf_json = _make_gltf_json(images=[{"name": "my_texture"}])
+        glb = _make_glb(gltf_json)
+        meta = extract_gltf_metadata(glb)
+        assert meta["texture_refs"] == ["my_texture"]
+
+    def test_empty_meshes(self):
+        gltf_json = _make_gltf_json(meshes=0)
+        glb = _make_glb(gltf_json)
+        meta = extract_gltf_metadata(glb)
+        assert meta["mesh_count"] == 0
+        assert meta["vertex_count"] == 0
+        assert meta["bounding_box_min"] == [0.0, 0.0, 0.0]
+        assert meta["bounding_box_max"] == [0.0, 0.0, 0.0]
+
+
+# ---------------------------------------------------------------------------
+# extract_gltf_metadata  (plain .gltf JSON path)
+# ---------------------------------------------------------------------------
+
+class TestExtractGltfMetadataGltfJson:
+    def test_plain_gltf(self):
+        gltf_json = _make_gltf_json(meshes=2, vertices_per_mesh=8)
+        raw = json.dumps(gltf_json).encode()
+        meta = extract_gltf_metadata(raw)
+        assert meta["mesh_count"] == 2
+        assert meta["vertex_count"] == 16
+        assert meta["has_animation"] is False
+
+    def test_plain_gltf_with_animation(self):
+        gltf_json = _make_gltf_json(has_animations=True)
+        raw = json.dumps(gltf_json).encode()
+        meta = extract_gltf_metadata(raw)
+        assert meta["has_animation"] is True
+
+
+# ---------------------------------------------------------------------------
+# Error handling
+# ---------------------------------------------------------------------------
+
+class TestExtractGltfMetadataErrors:
+    def test_invalid_glb(self):
+        with pytest.raises(ValueError):
+            extract_gltf_metadata(b"not a glb")
+
+    def test_invalid_gltf_json(self):
+        with pytest.raises(ValueError):
+            _parse_gltf_json(b"[1, 2, 3]")

docs/planning/client-server-wiring.md

@@ -0,0 +1,37 @@
+# MVP Vertical Slice: Client-Server Wiring — Plan
+
+## Goal
+Prove the real Godot client and the real backend can talk: **a user can register/log in
+and see a list of worlds from the game client**. Nothing more. Gameplay, join-a-world,
+chat, avatar, Discovery search/tags/trending, Social/Economy/Trust & Safety are all
+explicitly out of scope.
+
+## Verified backend contract (as of this writing)
+- `POST /api/auth/register` — JSON body `{username, email, password, date_of_birth}`.
+  `date_of_birth` is a `YYYY-MM-DD` string. Returns `201 {access_token, token_type}`.
+  Rejects under-18 with `400`.
+- `POST /api/auth/login` — OAuth2 **form-encoded** (`application/x-www-form-urlencoded`)
+  `username` + `password` (this is NOT a JSON endpoint). Returns `{access_token, token_type}`.
+- `GET /api/worlds` — **requires auth** (`CurrentUser`), returns a JSON array of
+  `{id, name, description, visibility, owner_id, created_at}`. There is no unauthenticated
+  public-worlds path, so the worlds list screen can only be shown after login/register.
+- `GET /api/health` — unauthenticated, `{status, app}`.
+- Base URL: uvicorn default `http://127.0.0.1:8000` (must be configurable in the client).
+- CORS is irrelevant to the native Godot `HTTPRequest` client (no browser origin).
+
+## Task breakdown
+| # | Type | Task | Depends on |
+|---|------|------|-----------|
+| 1 | architecture | `ApiClient` autoload: HTTP + JWT storage + error contract | — |
+| 2 | implementation | Main-menu **login** wiring (form-encoded) | 1 |
+| 3 | implementation | Main-menu **register** wiring (JSON + age gate) | 2 |
+| 4 | implementation | **World list** screen consuming `GET /api/worlds` | 2 |
+| 5 | testing | End-to-end headless smoke test + manual verify | 1,3,4 |
+
+## Design decisions captured (resolved in task 1)
+- Token storage: in-memory singleton property for the MVP; a `save_to_disk` seam is left
+  open but not required yet (no re-login on restart in this slice).
+- Error contract: every call returns a discriminated result (`ok`/`error`) so callers
+  never crash on network failure; non-2xx surfaces `{status, detail}` from the backend.
+- Base URL: read from a ProjectSetting, defaulting to `http://127.0.0.1:8000`.
+- Login is form-encoded; register is JSON — the client helper must support both content types.

docs/planning/economy.md

@@ -0,0 +1,295 @@
+# Economy — Currency, Marketplace & Creator Payouts — Plan
+
+> **Status:** Planned
+> **Owner:** Platform team
+> **Feature ID:** `economy`
+> **Godot version:** 4.6.2 stable
+> **Backend:** FastAPI + SQLAlchemy (async) + PostgreSQL + Redis
+
+## 1. Overview
+
+This document breaks the **Economy** feature into user stories and right-sized
+implementation tasks. The feature delivers:
+
+- **Virtual currency ("Credits")** — a single, server-authoritative currency
+  with an immutable, append-only transaction ledger.
+- **Premium purchase** — buying Credits with real money through a pluggable
+  payment-provider hook.
+- **Marketplace** — user-generated content (UGC) listings where creators sell
+  items (assets, avatar items, experience passes) to players for Credits.
+- **Creator payouts** — accumulating creator earnings and paying them out to
+  external accounts through a pluggable payout-provider hook.
+- **Godot client** — wallet/transaction history, marketplace browse/buy/sell,
+  and creator payout screens.
+
+The economy is the monetization backbone of the platform. Because it moves
+virtual value between real people, correctness (no double-spend, no lost funds,
+no balance drift) and safety (fraud prevention, moderation, audit) are treated
+as **blocking requirements**, not add-ons.
+
+## 2. Why correctness is the differentiator
+
+The platform is a creator economy (players buy UGC from other players). The
+economy is the highest-risk surface after chat: a single arithmetic or
+concurrency bug can mint or destroy value and irreversibly erode trust.
+Correctness is therefore designed in from the start:
+
+- **One currency, integer units.** Credits are whole-number integers. There are
+  no floats, no rounding, and no client-computed totals.
+- **Append-only ledger.** Every balance change is a row in a `transactions`
+  table with a signed amount, a `balance_after` snapshot, a reference to the
+  event that caused it, and an **idempotency key** so retries cannot double
+  credit or double debit.
+- **Atomic, locked mutations.** Balance changes run in a single database
+  transaction with row locking (`SELECT ... FOR UPDATE`) so concurrent
+  purchases/payouts cannot race.
+- **Escrow hold.** Marketplace proceeds are held in `pending_escrow` for a
+  configurable window before becoming available to the seller, so fraudulent
+  or moderated sales can be reversed without clawing back paid-out funds.
+- **Server-authoritative fees.** The platform commission is computed
+  server-side from a configured rate; the client never supplies the fee or the
+  seller's net.
+
+## 3. Existing constraints (do not re-build)
+
+- **Auth:** JWT bearer tokens; `get_current_user` / `CurrentUser` dependency in
+  `app/dependencies.py`. All economy endpoints reuse this.
+- **DB:** async SQLAlchemy + Alembic; migration `0001_initial` is the head.
+  Existing tables: `users`, `sessions`, `worlds`, `assets`.
+- **Redis:** configured (`REDIS_URL`) but unused so far; adopted here for
+  idempotency short-caching and rate limiting.
+- **Models:** `User` (owner_id), `Asset` (owner_id, is_public, asset_type).
+  Marketplace items reference existing `assets` rows and/or avatar items.
+- **Content moderation:** `docs/architecture/content_moderation.md` defines
+  flag vocabulary, age gate, and moderation actions. Marketplace items and
+  listings must inherit and enforce these rules (see §7).
+- **Client:** Godot 4.6.2, minimal `main_menu.gd`; no economy UI yet.
+
+## 4. Key design decisions
+
+| Concern | Decision |
+|---|---|
+| Currency model | Single virtual currency **"Credits" (CR)**, integer units. One wallet row per user; no fractional amounts. |
+| Ledger | Append-only `transactions` table: signed `amount`, `balance_after`, `reference_type`/`reference_id`, unique `idempotency_key`. |
+| Concurrency | `SELECT ... FOR UPDATE` on the wallet row inside the mutation transaction; never read-modify-write from stale data. |
+| Payments | Pluggable `PaymentProvider` interface with a **no-op default** that simulates a confirmed payment for dev/testing (clearly flagged). Stripe/PayPal later. |
+| Marketplace items | `catalog_items` (what is sold) + `marketplace_listings` (a seller's offer with a price/status). One item can have multiple listings over time. |
+| Purchase flow | Atomic transaction: debit buyer → hold funds in escrow (`pending_escrow`) → grant item. Platform fee computed server-side. |
+| Escrow | Configurable hold window (default 72h) before `pending_escrow` becomes available seller earnings. Refunds during the window reverse the sale. |
+| Fees | Single configurable `MARKETPLACE_FEE_RATE` (default `0.30`). `seller_net = floor(price * (1 - fee_rate))`. |
+| Creator balance | `creator_balances` table: `available` (earned, payable), `pending` (inside an open payout request), `lifetime_earned`. Updated in the same transaction as the sale completion. |
+| Payouts | Pluggable `PayoutProvider.pay()` with a no-op default (simulated external ref). Minimum payout threshold, admin review for large payouts. |
+| Idempotency | Every money-moving request carries a client-generated `Idempotency-Key`; duplicate keys return the original result. |
+| Rate limiting | Redis token-bucket dependency reused from the social feature for purchase/listing/payout endpoints. |
+| Moderation | Listings enforce content flags + age gate; moderators can `delist`/`remove`; fraud/chargeback reversal is an audited admin action. |
+
+## 5. User stories
+
+### US-1 Currency & wallet
+As a player, I can see my Credit balance and transaction history, and the system
+credits/debits my wallet only through server-authoritative events.
+
+**Acceptance criteria**
+- Exactly one wallet per user, created lazily on first use.
+- Balance is always a non-negative integer; no operation can make it negative.
+- Every mutation appends an immutable ledger row with amount, resulting balance,
+  reference, and idempotency key.
+- Retrying a request with the same idempotency key does not double-apply.
+- `GET` endpoints expose current balance and paged transaction history.
+
+### US-2 Premium purchase (buy Credits)
+As a player, I can purchase Credits with real money and have them credited only
+after the payment is confirmed.
+
+**Acceptance criteria**
+- A purchase session is created through the payment provider (or the no-op
+  default) and is idempotent.
+- Credits are granted exactly once, only after a verified provider confirmation
+  (webhook/confirm endpoint), never on client claim.
+- Purchase amounts are bounded and server-defined; clients cannot pick arbitrary
+  prices.
+- Confirmation is idempotent and audited (provider reference recorded).
+
+### US-3 Marketplace listing (sell)
+As a creator, I can list a catalog item for sale at a Credit price and
+manage/remove my listings.
+
+**Acceptance criteria**
+- A listing references a valid `catalog_item` owned by the seller (or an
+  authorized seller).
+- Price is bounded (min/max) and set server-side; status transitions are
+  explicit (`active`, `sold`, `delisted`, `removed_by_moderation`).
+- Only the seller (or a moderator) can update/remove a listing.
+- Listings are searchable/filterable (item type, price range, owner).
+
+### US-4 Marketplace purchase (buy)
+As a player, I can buy a listed item. The purchase is atomic, holds funds in
+escrow, grants the item, and splits the payment between platform and seller.
+
+**Acceptance criteria**
+- A single transaction debits the buyer, holds funds in escrow, and grants the
+  item — no partial states on failure.
+- Platform fee and seller net are computed server-side from the configured rate.
+- After the escrow hold window, funds move from escrow to the seller's
+  available balance.
+- Refunds during the hold window reverse the sale and return funds to the buyer.
+- Concurrent purchases of a one-of-a-kind listing cannot both succeed.
+
+### US-5 Creator payouts
+As a creator, I can view my earned balance, request a payout, and track its
+status; admins can review and approve/reject payouts.
+
+**Acceptance criteria**
+- Available balance is derived only from completed (escrow-released) sales and
+  completed payouts; it never goes negative.
+- Payout requests are bounded (min threshold, max per period) and rate-limited.
+- Large payouts require admin review; all payout requests carry an audit trail
+  (requested by, reviewed by, provider reference, status).
+- The payout provider is called exactly once; idempotent on retry.
+
+### US-6 Godot client
+As a player, I can manage Credits, browse/buy/sell marketplace items, and manage
+payouts from the game UI.
+
+**Acceptance criteria**
+- An API client handles JWT auth, HTTP, and idempotency keys for all economy
+  calls.
+- Dedicated screens: wallet + transaction history, marketplace browse/buy,
+  sell-listing, and creator payout.
+- The client never computes balances, fees, or seller nets — it only displays
+  server responses.
+
+## 6. Task breakdown
+
+Right-sized to 1–3 files / one coherent piece of functionality each. Task IDs
+are sequential for dependency chaining.
+
+| # | Task | Story | Depends on |
+|---|------|-------|-----------|
+| 1 | Wallet & ledger models + Alembic migration (`wallets`, `transactions`) | US-1 | — |
+| 2 | Wallet service (atomic credit/debit, idempotency, locking) + wallet/transactions API | US-1 | 1 |
+| 3 | Premium purchase: `PaymentProvider` interface + purchase/confirm endpoints | US-2 | 1 |
+| 4 | Catalog item & listing models + migration (`catalog_items`, `marketplace_listings`, `creator_balances`) | US-3 | 1 |
+| 5 | Marketplace listing API (create/list/search/update/remove) | US-3 | 4 |
+| 6 | Marketplace purchase service + API (atomic escrow, fee split, item grant) | US-4 | 2, 4, 5 |
+| 7 | Creator payout request models + API (`payout_requests`) | US-5 | 2, 6 |
+| 8 | Payout admin review + `PayoutProvider` + audit | US-5 | 7 |
+| 9 | Marketplace moderation + content-flag/age-gate enforcement | cross-cutting | 5, 6 |
+| 10 | Godot economy API client (auth + HTTP + idempotency) | US-6 | 2 |
+| 11 | Godot wallet & transaction history UI | US-6 | 10 |
+| 12 | Godot marketplace browse/buy UI | US-6 | 6, 10 |
+| 13 | Godot selling & payout UI | US-6 | 5, 7, 10 |
+
+## 7. Phasing
+
+- **Phase 1 (currency + payments):** tasks 1–3. The foundation — ledger and
+  money movement must be rock-solid before anything spends Credits.
+- **Phase 2 (marketplace):** tasks 4–6. Listing and atomic purchase with escrow.
+- **Phase 3 (payouts):** tasks 7–8. Turn released escrow into creator payouts.
+- **Phase 4 (moderation):** task 9. Lock down the marketplace against mature
+  content and abuse.
+- **Phase 5 (client):** tasks 10–13, each landing after its backend dependency.
+
+## 8. Data model sketch
+
+```text
+wallets
+  id                bigint PK
+  user_id           int UNIQUE FK -> users.id
+  balance           bigint NOT NULL DEFAULT 0  CHECK (balance >= 0)
+  created_at        timestamptz
+  updated_at        timestamptz
+
+transactions        (append-only ledger)
+  id                bigint PK
+  wallet_id         bigint FK -> wallets.id
+  type              enum(credit_purchase, marketplace_purchase,
+                        marketplace_sale, escrow_release, payout,
+                        refund, admin_adjustment)
+  amount            bigint NOT NULL            (signed)
+  balance_after     bigint NOT NULL
+  reference_type    text                        (e.g. "purchase", "sale", "payout_request")
+  reference_id      text
+  idempotency_key   text UNIQUE
+  metadata_json     jsonb
+  created_at        timestamptz
+
+catalog_items
+  id                bigint PK
+  owner_id          int FK -> users.id
+  asset_id          int FK -> assets.id (nullable; null for non-asset virtual items)
+  item_type         enum(asset, avatar_item, experience_pass)
+  name              text
+  description       text
+  metadata_json     jsonb
+  created_at        timestamptz
+
+marketplace_listings
+  id                bigint PK
+  catalog_item_id   bigint FK -> catalog_items.id
+  seller_id         int FK -> users.id
+  price             bigint NOT NULL CHECK (price > 0)
+  status            enum(active, sold, delisted, removed_by_moderation)
+  created_at        timestamptz
+  updated_at        timestamptz
+
+purchases
+  id                bigint PK
+  listing_id        bigint FK -> marketplace_listings.id
+  buyer_id          int FK -> users.id
+  seller_id         int FK -> users.id
+  price             bigint NOT NULL
+  platform_fee      bigint NOT NULL
+  seller_net        bigint NOT NULL
+  status            enum(pending_escrow, completed, refunded, reversed)
+  escrow_hold_until timestamptz
+  created_at        timestamptz
+
+creator_balances
+  id                bigint PK
+  user_id           int UNIQUE FK -> users.id
+  available         bigint NOT NULL DEFAULT 0
+  pending           bigint NOT NULL DEFAULT 0
+  lifetime_earned   bigint NOT NULL DEFAULT 0
+  updated_at        timestamptz
+
+payout_requests
+  id                bigint PK
+  creator_id        int FK -> users.id
+  amount            bigint NOT NULL CHECK (amount > 0)
+  status            enum(pending, approved, paid, rejected)
+  external_ref      text
+  provider_ref      text
+  requested_by      int FK -> users.id
+  reviewed_by       int FK -> users.id (nullable)
+  reviewed_at       timestamptz
+  created_at        timestamptz
+```
+
+## 9. Security, anti-fraud & audit
+
+- **Server-authoritative balances/fees:** clients never compute totals; amounts
+  are validated server-side against bounds and the current listing.
+- **Row locking:** wallet and creator-balance mutations use `SELECT ... FOR
+  UPDATE` within one transaction.
+- **Idempotency:** every money-moving endpoint requires an `Idempotency-Key`;
+  duplicate keys return the stored original outcome.
+- **Rate limiting:** purchase, listing, and payout endpoints are token-bucket
+  rate-limited per user.
+- **Escrow & reversibility:** funds are not payable until the hold window
+  elapses; chargebacks/refunds reverse before release.
+- **Moderation:** listings carry the item's effective content flags; mature
+  items require age verification (per `content_moderation.md`); moderators can
+  `delist`/`remove` and trigger audited reversals.
+- **Audit:** the ledger plus `payout_requests` review fields form an append-only
+  audit trail for every movement of value.
+
+## 10. Out of scope for this feature
+
+- Real Stripe/PayPal/KYC integrations (provider interfaces leave the hooks; the
+  defaults are deterministic no-ops).
+- Subscriptions, recurring billing, or premium memberships.
+- Gift cards, promotional codes, or user-to-user Credit transfers.
+- Partial refunds, chargeback disputes, and seller tax/VAT handling.
+- In-world vending machines / scripted economy triggers (future, built on this
+  ledger via the scripting sandbox).

docs/planning/social.md

@@ -0,0 +1,170 @@
+# Social — Friends, Chat & Groups — Plan
+
+> **Status:** Planned
+> **Owner:** Platform team
+> **Feature ID:** `social`
+> **Godot version:** 4.6.2 stable
+> **Backend:** FastAPI + SQLAlchemy (async) + PostgreSQL + Redis
+
+## 1. Overview
+
+This document breaks the **Social** feature into user stories and right-sized
+implementation tasks. The feature delivers:
+
+- **Friends & following** — a friend request/accept model plus a one-way follow
+  relationship, with block lists.
+- **Presence & status** — online/offline, custom status message, last-seen.
+- **Chat** — direct messages (DM) and in-experience (world/room) chat with
+  **first-class safety**: server-side text filtering, report-message, and rate
+  limiting.
+- **Groups** — named groups with roles (owner/admin/member) and a simple group
+  page.
+- **Public profiles** — avatar, bio, favorite experiences, and a friends list
+  that respects privacy settings.
+
+## 2. Why chat safety is the differentiator
+
+The platform is explicitly meant to pull adults away from a youth-oriented
+competitor. Chat is the highest-risk surface: it is real-time, user-generated,
+and where abuse happens fastest. Safety is therefore treated as a **blocking
+requirement**, not an add-on:
+
+- Every message passes a **server-side text filter** before it is stored or
+  delivered. The client filter is cosmetic only; the server is authoritative.
+- Every message can be **reported**; reports flow into a moderation queue with
+  actor + reason + audit trail (mirroring `content_moderation.md`).
+- Sending is **rate limited** per user (Redis token bucket) to stop flooding and
+  harassment-by-volume.
+- Report and block are always reachable from a message context in the UI.
+
+## 3. Existing constraints (do not re-build)
+
+- **Auth:** JWT bearer tokens; `get_current_user` / `CurrentUser` dependency in
+  `app/dependencies.py`. All social endpoints reuse this.
+- **DB:** async SQLAlchemy + Alembic; migration `0001_initial` is the head.
+- **Redis:** configured (`REDIS_URL`) but unused so far; adopted here for
+  presence and rate limiting.
+- **Models:** `User`, `World` (owner_id), `Asset` (owner_id, is_public). Avatars
+  and favorite-experience references point at existing rows.
+- **Client:** Godot 4.6.2, minimal `main_menu.gd`; no social UI yet.
+
+## 4. Key design decisions
+
+| Concern | Decision |
+|---|---|
+| Message transport | REST for send/history; **WebSocket** gateway for real-time delivery + presence (matches `networking.md`'s "WebSocket as secondary transport" for chat) |
+| Presence store | Redis (TTL heartbeat) + persisted `last_seen_at` on the user record |
+| Text filtering | Pluggable `TextFilter` interface with a deterministic default (profanity list + normalization) so it runs without external services; third-party hook later |
+| Rate limiting | Redis token-bucket dependency, reusable across all social endpoints |
+| Reports | `message_reports` table + moderation endpoints (list/review/resolve) with audit fields |
+| Friends vs. follow | Friends = mutual (request→accept). Follow = one-way (no approval). Block = hard deny that also hides content and prevents DMs |
+| Privacy | Per-user settings JSON (`profile_visibility`, `friends_list_visibility`, `favorites_visibility`) enforced server-side on every read |
+| Groups | `groups` + `group_members` (role: owner/admin/member) + group page aggregate endpoint |
+| Real-time | One WebSocket endpoint multiplexing presence, DM, and world-chat messages via Redis pub/sub |
+
+## 5. User stories
+
+### US-1 Friends & following
+As a player, I can send a friend request, accept/decline incoming requests,
+unfriend, follow/unfollow other players, and block users so they can't interact
+with me.
+
+**Acceptance criteria**
+- Friend requests are one-directional until accepted; accepted friendships are mutual.
+- Follow is one-way and requires no approval.
+- Block prevents DMs, hides the blocked user's profile/friends interactions, and
+  removes any existing friendship/follow between the two.
+- Duplicate/self requests are rejected idempotently.
+
+### US-2 Presence & status
+As a player, I can see whether my friends are online, their custom status, and
+when they were last seen.
+
+**Acceptance criteria**
+- Online/offline is derived from a server-side heartbeat (Redis TTL), not client claims.
+- `last_seen_at` persists and is visible (subject to privacy settings).
+- Custom status text is optional and length-limited.
+
+### US-3 Public profiles
+As a player, I can view a public profile page showing avatar, bio, favorite
+experiences, and a friends list that respects the owner's privacy settings.
+
+**Acceptance criteria**
+- Avatar and bio are editable by the owner only.
+- Favorite experiences reference existing `World` rows.
+- A viewer sees only the sections the owner's privacy settings allow; blocked
+  users see a restricted view.
+
+### US-4 Chat (DM + in-experience) with safety
+As a player, I can send direct messages and chat inside a world/room. Messages
+are filtered, rate limited, and reportable.
+
+**Acceptance criteria**
+- Server filters message text before storing/delivering; filtered content is either
+  rejected (blocking) or redacted (configurable per filter policy).
+- Send rate is limited per user (token bucket); excess sends get `429`.
+- Every message has a stable id, author, timestamp, and conversation/world scope.
+- Any message can be reported with a reason; reports are stored and reviewable.
+- Real-time delivery over WebSocket with REST fallback for history.
+
+### US-5 Groups
+As a player, I can create a group, join/leave groups, and (as owner/admin)
+manage roles and view a simple group page.
+
+**Acceptance criteria**
+- Each group has exactly one owner and any number of admins/members.
+- Role transitions are authorized (only owner can transfer ownership or promote/demote admins).
+- Group page lists name, description, member list with roles, and member count.
+
+### US-6 Godot client
+As a player, I can access friends, presence, chat, profiles, and groups from the
+game UI.
+
+**Acceptance criteria**
+- An API client handles JWT auth, HTTP, and WebSocket for all social calls.
+- Dedicated screens/panels: friends+presence, DM & world chat (with report),
+  profile page, group page.
+- Client-side filtering is cosmetic; server responses remain authoritative.
+
+## 6. Task breakdown
+
+Right-sized to 1–3 files / one coherent piece of functionality each. Task IDs
+are sequential for dependency chaining.
+
+| # | Task | Story | Depends on |
+|---|------|-------|-----------|
+| 1 | Friends/follow/block models + Alembic migration | US-1 | — |
+| 2 | Friends & follow API router | US-1 | 1 |
+| 3 | Presence & status model + endpoints (Redis heartbeat) | US-2 | — |
+| 4 | Profile model + migration + own-profile endpoints | US-3 | 1 |
+| 5 | Public profile view + favorites + privacy enforcement | US-3 | 2, 4 |
+| 6 | Chat data models + migration (conversations, messages, reports) | US-4 | — |
+| 7 | Text filtering service + profanity config | US-4 | — |
+| 8 | Redis rate-limiting dependency | US-4 | — |
+| 9 | DM chat send/list endpoints (filter + rate limit) | US-4 | 6, 7, 8 |
+| 10 | Report-message endpoint + moderation queue | US-4 | 6, 9 |
+| 11 | In-experience (world/room) chat endpoints | US-4 | 9 |
+| 12 | Real-time WebSocket gateway (presence + DM + world chat) | US-4 | 3, 9, 11 |
+| 13 | Group + membership models + migration | US-5 | — |
+| 14 | Groups API (CRUD, join/leave, roles, group page) | US-5 | 13 |
+| 15 | Godot API client (auth + HTTP + WebSocket) | US-6 | 2 |
+| 16 | Godot friends & presence UI | US-6 | 3, 15 |
+| 17 | Godot chat UI (DM + world chat + report) | US-6 | 12, 15 |
+| 18 | Godot profile page UI | US-6 | 5, 15 |
+| 19 | Godot groups UI + group page | US-6 | 14, 15 |
+
+## 7. Phasing
+
+- **Phase 1 (data + core APIs):** tasks 1–5 (friends, presence, profiles).
+- **Phase 2 (chat safety — the differentiator):** tasks 6–12 (chat + safety +
+  realtime). This is the critical path and highest priority.
+- **Phase 3 (groups):** tasks 13–14.
+- **Phase 4 (client):** tasks 15–19, each landing after its backend dependency.
+
+## 8. Out of scope for this feature
+
+- Age verification / maturity gating (covered by `content_moderation.md`).
+- Voice chat, media/image messages, message editing/deletion history.
+- Third-party profanity/toxicity vendors (the `TextFilter` interface leaves a
+  hook, but the default is deterministic and dependency-free).
+- Mobile push notifications.

scripts/api_client.gd.uid

@@ -0,0 +1 @@
+uid://cjd0uhll7iylj

scripts/main_menu.gd.uid

@@ -0,0 +1 @@
+uid://bgnc3iamfgf6k