WIP checkpoint: Redis rate-limiting dependency

backend/alembic/versions/0001_initial.py

@@ -69,8 +69,7 @@ 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,
         ),
@@ -90,7 +89,7 @@ def upgrade() -> None:
             "asset_type",
             postgresql.ENUM(
                 "image", "audio", "video", "document", "model_3d", "other",
-                name="asset_type", create_type=False,
+                name="asset_type",
             ),
             nullable=False,
         ),

backend/alembic/versions/0002_add_date_of_birth_to_users.py

@@ -1,30 +0,0 @@
-"""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/app/config.py

@@ -16,6 +16,7 @@ class Settings(BaseSettings):
 
     # Redis
     REDIS_URL: str = "redis://localhost:6379/0"
+    REDIS_TIMEOUT_SECONDS: float = 2.0
 
     # JWT / Auth
     # NOTE: production must override SECRET_KEY with a secure random value
@@ -30,7 +31,6 @@ 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",

backend/app/models/user.py

@@ -1,7 +1,4 @@
-from datetime import date
+from sqlalchemy import Column, Integer, String, Boolean, DateTime
-from typing import Optional
-
-from sqlalchemy import Column, Integer, String, Boolean, DateTime, Date
 from sqlalchemy.orm import relationship
 from sqlalchemy.sql import func
 
@@ -15,7 +12,6 @@ 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())
@@ -23,15 +19,3 @@ class User(Base):
     sessions = relationship("Session", 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/rate_limit.py

@@ -0,0 +1,293 @@
+"""Redis-backed token-bucket rate limiting.
+
+This module provides a reusable FastAPI dependency that rate-limits requests
+per endpoint scope (optionally per-user) using an atomic Lua script on Redis.
+
+If Redis is unavailable the limiter can either allow the request through
+(fail-open) or reject it with a ``503`` (fail-closed), depending on the
+policy configured for that limit. Chat send uses fail-closed by default
+because flooding/abuse is worse than a temporary outage.
+
+Example
+-------
+    from app.rate_limit import rate_limit, named_limit
+
+    chat_send_limit = rate_limit(
+        named_limit("chat_send", capacity=5, refill_rate=0.2, fail_open=False),
+        user_id_dependency=Depends(get_current_user_id),
+    )
+
+    @router.post("/messages")
+    async def send_message(
+        payload: MessageCreate,
+        current_user: CurrentUser,
+        db: DbDep,
+        _: None = Depends(chat_send_limit),
+    ):
+        ...
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable
+
+from fastapi import Depends, HTTPException, Request, status
+from redis.asyncio import Redis
+from redis.exceptions import RedisError
+
+from app.config import settings
+
+# Atomic token-bucket implementation.
+#
+# KEYS[1] is the bucket key. ARGV[1] is the bucket capacity, ARGV[2] is the
+# refill rate in tokens per second, ARGV[3] is the current Unix time in
+# seconds (float), and ARGV[4] is the request cost (tokens to take).
+#
+# The bucket state is stored as a hash with "tokens" and "ts". The script
+# refills the bucket up to capacity, then takes the requested tokens. It
+# returns an array:
+#   [0] allowed (1 or 0)
+#   [1] tokens remaining after the take
+#   [2] retry-after seconds (0 when allowed)
+_TOKEN_BUCKET_LUA = """
+local key = KEYS[1]
+local capacity = tonumber(ARGV[1])
+local refill_rate = tonumber(ARGV[2])
+local now = tonumber(ARGV[3])
+local cost = tonumber(ARGV[4])
+
+local state = redis.call("HMGET", key, "tokens", "ts")
+local tokens = capacity
+local ts = now
+
+if state[1] ~= false then
+    tokens = tonumber(state[1])
+    ts = tonumber(state[2]) or now
+end
+
+local elapsed = math.max(0, now - ts)
+tokens = math.min(capacity, tokens + (elapsed * refill_rate))
+
+local allowed = 0
+local retry_after = 0
+
+if tokens >= cost then
+    tokens = tokens - cost
+    allowed = 1
+else
+    -- Time until enough tokens for a single request have accrued.
+    retry_after = math.ceil((cost - tokens) / refill_rate)
+end
+
+-- Keep the bucket state small and expire-able. Retaining the timestamp as a
+-- float lets partial tokens accumulate smoothly between requests.
+redis.call("HSET", key, "tokens", tostring(tokens), "ts", tostring(now))
+redis.call("PEXPIRE", key, 600000)
+
+return {allowed, tostring(tokens), retry_after}
+"""
+
+
+class RateLimitExceeded(HTTPException):
+    """Raised when a rate-limit bucket has no tokens left."""
+
+    def __init__(self, retry_after: int) -> None:
+        super().__init__(
+            status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+            detail="Rate limit exceeded",
+            headers={"Retry-After": str(retry_after)},
+        )
+
+
+@dataclass(frozen=True)
+class RateLimit:
+    """Definition of a named token-bucket rate limit.
+
+    ``capacity`` is the burst size and ``refill_rate`` is the steady-state
+    token accumulation rate (tokens/second). For example,
+    ``RateLimit(name="chat_send", capacity=10, refill_rate=1.0)`` allows a
+    burst of 10 requests and then one request per second on average.
+    """
+
+    name: str
+    capacity: int
+    refill_rate: float
+    # When Redis is unreachable: ``True`` allows the request (fail-open),
+    # ``False`` rejects it with 503 (fail-closed).
+    fail_open: bool = True
+
+    def __post_init__(self) -> None:
+        if not self.name:
+            raise ValueError("name must be non-empty")
+        if self.capacity <= 0:
+            raise ValueError("capacity must be positive")
+        if self.refill_rate <= 0:
+            raise ValueError("refill_rate must be positive")
+
+
+def default_user_scope(request: Request, user_id: int | None) -> str:
+    """Scope a bucket per authenticated user, or per client IP if anonymous."""
+    if user_id is not None:
+        return f"user:{user_id}"
+    client = request.client
+    return f"ip:{client.host if client else 'unknown'}"
+
+
+@dataclass(frozen=True)
+class RateLimitConfig:
+    """A named rate limit plus how it is applied to a request."""
+
+    limit: RateLimit
+    # Builds the Redis key fragment for the request. The resolved user id is
+    # passed as the second argument (or ``None`` for anonymous limits).
+    scope: Callable[[Request, int | None], str] = default_user_scope
+
+
+@dataclass(frozen=True)
+class RateLimitResult:
+    """Outcome of a rate-limit check (used by tests)."""
+
+    allowed: bool
+    remaining: int
+    retry_after: int
+
+
+_redis_client: Redis | None = None
+
+
+def get_redis() -> Redis:
+    """Return a shared async Redis client for rate limiting.
+
+    The client is created lazily (``Redis.from_url`` does not connect until a
+    command is issued), so this dependency never blocks or fails just because
+    Redis is down.
+    """
+    global _redis_client
+    if _redis_client is None:
+        _redis_client = Redis.from_url(
+            settings.REDIS_URL,
+            encoding="utf-8",
+            decode_responses=True,
+            socket_connect_timeout=settings.REDIS_TIMEOUT_SECONDS,
+            socket_timeout=settings.REDIS_TIMEOUT_SECONDS,
+        )
+    return _redis_client
+
+
+class RateLimiter:
+    """Enforce a token bucket in Redis.
+
+    Buckets are keyed as ``rate:{limit.name}:{scope_key}`` so multiple
+    endpoints can share a named limit while remaining independently bucketed.
+    """
+
+    def __init__(self, config: RateLimitConfig, redis: Redis | None = None) -> None:
+        self._config = config
+        self._redis = redis
+
+    def _redis_client(self) -> Redis:
+        return self._redis or get_redis()
+
+    def _bucket_key(self, request: Request, user_id: int | None) -> str:
+        limit = self._config.limit
+        scope_key = self._config.scope(request, user_id)
+        return f"rate:{limit.name}:{scope_key}"
+
+    async def check(self, request: Request, user_id: int | None = None) -> RateLimitResult:
+        """Atomically refill/take a token and return the outcome.
+
+        Redis failures are mapped to ``allowed=True`` (fail-open) or
+        ``allowed=False`` (fail-closed, represented with ``retry_after=-1``)
+        according to the limit's policy, without raising.
+        """
+        limit = self._config.limit
+        key = self._bucket_key(request, user_id)
+
+        try:
+            result = await self._redis_client().eval(
+                _TOKEN_BUCKET_LUA,
+                1,
+                key,
+                str(limit.capacity),
+                str(limit.refill_rate),
+                str(time.time()),
+                "1",  # each request consumes one token
+            )
+        except RedisError:
+            if limit.fail_open:
+                return RateLimitResult(allowed=True, remaining=0, retry_after=0)
+            # Fail-closed: no reliable retry estimate is available.
+            return RateLimitResult(allowed=False, remaining=0, retry_after=-1)
+
+        # Redis may return ints or strings depending on decode_responses.
+        allowed = bool(int(result[0]))
+        remaining = int(result[1])
+        retry_after = int(result[2])
+        return RateLimitResult(allowed=allowed, remaining=remaining, retry_after=retry_after)
+
+    async def __call__(self, request: Request, user_id: int | None = None) -> None:
+        """Enforce the rate limit, raising 429 or 503 as appropriate."""
+        result = await self.check(request, user_id)
+        if result.allowed:
+            return
+
+        if result.retry_after < 0:
+            # Redis was unavailable and this limit is fail-closed.
+            raise HTTPException(
+                status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+                detail="Rate limiting service unavailable",
+            )
+        raise RateLimitExceeded(retry_after=result.retry_after)
+
+
+def named_limit(
+    name: str,
+    *,
+    capacity: int,
+    refill_rate: float,
+    fail_open: bool = True,
+) -> RateLimitConfig:
+    """Create a named rate-limit config with the default per-user/IP scope.
+
+    ``capacity`` is the burst size and ``refill_rate`` is tokens/second.
+    """
+    return RateLimitConfig(
+        limit=RateLimit(
+            name=name,
+            capacity=capacity,
+            refill_rate=refill_rate,
+            fail_open=fail_open,
+        )
+    )
+
+
+def rate_limit(
+    config: RateLimitConfig,
+    *,
+    user_id_dependency: Any = None,
+) -> Callable[[Request, Any], Awaitable[None]]:
+    """Build a FastAPI dependency enforcing ``config``.
+
+    ``user_id_dependency`` optionally injects the authenticated user id, e.g.
+    ``Depends(get_current_user_id)``. If omitted the limiter buckets by client
+    IP (the ``default_user_scope`` fallback), which is suitable for anonymous
+    endpoints but should be paired with an auth resolver for per-user limits.
+
+    The returned callable is intended for ``Depends(...)``.
+    """
+
+    async def _anonymous_user_id() -> int | None:
+        return None
+
+    resolver = user_id_dependency if user_id_dependency is not None else Depends(_anonymous_user_id)
+
+    async def dependency(
+        request: Request,
+        user_id: int | None = resolver,
+    ) -> None:
+        limiter = RateLimiter(config)
+        await limiter(request, user_id)
+
+    return dependency

backend/app/routers/assets.py

@@ -1,6 +1,5 @@
 """Asset management router."""
 
-import json
 import os
 from pathlib import Path
 from typing import Optional
@@ -14,7 +13,6 @@ 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()
@@ -66,14 +64,6 @@ 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)
@@ -193,16 +183,10 @@ async def upload_asset_file(
     # Sanitize filename to prevent path traversal.
     safe_filename = _sanitize_filename(file.filename or f"asset_{asset_id}")
 
-    # Read the file content.
+    # Validate file size against configured maximum.
+    max_bytes = settings.MAX_UPLOAD_SIZE_MB * 1024 * 1024
     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,
@@ -216,28 +200,10 @@ 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,10 +1,10 @@
 """Authentication router - login, register, token refresh."""
 
-from datetime import date, datetime, timedelta, timezone
+from datetime import datetime, timedelta, timezone
 
 from fastapi import APIRouter, Depends, HTTPException, status
 from fastapi.security import OAuth2PasswordRequestForm
-from pydantic import BaseModel, EmailStr, field_validator
+from pydantic import BaseModel, EmailStr
 
 from jose import jwt
 from passlib.context import CryptContext
@@ -32,24 +32,12 @@ 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
 
@@ -77,44 +65,11 @@ def hash_password(password: str) -> str:
     return pwd_context.hash(password)
 
 
-def calculate_age(birth_date: date, today: date | None = 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
-
-
 # --- 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 an access token."""
-
-    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():
@@ -135,7 +90,6 @@ 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()

backend/app/services/gltf.py

@@ -1,197 +0,0 @@
-"""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:
-      - "${POSTGRES_HOST_PORT:-5432}:5432"
+      - "5432:5432"
     volumes:
       - postgres_data:/var/lib/postgresql/data
     healthcheck:
@@ -20,7 +20,7 @@ services:
   redis:
     image: redis:7-alpine
     ports:
-      - "${REDIS_HOST_PORT:-6379}:6379"
+      - "6379:6379"
     volumes:
       - redis_data:/data
     healthcheck:

backend/pytest.ini

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

backend/tests/test_auth_age_gate.py

@@ -1,94 +0,0 @@
-"""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

@@ -1,220 +0,0 @@
-"""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]")

backend/tests/test_rate_limit.py

@@ -0,0 +1,193 @@
+"""Tests for the Redis-backed token-bucket rate limiter.
+
+These tests use fakeredis (Lua enabled via lupa) so no live Redis server is
+required.
+"""
+
+import asyncio
+import sys
+
+import pytest
+from fastapi import Depends, FastAPI, Request
+from fastapi.testclient import TestClient
+
+sys.path.insert(0, "/workspace")
+
+import fakeredis.aioredis
+from redis.asyncio import Redis
+from redis.exceptions import ConnectionError
+
+from app.rate_limit import (
+    RateLimit,
+    RateLimitConfig,
+    RateLimiter,
+    default_user_scope,
+    named_limit,
+    rate_limit,
+)
+
+
+@pytest.fixture()
+def fake_redis():
+    return fakeredis.aioredis.FakeRedis(decode_responses=True)
+
+
+def make_request(client_ip: str = "127.0.0.1") -> Request:
+    scope = {
+        "type": "http",
+        "method": "GET",
+        "path": "/",
+        "headers": [],
+        "client": (client_ip, 12345),
+    }
+    return Request(scope)
+
+
+@pytest.mark.asyncio
+async def test_token_bucket_allows_burst_then_exhausts(fake_redis):
+    limiter = RateLimiter(
+        RateLimitConfig(
+            limit=RateLimit(name="burst", capacity=3, refill_rate=0.1),
+        ),
+        redis=fake_redis,
+    )
+    request = make_request()
+
+    results = []
+    for _ in range(4):
+        result = await limiter.check(request, user_id=42)
+        results.append(result)
+
+    assert [r.allowed for r in results] == [True, True, True, False]
+    assert results[0].remaining == 2
+    assert results[1].remaining == 1
+    assert results[2].remaining == 0
+    assert results[3].retry_after > 0
+
+
+@pytest.mark.asyncio
+async def test_retry_after_reflects_refill_rate(fake_redis):
+    limiter = RateLimiter(
+        RateLimitConfig(
+            limit=RateLimit(name="slow", capacity=1, refill_rate=0.5),
+        ),
+        redis=fake_redis,
+    )
+    request = make_request()
+
+    assert (await limiter.check(request, user_id=7)).allowed is True
+    denied = await limiter.check(request, user_id=7)
+    assert denied.allowed is False
+    # 1 token / 0.5 tokens per second = 2 seconds.
+    assert denied.retry_after == 2
+
+
+@pytest.mark.asyncio
+async def test_separate_scopes_get_separate_buckets(fake_redis):
+    limiter = RateLimiter(
+        RateLimitConfig(
+            limit=RateLimit(name="scoped", capacity=1, refill_rate=0.1),
+        ),
+        redis=fake_redis,
+    )
+    request = make_request()
+
+    assert (await limiter.check(request, user_id=1)).allowed is True
+    assert (await limiter.check(request, user_id=2)).allowed is True
+    assert (await limiter.check(request, user_id=1)).allowed is False
+
+
+@pytest.mark.asyncio
+async def test_fail_open_returns_allowed_when_redis_unavailable():
+    class BrokenRedis(Redis):
+        async def eval(self, *args, **kwargs):
+            raise ConnectionError("down")
+
+    limiter = RateLimiter(
+        RateLimitConfig(
+            limit=RateLimit(name="open", capacity=1, refill_rate=0.1, fail_open=True),
+        ),
+        redis=BrokenRedis(),
+    )
+    result = await limiter.check(make_request(), user_id=1)
+    assert result.allowed is True
+
+
+@pytest.mark.asyncio
+async def test_fail_closed_returns_denied_with_negative_retry_after():
+    class BrokenRedis(Redis):
+        async def eval(self, *args, **kwargs):
+            raise ConnectionError("down")
+
+    limiter = RateLimiter(
+        RateLimitConfig(
+            limit=RateLimit(name="closed", capacity=1, refill_rate=0.1, fail_open=False),
+        ),
+        redis=BrokenRedis(),
+    )
+    result = await limiter.check(make_request(), user_id=1)
+    assert result.allowed is False
+    assert result.retry_after == -1
+
+
+@pytest.mark.asyncio
+async def test_fail_closed_call_raises_503(fake_redis):
+    class BrokenRedis(Redis):
+        async def eval(self, *args, **kwargs):
+            raise ConnectionError("down")
+
+    limiter = RateLimiter(
+        RateLimitConfig(
+            limit=RateLimit(name="closed", capacity=1, refill_rate=0.1, fail_open=False),
+        ),
+        redis=BrokenRedis(),
+    )
+    with pytest.raises(Exception) as exc_info:
+        await limiter(make_request(), user_id=1)
+    assert exc_info.value.status_code == 503
+
+
+def test_named_limit_builds_expected_config():
+    config = named_limit(
+        "chat_send",
+        capacity=5,
+        refill_rate=0.2,
+        fail_open=False,
+    )
+    assert config.limit.name == "chat_send"
+    assert config.limit.capacity == 5
+    assert config.limit.refill_rate == 0.2
+    assert config.limit.fail_open is False
+    assert config.scope is default_user_scope
+
+
+def test_invalid_limit_definition_rejected():
+    with pytest.raises(ValueError):
+        named_limit("bad", capacity=0, refill_rate=1.0)
+    with pytest.raises(ValueError):
+        named_limit("bad", capacity=1, refill_rate=0)
+
+
+def test_dependency_integration_returns_429_with_retry_after():
+    async def fake_user_id() -> int:
+        return 99
+
+    chat_limit = rate_limit(
+        named_limit("chat_send_test", capacity=2, refill_rate=0.1, fail_open=False),
+        user_id_dependency=Depends(fake_user_id),
+    )
+
+    app = FastAPI()
+
+    @app.get("/probe")
+    async def probe(_: None = Depends(chat_limit)):
+        return {"ok": True}
+
+    client = TestClient(app)
+    assert client.get("/probe").status_code == 200
+    assert client.get("/probe").status_code == 200
+
+    denied = client.get("/probe")
+    assert denied.status_code == 429
+    assert denied.headers["retry-after"]
+    assert denied.json() == {"detail": "Rate limit exceeded"}

docs/planning/client-server-wiring.md

@@ -1,41 +0,0 @@
-# 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 + register** UI built & wired (form-encoded + JSON/age gate) | 1 |
-| 3 | implementation | **World list** screen consuming `GET /api/worlds` | 1 |
-| 4 | testing | End-to-end headless smoke test + manual verify | 1,2,3 |
-
-## 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.
-
-## Notes
-- The main-menu auth UI does **not** exist yet (main_menu.gd currently has only Play/Quit
-  stubs). Task 2 must **build** the login/register UI, not merely wire an existing one.
-- The world-list screen also needs to be **built** (a new scene), not just wired.

docs/planning/economy.md

@@ -1,295 +0,0 @@
-# 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).