very minor bugfixes, really nothing too important

src/random_access/__init__.py

@@ -0,0 +1,7 @@
+"""Random Access - A FastAPI app with secure authentication, Redis caching, and Airtable integration."""
+
+__version__ = "0.0.1"
+__author__ = "Micha R. Albert"
+__email__ = "info@micha.zone"
+
+__all__ = ["__version__", "__author__", "__email__"]

src/random_access/auth.py

@@ -0,0 +1,124 @@
+"""Authentication utilities and endpoints."""
+
+import hashlib
+import hmac
+from datetime import datetime, timedelta
+
+from fastapi import HTTPException, status
+from pyairtable.formulas import match
+
+from random_access.security import validate_bearer_token_format, create_safe_error_response
+from random_access.settings import settings
+
+
+def hash_token(token: str) -> str:
+    """Hash a token using SHA256."""
+    return hashlib.sha256(token.encode()).hexdigest()
+
+
+async def get_session_by_token(token: str, sessions_table) -> dict | None:
+    """Get a session by its hashed token (now using cached version)."""
+    from random_access.database import get_session_by_token_cached
+    return await get_session_by_token_cached(token, sessions_table)
+
+
+def is_session_expired(session: dict) -> bool:
+    """Check if a session has expired based on creation time."""
+    created_at = session["fields"].get("Created")
+    if not created_at:
+        return True
+    
+    try:
+        created_time = datetime.fromisoformat(created_at.replace('Z', '+00:00'))
+        expiry_time = created_time + timedelta(hours=settings.session_ttl_hours)
+        return datetime.now().replace(tzinfo=created_time.tzinfo) > expiry_time
+    except (ValueError, TypeError):
+        # If we can't parse the date, consider it expired for safety
+        return True
+
+
+async def decode_oidc_state(state: str, sessions_table) -> tuple[str, str, str]:
+    """Decode and validate OIDC state token."""
+    try:
+        # Expecting format: {secure_token}.{game_hash}.{game_id}
+        parts = state.split(".")
+        if len(parts) != 3:
+            raise ValueError("OIDC state format invalid")
+        
+        secure_token, game_hash, game_id = parts
+    except ValueError:
+        raise ValueError("OIDC state format invalid")
+
+    # Validate game hash
+    expected_hash = hashlib.sha256(
+        f"{game_id}.{settings.game_id_salt}".encode("utf-8")
+    ).hexdigest()
+
+    if not hmac.compare_digest(expected_hash, game_hash):
+        raise ValueError("Invalid game hash")
+
+    # Look up session by the secure token (not the full state)
+    session = await get_session_by_token(secure_token, sessions_table)
+    if not session:
+        raise ValueError("Session not found")
+    
+    # Check session expiration
+    if is_session_expired(session):
+        raise ValueError("Session has expired")
+
+    return game_id, secure_token, session["id"]
+
+
+async def extract_and_validate_auth(authorization: str, sessions_table, users_table):
+    """Extract and validate authentication token, return game_id, session, and user."""
+    try:
+        full_token = validate_bearer_token_format(authorization)
+    except HTTPException:
+        raise
+    
+    try:
+        game_id, token_id, session_rec_id = await decode_oidc_state(full_token, sessions_table)
+    except ValueError as e:
+        if settings.is_production:
+            detail = "Invalid authentication token"
+        else:
+            detail = str(e)
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail=detail
+        )
+    
+    # Get session using the hashed token
+    session = sessions_table.first(formula=match({"Token": hash_token(token_id)}))
+    if not session:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid session token"
+        )
+    
+    # Check session expiration
+    if is_session_expired(session):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Session has expired"
+        )
+    
+    # Get the user from the session
+    user_id = session["fields"].get("User")
+    if not user_id:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Session not linked to a user"
+        )
+    
+    user = users_table.get(user_id[0])  # User is stored as a list in Airtable
+    if not user:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="User not found"
+        )
+    
+    return game_id, session, user
+
+
+# Removed unused SessionStore class for cleaner codebase

src/random_access/database.py

@@ -0,0 +1,276 @@
+"""Airtable database utilities with Redis caching and rate-limited writes."""
+
+import asyncio
+import datetime
+import hashlib
+import logging
+import os
+from typing import Any, Dict, List, Optional
+
+from aiocache import Cache, cached
+from aiocache.serializers import PickleSerializer
+from pyairtable import Api as AirtableApi
+from pyairtable.formulas import match
+
+logger = logging.getLogger("uvicorn.error")
+
+# Global queue for write operations
+write_queue: asyncio.Queue = asyncio.Queue()
+
+def get_airtable_base():
+    """Get the Airtable base instance."""
+    return AirtableApi(os.environ["AIRTABLE_PAT"]).base(os.environ["AIRTABLE_BASE"])
+
+
+def get_table(base, name: str):
+    """Get a specific Airtable table."""
+    return base.table(os.environ[f"AIRTABLE_{name.upper()}_TABLE"])
+
+
+async def invalidate_user_items_cache(user_id: str):
+    """Invalidate the cached user items for a specific user."""
+    # Simple approach: just log the invalidation request
+    # The actual cache will expire naturally based on TTL (5 minutes)
+    # This ensures we don't block the API if Redis is unavailable
+    logger.info(f"Cache invalidation requested for user ID: {user_id} (will expire naturally in 5 minutes)")
+    
+    # TODO: Implement proper cache invalidation when Redis connection is stable
+    # For now, users will see new items after the 5-minute cache TTL expires
+
+
+def _generate_cache_key(*args, **kwargs) -> str:
+    """Generate a consistent cache key from function arguments."""
+    key_parts = [str(arg) for arg in args]
+    key_parts.extend([f"{k}:{v}" for k, v in sorted(kwargs.items())])
+    key_string = "|".join(key_parts)
+    return hashlib.md5(key_string.encode()).hexdigest()
+
+
+# READ OPERATIONS (Cached)
+
+@cached(
+    ttl=300,  # 5 minutes
+    cache=Cache.REDIS,  # type: ignore
+    serializer=PickleSerializer(),
+    port=6379,
+    namespace="airtable_reads",
+    key_builder=lambda f, *args, **kwargs: _generate_cache_key(f.__name__, *args, **kwargs)
+)
+async def get_user_record(slack_user_id: str, users_table) -> dict:
+    """Get user record from Airtable by Slack ID."""
+    logger.info(f"Fetching user record from Airtable for Slack ID: {slack_user_id}")
+    user_rec = users_table.first(formula=match({"Slack ID": slack_user_id}))
+    if not user_rec or "id" not in user_rec:
+        raise ValueError("User not found in Airtable")
+    return dict(user_rec)
+
+
+@cached(
+    ttl=300,  # 5 minutes
+    cache=Cache.REDIS,  # type: ignore
+    serializer=PickleSerializer(),
+    port=6379,
+    namespace="airtable_reads",
+    key_builder=lambda f, *args, **kwargs: _generate_cache_key(f.__name__, *args, **kwargs)
+)
+async def get_game_record(game_id: str, submissions_table) -> dict:
+    """Get game record from Airtable."""
+    logger.info(f"Fetching game record from Airtable for ID: {game_id}")
+    game_rec = submissions_table.get(game_id)
+    if not game_rec or "id" not in game_rec:
+        raise ValueError("Game not found in Airtable")
+    return dict(game_rec)
+
+
+@cached(
+    ttl=180,  # 3 minutes
+    cache=Cache.REDIS,  # type: ignore
+    serializer=PickleSerializer(),
+    port=6379,
+    namespace="airtable_reads",
+    key_builder=lambda f, *args, **kwargs: _generate_cache_key(f.__name__, *args, **kwargs)
+)
+async def get_all_items(items_table):
+    """Get all items from Airtable."""
+    logger.info("Fetching all items from Airtable")
+    return items_table.all()
+
+
+@cached(
+    ttl=60,  # 1 minute
+    cache=Cache.REDIS,  # type: ignore
+    serializer=PickleSerializer(),
+    port=6379,
+    namespace="airtable_reads",
+    key_builder=lambda f, *args, **kwargs: _generate_cache_key(f.__name__, *args, **kwargs)
+)
+async def get_session_by_token_cached(token: str, sessions_table) -> Optional[dict]:
+    """Get session by token from Airtable (cached)."""
+    hashed = hashlib.sha256(token.encode("utf-8")).hexdigest()
+    session = sessions_table.first(formula=match({"Token": hashed}))
+    if session:
+        return dict(session)
+    return None
+
+
+@cached(
+    ttl=300,  # 5 minutes
+    cache=Cache.REDIS,  # type: ignore
+    serializer=PickleSerializer(),
+    port=6379,
+    namespace="airtable_reads",
+    key_builder=lambda f, *args, **kwargs: _generate_cache_key(f.__name__, *args, **kwargs)
+)
+async def get_user_items(user_id: str, users_table) -> List[dict]:
+    """Get all items for a user from the Users table Items field (cached)."""
+    logger.info(f"Fetching user items from Users table for user ID: {user_id}")
+    try:
+        user_record = users_table.get(user_id)
+        items_field = user_record.get("fields", {}).get("Items", [])
+        logger.info(f"User {user_id} has {len(items_field)} items")
+        return items_field  # This returns a list of item IDs
+    except Exception as e:
+        logger.error(f"Error fetching user items: {e}")
+        return []
+
+
+@cached(
+    ttl=300,  # 5 minutes
+    cache=Cache.REDIS,  # type: ignore
+    serializer=PickleSerializer(),
+    port=6379,
+    namespace="airtable_reads",
+    key_builder=lambda f, *args, **kwargs: _generate_cache_key(f.__name__, *args, **kwargs)
+)
+async def get_item_by_id(item_id: str, items_table) -> Optional[dict]:
+    """Get a specific item by ID (cached)."""
+    logger.info(f"Fetching item from Airtable for ID: {item_id}")
+    try:
+        item = items_table.get(item_id)
+        return dict(item) if item else None
+    except Exception:
+        return None
+
+
+# WRITE OPERATIONS (Queued)
+
+async def queue_airtable_write(operation: str, table, *args, **kwargs):
+    """Queue an Airtable write operation."""
+    write_operation = {
+        "operation": operation,
+        "table": table,
+        "args": args,
+        "kwargs": kwargs,
+        "timestamp": datetime.datetime.now().isoformat()
+    }
+    await write_queue.put(write_operation)
+    logger.info(f"Queued Airtable {operation} operation")
+
+
+async def create_session(fields: dict, sessions_table):
+    """Create a new session (immediate write for session creation)."""
+    # Session creation needs immediate response, so we do it synchronously
+    session = sessions_table.create(fields=fields)
+    logger.info(f"Created session: {session['id']}")
+    return session
+
+
+async def add_item_to_user(item_id: str, user_id: str, users_table):
+    """Add an item to a user's Items list in the Users table (queued write)."""
+    try:
+        # Get the current user record to see existing items
+        current_user = users_table.get(user_id)
+        current_items = current_user.get("fields", {}).get("Items", [])
+        
+        # Add item if not already in the list
+        if item_id not in current_items:
+            updated_items = current_items + [item_id]
+            fields = {"Items": updated_items}
+            await queue_airtable_write("update", users_table, user_id, fields)
+            logger.info(f"Added item {item_id} to user {user_id}")
+        else:
+            logger.info(f"User {user_id} already has item {item_id}")
+    except Exception as e:
+        logger.error(f"Error adding item {item_id} to user {user_id}: {e}")
+
+
+# Legacy function name for backwards compatibility
+async def create_item_instance(fields: dict, items_table):
+    """Create a new item instance (queued write)."""
+    await queue_airtable_write("create", items_table, fields)
+
+
+async def update_user_last_login(user_id: str, users_table):
+    """Update user's last login timestamp (queued write)."""
+    fields = {"Last Login": datetime.datetime.now().isoformat()}
+    await queue_airtable_write("update", users_table, user_id, fields)
+
+
+async def update_session_user_game(session_id: str, user_id: str, game_id: str, sessions_table):
+    """Update session with user and game (queued write)."""
+    fields = {"User": [user_id], "Game": [game_id]}
+    await queue_airtable_write("update", sessions_table, session_id, fields)
+
+
+async def update_user_and_session(user_rec: dict, game_rec: dict, session_id: str, users_table, sessions_table):
+    """Update user last login and link session to user and game (queued writes)."""
+    await update_user_last_login(user_rec["id"], users_table)
+    await update_session_user_game(session_id, user_rec["id"], game_rec["id"], sessions_table)
+
+
+# CACHE INVALIDATION
+
+async def invalidate_user_cache(slack_user_id: str):
+    """Invalidate cached user data."""
+    logger.info(f"Cache invalidation requested for Slack ID: {slack_user_id}")
+    # For now, we'll rely on TTL expiration
+    # Future: implement proper cache invalidation
+
+
+# RATE-LIMITED WRITE WORKER
+
+async def airtable_write_worker():
+    """Process queued Airtable write operations at max 5 per second."""
+    rate_limit_delay = 0.2  # 200ms = 5 operations per second
+    
+    while True:
+        try:
+            # Wait for an operation
+            operation = await write_queue.get()
+            
+            # Process the operation
+            table = operation["table"]
+            op_type = operation["operation"]
+            args = operation["args"]
+            kwargs = operation["kwargs"]
+            
+            try:
+                if op_type == "create":
+                    result = table.create(*args, **kwargs)
+                    logger.info(f"Completed Airtable create operation: {result.get('id', 'unknown')}")
+                elif op_type == "update":
+                    result = table.update(*args, **kwargs)
+                    logger.info(f"Completed Airtable update operation")
+                elif op_type == "delete":
+                    result = table.delete(*args, **kwargs)
+                    logger.info(f"Completed Airtable delete operation")
+                else:
+                    logger.error(f"Unknown operation type: {op_type}")
+                    
+            except Exception as e:
+                logger.error(f"Airtable {op_type} operation failed: {e}")
+            
+            # Mark task as done
+            write_queue.task_done()
+            
+            # Rate limiting: wait before processing next operation
+            await asyncio.sleep(rate_limit_delay)
+            
+        except Exception as e:
+            logger.error(f"Error in airtable_write_worker: {e}")
+            await asyncio.sleep(1)  # Wait before retrying
+
+
+def get_write_queue() -> asyncio.Queue:
+    """Get the global write queue."""
+    return write_queue

src/random_access/main.py

@@ -1,187 +1,135 @@
-from logging import Logger
-import os
-import secrets
-from contextlib import asynccontextmanager
-from urllib.parse import urlencode
-from typing import Annotated, Any
+"""FastAPI application main entry point."""
 
+import asyncio
+import logging
+from collections import namedtuple
+from contextlib import asynccontextmanager
 
 from dotenv import load_dotenv
-from fastapi import Depends, FastAPI, Header, HTTPException, Request
-from fastapi.responses import RedirectResponse
+from fastapi import FastAPI, Request, Response, HTTPException
+from fastapi.responses import JSONResponse
+from fastapi.middleware.cors import CORSMiddleware
+from slowapi import Limiter, _rate_limit_exceeded_handler
+from slowapi.errors import RateLimitExceeded
+from slowapi.middleware import SlowAPIMiddleware
 from slack_bolt.adapter.fastapi.async_handler import AsyncSlackRequestHandler
-from slack_bolt.async_app import AsyncAck, AsyncApp, AsyncRespond, AsyncSay
-from slack_bolt.response import BoltResponse
-from tortoise import Tortoise
 
-from .models import User, UserCreate, UserResponse, UserUpdate
+from random_access.database import get_airtable_base, get_table, airtable_write_worker
+from random_access.routes.auth import create_auth_router
+from random_access.routes.items import create_items_router, create_user_items_router
+from random_access.routes.system import create_system_router
+from random_access.routes.users import create_users_router
+from random_access.security import get_client_ip, SecurityHeaders
+from random_access.settings import settings
+from random_access.slack_integration import create_slack_app, setup_slack_handlers
 
+Result = namedtuple("Result", "content, status")
+
+logger = logging.getLogger("uvicorn.error")
 
 if not load_dotenv():
     raise FileNotFoundError("Environment secrets not found!")
 
+# Initialize rate limiter
+limiter = Limiter(key_func=get_client_ip)
 
+# Initialize Airtable
+at_base = get_airtable_base()
+SUBMISSIONS = get_table(at_base, "submissions")
+USERS = get_table(at_base, "users")
+SESSIONS = get_table(at_base, "sessions")
+ITEMS = get_table(at_base, "items")
+ITEM_ADDONS = get_table(at_base, "item_addons")
 
-@asynccontextmanager
-async def lifespan(_: FastAPI):
-    await Tortoise.init(
-        db_url="sqlite://random_access.db", modules={"models": ["random_access.models"]}
-    )
-    await Tortoise.generate_schemas()
-    yield
-    await Tortoise.close_connections()
-
-
-slack = AsyncApp(
-    signing_secret=os.getenv("SLACK_SIGNING_SECRET")
-)
+slack = create_slack_app()
+setup_slack_handlers(slack)
 slack_handler = AsyncSlackRequestHandler(slack)
 
 
-@slack.event("app_mention") # pyright:ignore[reportUnknownMemberType]
-async def handle_app_mentions(body: BoltResponse, say: AsyncSay, logger: Logger):
-    logger.info(body)
-    _ = await say("What's up?")
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Application lifespan manager."""
+    asyncio.create_task(airtable_write_worker())
+    yield
 
 
-@slack.event("message") # pyright:ignore[reportUnknownMemberType]
-async def handle_message():
-    pass
+app = FastAPI(
+    title="Random Access API", 
+    version="0.1.0", 
+    lifespan=lifespan, 
+    description="Secure API for Random Access game integration"
+)
 
-@slack.command("/random-access") # pyright:ignore[reportUnknownMemberType]  
-async def handle_command(ack: AsyncAck, body: BoltResponse, respond: AsyncRespond):
-    await ack()
-    subcommand = dict(body).get('text') # type: ignore
-    print(subcommand)
+# Security middleware
+app.state.limiter = limiter
+
+# Custom rate limit exception handler
+@app.exception_handler(RateLimitExceeded)
+async def rate_limit_handler(request: Request, exc: RateLimitExceeded):
+    """Custom rate limit exceeded handler."""
+    return JSONResponse(
+        status_code=429,
+        content={"detail": f"Rate limit exceeded: {exc.detail}"},
+        headers={
+            "X-RateLimit-Limit": str(getattr(exc, 'limit', settings.rate_limit_requests)),
+            "Retry-After": "60"  # Default retry after 60 seconds
+        }
+    )
+
+app.add_middleware(SlowAPIMiddleware)
+
+# CORS middleware - allows all origins for game compatibility but with secure settings
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.origins_list,  # ["*"] for development, specific domains for production
+    allow_credentials=False,  # Don't allow credentials with wildcards for security
+    allow_methods=["GET", "POST", "PUT", "DELETE", "OPTIONS"],
+    allow_headers=["Authorization", "Content-Type", "X-Requested-With"],
+    expose_headers=["X-RateLimit-Limit", "X-RateLimit-Remaining"],
+    max_age=3600,  # Cache preflight requests for 1 hour
+)
+
+# Security headers middleware
+@app.middleware("http")
+async def add_security_headers(request: Request, call_next):
+    """Add security headers to all responses."""
+    response = await call_next(request)
     
-    await respond("hewowo")
+    # Add security headers
+    security_headers = SecurityHeaders.get_security_headers()
+    for header, value in security_headers.items():
+        response.headers[header] = value
+    
+    # Add rate limit headers
+    response.headers["X-Content-Security-Policy"] = "default-src 'self'"
+    
+    return response
 
-app = FastAPI(title="Random Access API", version="0.1.0", lifespan=lifespan)
+# Request size limit middleware
+@app.middleware("http")
+async def limit_request_size(request: Request, call_next):
+    """Limit request body size to prevent large payload attacks."""
+    content_length = request.headers.get("content-length")
+    if content_length:
+        content_length = int(content_length)
+        if content_length > settings.max_request_size:
+            from fastapi import HTTPException, status
+            raise HTTPException(
+                status_code=status.HTTP_413_REQUEST_ENTITY_TOO_LARGE,
+                detail=f"Request too large. Maximum size: {settings.max_request_size} bytes"
+            )
+    
+    response = await call_next(request)
+    return response
 
+# Include routers
+routers = [
+    create_auth_router(SESSIONS, USERS, SUBMISSIONS, slack),
+    create_users_router(SESSIONS, USERS),
+    create_items_router(SESSIONS, USERS, ITEMS, ITEM_ADDONS),
+    create_user_items_router(SESSIONS, USERS, ITEMS, ITEM_ADDONS),
+    create_system_router(slack_handler)
+]
 
-@app.post("/slack/events")
-async def endpoint(req: Request):
-    return await slack_handler.handle(req)
-
-
-# Authentication dependency
-async def get_current_user(x_api_key: Annotated[str, Header()]) -> User:
-    if not x_api_key:
-        raise HTTPException(status_code=401, detail="API key required")
-
-    user = await User.get_or_none(api_key=x_api_key)
-    if not user:
-        raise HTTPException(status_code=401, detail="Invalid API key")
-
-    return user
-
-
-# Public endpoints (no auth required)
-@app.get("/")
-async def root():
-    return {"message": "Random Access API is running"}
-
-@app.get("/auth/start")
-async def auth_start(game_id: str):
-    url = "https://slack.com/openid/connect/authorize/?"
-    params = {"response_type": "code", "scope": "openid profile email", "client_id": os.environ.get("SLACK_CLIENT_ID"), "state": game_id, "redirect_uri": "https://random-access.prox.mra.sh/auth/callback"}
-    return RedirectResponse(url + urlencode(params))
-
-@app.get("/auth/callback")
-async def auth_callback(code: str, state: str):
-    print(code, state)
-    return "yay!"
-
-@app.post("/register", response_model=UserResponse)
-async def register_user(user_data: UserCreate):
-    # Check if username or email already exists
-    existing_user = await User.get_or_none(slack_id=user_data.slack_id)
-    if existing_user:
-        raise HTTPException(status_code=400, detail="Username already exists")
-
-    existing_email = await User.get_or_none(email=user_data.email)
-    if existing_email:
-        raise HTTPException(status_code=400, detail="Email already exists")
-
-    # Generate API key
-    api_key = secrets.token_urlsafe(32)
-
-    # Create user
-    user = await User.create(
-        slack_id=user_data.slack_id,
-        email=user_data.email,
-        display_name=user_data.display_name,
-        api_key=api_key,
-    )
-
-    return UserResponse(
-        id=user.id,
-        slack_id=user.slack_id,
-        email=user.email,
-        display_name=user.display_name,
-        api_key=user.api_key,
-        created_at=user.created_at.isoformat(),
-    )
-
-
-# Protected endpoints (auth required)
-@app.get("/profile", response_model=UserResponse)
-async def get_profile(current_user: User = Depends(get_current_user)): # pyright:ignore[reportCallInDefaultInitializer]
-    return UserResponse(
-        id=current_user.id,
-        slack_id=current_user.slack_id,
-        email=current_user.email,
-        display_name=current_user.display_name,
-        api_key=current_user.api_key,
-        created_at=current_user.created_at.isoformat(),
-    )
-
-
-@app.put("/profile", response_model=UserResponse)
-async def update_profile(
-    user_update: UserUpdate, current_user: User = Depends(get_current_user) # pyright:ignore[reportCallInDefaultInitializer]
-
-):
-    # Update fields if provided
-    if user_update.email is not None:
-        # Check if email is already taken by another user
-        existing_email = await User.get_or_none(email=user_update.email)
-        if existing_email and existing_email.id != current_user.id:
-            raise HTTPException(status_code=400, detail="Email already exists")
-        current_user.email = user_update.email
-
-    if user_update.display_name is not None:
-        current_user.display_name = user_update.display_name
-
-    await current_user.save()
-
-    return UserResponse(
-        id=current_user.id,
-        slack_id=current_user.slack_id,
-        email=current_user.email,
-        display_name=current_user.display_name,
-        api_key=current_user.api_key,
-        created_at=current_user.created_at.isoformat(),
-    )
-
-
-@app.get("/profile/data")
-async def get_profile_data(current_user: User = Depends(get_current_user)) -> dict[str, int | str | bool | float | dict[str, Any]]: # pyright:ignore[reportCallInDefaultInitializer,reportExplicitAny]
-   
-    """Get flexible profile data (for future passport features)"""
-
-    return {"profile_data": current_user.profile_data} # pyright:ignore[reportUnknownMemberType]
-
-
-@app.put("/profile/data")
-async def update_profile_data(
-    data: dict[str, Any], current_user: User = Depends(get_current_user) # pyright:ignore[reportCallInDefaultInitializer,reportExplicitAny]
-
-):
-    """Update flexible profile data (for future passport features)"""
-    current_user.profile_data = data
-    await current_user.save()
-    return {
-        "message": "Profile data updated",
-        "profile_data": current_user.profile_data,
-    }
+for router in routers:
+    app.include_router(router)

src/random_access/routes/__init__.py

@@ -0,0 +1 @@
+"""API routes package."""

src/random_access/routes/auth.py

@@ -0,0 +1,213 @@
+"""API routes for authentication endpoints."""
+
+import hashlib
+from pathlib import Path
+from typing import Literal
+from urllib.parse import urlencode
+
+from fastapi import APIRouter, HTTPException, Query, Request, status
+from fastapi.responses import HTMLResponse, JSONResponse, RedirectResponse
+from pydantic import BaseModel, Field
+from slowapi import Limiter
+
+from random_access.auth import get_session_by_token, hash_token
+from random_access.database import get_game_record, get_user_record, update_user_and_session, create_session
+from random_access.security import generate_secure_token, validate_airtable_id, create_safe_error_response, get_client_ip
+from random_access.settings import settings
+from random_access.slack_integration import get_slack_user_id
+
+# Rate limiter for auth endpoints
+limiter = Limiter(key_func=get_client_ip)
+
+# Pydantic models for OpenAPI documentation
+class AuthStatusResponse(BaseModel):
+    """Response model for authentication status check."""
+    status: Literal["ok", "error"] = Field(..., description="Authentication status")
+
+
+def create_auth_router(sessions_table, users_table, submissions_table, slack_app) -> APIRouter:
+    """Create and configure the authentication router."""
+    router = APIRouter(prefix="/auth", tags=["authentication"])
+
+    @router.get(
+        "/tokens",
+        response_model=str,
+        summary="Generate authentication token",
+        description="Generate a secure token for initiating the OAuth flow with Slack. This endpoint creates a new session and returns a token that can be used to start the authentication process. The token includes: A secure hash derived from the game ID and session, Game session binding for context. Required for: Starting any authentication flow. Security: Token is cryptographically signed and expires with the session. The returned token should be used immediately with the /auth/login endpoint.",
+        responses={
+            200: {
+                "description": "Token generated successfully",
+                "content": {
+                    "application/json": {
+                        "example": "abc123def456.game789"
+                    }
+                }
+            },
+            400: {"description": "Game ID is required"},
+            429: {"description": "Rate limit exceeded"}
+        }
+    )
+    @limiter.limit(f"{settings.rate_limit_requests}/minute")
+    async def auth_token(
+        request: Request,
+        game_id: str = Query(..., description="Unique identifier of the game session requesting authentication")
+    ):
+        """Generates a secure token for the OpenID Connect flow."""
+        try:
+            # Validate game ID format
+            validated_game_id = validate_airtable_id(game_id, "Game ID")
+            
+            # Generate secure token and create session
+            secure_token = generate_secure_token()
+            hashed_token = hash_token(secure_token)
+            
+            session = await create_session({
+                "Game": [validated_game_id],
+                "Token": hashed_token
+            }, sessions_table)
+            
+            # Create game hash for state validation
+            game_hash = hashlib.sha256(
+                f"{validated_game_id}.{settings.game_id_salt}".encode("utf-8")
+            ).hexdigest()
+            
+            # Return secure token format: {secure_token}.{game_hash}.{game_id}
+            return f"{secure_token}.{game_hash}.{validated_game_id}"
+            
+        except HTTPException:
+            raise
+        except Exception as e:
+            error_response = create_safe_error_response(e, "Failed to generate authentication token")
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail=error_response["detail"]
+            )
+
+    @router.get(
+        "/login",
+        response_class=RedirectResponse,
+        summary="Start OAuth flow with Slack",
+        description="Redirect user to Slack's OAuth authorization page to begin authentication. This endpoint: 1) Validates the provided token, 2) Constructs the OAuth URL with proper scopes and callback, 3) Redirects the user to Slack for authorization. User flow: 1) Game calls /auth/tokens to get a token, 2) Game redirects user to this endpoint with the token, 3) User is redirected to Slack for authorization, 4) Slack redirects back to /auth/callback with authorization code. Scopes requested: openid profile email.",
+        responses={
+            302: {"description": "Redirect to Slack OAuth authorization page"},
+            400: {"description": "Token is required"},
+            429: {"description": "Rate limit exceeded"}
+        }
+    )
+    @limiter.limit(f"{settings.rate_limit_requests}/minute")
+    async def auth_start(
+        request: Request,
+        token: str = Query(..., description="Authentication token obtained from /auth/tokens endpoint")
+    ):
+        """Starts the OpenID Connect flow with Slack."""
+        if not token:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Token is required to start authentication",
+            )
+        
+        params = {
+            "response_type": "code", 
+            "scope": "openid profile email", 
+            "client_id": settings.slack_client_id, 
+            "state": token, 
+            "redirect_uri": settings.app_base_url + "/auth/callback"
+        }
+        return RedirectResponse("https://slack.com/openid/connect/authorize/?" + urlencode(params))
+
+    @router.get(
+        "/callback",
+        response_class=HTMLResponse,
+        summary="Handle OAuth callback from Slack",
+        description="Process the OAuth callback from Slack and complete user authentication. This endpoint is called automatically by Slack after user authorization and: 1) Validates the authorization code and state token, 2) Exchanges the code for user information from Slack, 3) Creates or updates user records in the system, 4) Links the user to their game session, 5) Returns a success page with next steps. Automatic: This endpoint is called by Slack, not directly by games or users. Result: HTML page instructing user to return to the game. Error handling: Invalid codes or tokens will return HTTP 400 errors.",
+        responses={
+            200: {
+                "description": "Authentication completed successfully - HTML success page returned",
+                "content": {
+                    "text/html": {
+                        "example": "<html>Authentication successful! Please check the game for next steps.</html>"
+                    }
+                }
+            },
+            400: {"description": "Missing or invalid authorization code or state token"},
+            429: {"description": "Rate limit exceeded"}
+        }
+    )
+    @limiter.limit(f"{settings.rate_limit_requests}/minute")
+    async def auth_callback(
+        request: Request,
+        code: str = Query(..., description="Authorization code provided by Slack"),
+        state: str = Query(..., description="State token that was passed to Slack during authorization")
+    ):
+        """Handles the callback from Slack's OpenID Connect flow."""
+        if not code or not state:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Missing code or state in callback",
+            )
+        
+        from random_access.auth import decode_oidc_state
+        
+        game_id, token, session_rec_id = await decode_oidc_state(state, sessions_table)
+        user_id = await get_slack_user_id(code, slack_app)
+        user_rec = await get_user_record(user_id, users_table)
+        game_rec = await get_game_record(game_id, submissions_table)
+        await update_user_and_session(user_rec, game_rec, session_rec_id, users_table, sessions_table)
+        
+        # Load and return the HTML success page
+        template_path = Path(__file__).parent.parent.parent.parent / "templates" / "auth_success.html"
+        with open(template_path, "r", encoding="utf-8") as f:
+            html_content = f.read()
+        
+        return HTMLResponse(content=html_content, status_code=200)
+
+    @router.get(
+        "/status",
+        response_model=AuthStatusResponse,
+        summary="Check authentication status",
+        description="Verify if a token represents a valid, authenticated session. This endpoint checks: Token validity and format, Session existence in the database, Whether the session is linked to a game. Use case: Games can poll this endpoint to check if a user has completed the authentication flow after being redirected to Slack. Session lookups are cached for 1 minute to improve performance. Returns {\"status\": \"ok\"} for valid authenticated sessions, {\"status\": \"error\"} otherwise.",
+        responses={
+            200: {
+                "description": "Authentication status checked successfully",
+                "content": {
+                    "application/json": {
+                        "examples": {
+                            "authenticated": {
+                                "summary": "User is authenticated",
+                                "value": {"status": "ok"}
+                            },
+                            "not_authenticated": {
+                                "summary": "User is not authenticated",
+                                "value": {"status": "error"}
+                            }
+                        }
+                    }
+                }
+            },
+            400: {"description": "Token is required"},
+            429: {"description": "Rate limit exceeded"}
+        }
+    )
+    @limiter.limit(f"{settings.rate_limit_requests}/minute")
+    async def auth_check(
+        request: Request,
+        token: str = Query(..., description="Authentication token to validate")
+    ):
+        """Checks if the provided token is valid and if the session has a game associated with it."""
+        if not token:
+            return JSONResponse({"status": "error"}, status_code=status.HTTP_400_BAD_REQUEST)
+        
+        try:
+            session = await get_session_by_token(token, sessions_table)
+            # Check if session exists, has a game, and has a user (complete auth)
+            if (session and 
+                session["fields"].get("Game") and 
+                session["fields"].get("User")):
+                return JSONResponse({"status": "ok"})
+        except Exception:
+            # Safe error handling - don't leak internal errors
+            pass
+            
+        return JSONResponse({"status": "error"}, status_code=status.HTTP_400_BAD_REQUEST)
+
+    return router

src/random_access/routes/items.py

@@ -0,0 +1,290 @@
+"""API routes for item endpoints."""
+
+import datetime
+from typing import Annotated, Dict, List, Optional
+
+from fastapi import APIRouter, Header, HTTPException, Request, status
+from pydantic import BaseModel, Field, field_validator
+from slowapi import Limiter
+
+from random_access.auth import extract_and_validate_auth
+from random_access.database import get_all_items, get_item_by_id, create_item_instance, get_user_items as get_user_items_cached, invalidate_user_items_cache
+from random_access.security import validate_airtable_id, get_client_ip, create_safe_error_response
+from random_access.settings import settings
+
+# Rate limiter for item endpoints
+limiter = Limiter(key_func=get_client_ip)
+
+# Pydantic models for OpenAPI documentation
+class ItemResponse(BaseModel):
+    """Response model for item data."""
+    id: str = Field(..., description="Unique identifier for the item")
+    name: str = Field(..., description="Display name of the item")
+    type: str = Field(..., description="Category or type of the item")
+    level: int = Field(..., description="Required level to use this item")
+    rarity: str = Field(..., description="Rarity classification (common, rare, epic, legendary, etc.)")
+    game_name: str = Field(..., description="Name of the game this item belongs to")
+
+
+class UserItemResponse(BaseModel):
+    """Response model for user's item (simplified flat structure)."""
+    item_id: str = Field(..., description="Unique identifier for the item")
+    name: Optional[str] = Field(None, description="Display name of the item")
+    type: Optional[str] = Field(None, description="Category or type of the item")
+    level: Optional[int] = Field(None, description="Required level to use this item")
+    rarity: Optional[str] = Field(None, description="Rarity classification (common, rare, epic, legendary, etc.)")
+    game_name: Optional[str] = Field(None, description="Name of the game this item belongs to")
+    description: Optional[str] = Field(None, description="Description of the item")
+
+
+class UserItemsResponse(BaseModel):
+    """Response model for user's complete item collection."""
+    user_id: str = Field(..., description="Unique identifier of the user")
+    user_name: Optional[str] = Field(None, description="Display name of the user")
+    total_items: int = Field(..., description="Total number of items owned by the user")
+    items: List[UserItemResponse] = Field(..., description="List of all items owned by the user")
+
+
+class CreateItemRequest(BaseModel):
+    """Request model for creating an item instance."""
+    item_id: str = Field(..., description="The ID of the item to create an instance of")
+    
+    @field_validator('item_id')
+    @classmethod
+    def validate_item_id(cls, v):
+        """Validate item ID format."""
+        return validate_airtable_id(v, "Item ID")
+
+
+class CreateItemResponse(BaseModel):
+    """Response model for item creation."""
+    item_id: str = Field(..., description="ID of the item that was instantiated")
+    user_id: str = Field(..., description="ID of the user who now owns this item instance")
+    game_id: str = Field(..., description="ID of the game session where this item was created")
+    message: str = Field(..., description="Confirmation message about the operation status")
+
+
+def create_items_router(sessions_table, users_table, items_table, item_addons_table) -> APIRouter:
+    """Create and configure the items router."""
+    router = APIRouter(prefix="/items", tags=["items"])
+
+    @router.get(
+        "",
+        response_model=List[Dict[str, ItemResponse]],
+        summary="Get all available items",
+        description="Retrieve a complete list of all items available in the system. This endpoint returns all items from all games with their basic information including item name, type, level, rarity, and which game the item belongs to. No authentication required - this is public catalog data. Results are cached in Redis for 3 minutes to improve performance.",
+        responses={
+            200: {
+                "description": "Successfully retrieved all items",
+                "content": {
+                    "application/json": {
+                        "example": [
+                            {
+                                "rec123": {
+                                    "id": "rec123",
+                                    "name": "Steel Sword",
+                                    "type": "weapon",
+                                    "level": 5,
+                                    "rarity": "common",
+                                    "game_name": "Adventure Quest"
+                                }
+                            }
+                        ]
+                    }
+                }
+            },
+            429: {"description": "Rate limit exceeded"}
+        }
+    )
+    @limiter.limit(f"{settings.rate_limit_requests}/minute")
+    async def read_items(request: Request):
+        """Fetches all items from Airtable and returns them in a parsed format."""
+        try:
+            all_items = await get_all_items(items_table)
+            parsed_items = []
+            for idx, item in enumerate(all_items):
+                parsed_item = {}
+                # Add the ID field
+                parsed_item["id"] = item["id"]
+                
+                for at_field, field in {
+                    "Name": "name",
+                    "Type": "type",
+                    "Level": "level",
+                    "Rarity": "rarity",
+                    "Game Name (from Games)": "game_name",
+                }.items():
+                    val = item["fields"][at_field]
+                    if field == "game_name":
+                        val = val[
+                            0
+                        ]  # the game an item is from is represented as a list in airtable because it's a lookup,
+                        # but since an item can only belong to one game, it should be a string instead
+                    elif field == "rarity":
+                        # Convert rarity from integer to string if needed
+                        val = str(val)
+                    parsed_item[field] = val
+                parsed_items.append({item["id"]: parsed_item})
+            return parsed_items
+        except Exception as e:
+            error_response = create_safe_error_response(e, "Failed to retrieve items")
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail=error_response["detail"]
+            )
+
+    @router.post(
+        "",
+        response_model=CreateItemResponse,
+        summary="Create a new item instance for authenticated user",
+        description="Create a new instance of an existing item for the authenticated user. This endpoint allows authenticated users to add items to their inventory by: 1) Verifying the user's authentication token, 2) Checking that the specified item exists in the catalog, 3) Creating a new instance of that item owned by the user. Authentication required: Must provide valid Bearer token in Authorization header. Rate limiting: Write operations are queued and processed at max 5 per second. The item will be associated with the user's current game session.",
+        responses={
+            200: {
+                "description": "Item instance creation queued successfully",
+                "content": {
+                    "application/json": {
+                        "example": {
+                            "item_id": "rec123",
+                            "user_id": "usr456",
+                            "game_id": "game789",
+                            "message": "Item instance creation queued successfully"
+                        }
+                    }
+                }
+            },
+            401: {"description": "Invalid or missing authentication token"},
+            404: {"description": "Specified item does not exist"},
+            400: {"description": "Invalid request format"},
+            429: {"description": "Rate limit exceeded"}
+        }
+    )
+    @limiter.limit("10/minute")  # More restrictive for write operations
+    async def create_item(
+        request: Request,
+        item_request: CreateItemRequest,
+        authorization: Annotated[Optional[str], Header(description="Bearer token for authentication (format: 'Bearer <token>')")] = None
+    ):
+        """Create a new item instance for the authenticated user."""
+        try:
+            if not authorization:
+                raise HTTPException(
+                    status_code=status.HTTP_401_UNAUTHORIZED,
+                    detail="Authorization header required"
+                )
+            
+            game_id, session, user = await extract_and_validate_auth(authorization, sessions_table, users_table)
+            
+            # Verify the item exists
+            item = await get_item_by_id(item_request.item_id, items_table)
+            if not item:
+                raise HTTPException(
+                    status_code=status.HTTP_404_NOT_FOUND,
+                    detail="Item not found"
+                )
+            
+            # Create a new item instance (queued write)
+            await create_item_instance({
+                "User": [user["id"]],
+                "Item": [item_request.item_id],
+                "Game": [game_id],
+                "Created": datetime.datetime.now().isoformat()
+            }, item_addons_table)
+            
+            # Invalidate the user's cached items so they see the new item immediately
+            await invalidate_user_items_cache(user["id"])
+            
+            return {
+                "item_id": item_request.item_id,
+                "user_id": user["id"],
+                "game_id": game_id,
+                "message": "Item instance creation queued successfully"
+            }
+        except HTTPException:
+            raise
+        except Exception as e:
+            error_response = create_safe_error_response(e, "Failed to create item instance")
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail=error_response["detail"]
+            )
+
+    return router
+
+
+def create_user_items_router(sessions_table, users_table, items_table, item_addons_table) -> APIRouter:
+    """Create router for user-specific item endpoints."""
+    router = APIRouter(prefix="/users/me", tags=["user-items"])
+
+    @router.get(
+        "/items",
+        response_model=UserItemsResponse,
+        summary="Get all items owned by authenticated user",
+        description="Retrieve the complete inventory of items owned by the authenticated user. This endpoint returns: User information (ID and display name), Total count of items owned, Detailed list of each item with complete item details (ID, name, type, level, rarity, source game, description). Authentication required: Must provide valid Bearer token in Authorization header. User items are cached in Redis for 5 minutes to improve performance. Results include items from all games the user has played.",
+        responses={
+            200: {
+                "description": "Successfully retrieved user's item inventory",
+                "content": {
+                    "application/json": {
+                        "example": {
+                            "user_id": "usr456",
+                            "user_name": "PlayerOne",
+                            "total_items": 3,
+                            "items": [
+                                {
+                                    "item_id": "rec123",
+                                    "name": "Steel Sword",
+                                    "type": "weapon",
+                                    "level": 5,
+                                    "rarity": "common",
+                                    "game_name": "Adventure Quest",
+                                    "description": "A sturdy steel sword for adventurers"
+                                }
+                            ]
+                        }
+                    }
+                }
+            },
+            401: {"description": "Invalid or missing authentication token"},
+            404: {"description": "User not found"}
+        }
+    )
+    @limiter.limit(f"{settings.rate_limit_requests}/minute")
+    async def get_user_items(
+        request: Request,
+        authorization: Annotated[Optional[str], Header(description="Bearer token for authentication (format: 'Bearer <token>')")] = None
+    ):
+        """Get all items owned by the authenticated user."""
+        if not authorization:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Authorization header required"
+            )
+        
+        game_id, session, user = await extract_and_validate_auth(authorization, sessions_table, users_table)
+        
+        # Get all item instances for this user (cached)
+        user_item_ids = await get_user_items_cached(user["id"], users_table)
+        
+        # Format the response with item details
+        user_items = []
+        for item_id in user_item_ids:
+            item = await get_item_by_id(item_id, items_table)
+            if item:
+                user_items.append({
+                    "item_id": item["id"],
+                    "name": item["fields"].get("Name"),
+                    "type": item["fields"].get("Type"),
+                    "level": item["fields"].get("Level"),
+                    "rarity": str(item["fields"].get("Rarity")) if item["fields"].get("Rarity") is not None else None,
+                    "game_name": item["fields"].get("Game Name (from Games)", [None])[0] if item["fields"].get("Game Name (from Games)") else None,
+                    "description": item["fields"].get("Description")
+                })
+        
+        return {
+            "user_id": user["id"],
+            "user_name": user["fields"].get("Display Name"),
+            "total_items": len(user_items),
+            "items": user_items
+        }
+
+    return router

src/random_access/routes/system.py

@@ -0,0 +1,67 @@
+"""API routes for system and utility endpoints."""
+
+from fastapi import APIRouter, Request
+from pydantic import BaseModel, Field
+from slack_bolt.adapter.fastapi.async_handler import AsyncSlackRequestHandler
+from slowapi import Limiter
+
+from random_access.security import get_client_ip
+from random_access.settings import settings
+
+# Rate limiter for system endpoints
+limiter = Limiter(key_func=get_client_ip)
+
+
+class SystemHealthResponse(BaseModel):
+    """Response model for system health check."""
+    message: str = Field(..., description="Status message indicating system health")
+    status: str = Field(default="healthy", description="Overall system status")
+
+
+def create_system_router(slack_handler: AsyncSlackRequestHandler) -> APIRouter:
+    """Create and configure the system router."""
+    router = APIRouter(tags=["system"])
+
+    @router.post(
+        "/slack/events",
+        summary="Handle Slack events webhook",
+        description="Webhook endpoint for processing Slack Events API callbacks. This endpoint receives and processes events from the Slack Events API including: Bot mentions and direct messages, Slash commands and interactive components, App home tab openings and user interactions. Slack requests are automatically verified using signing secrets. This endpoint enables the Random Access bot to: Respond to user commands in Slack, Display game-related information and inventory, Facilitate item trading and game interactions. Note: This endpoint is intended for Slack's Events API only.",
+        responses={
+            200: {"description": "Event processed successfully"},
+            400: {"description": "Invalid request format or signature"},
+            401: {"description": "Invalid or missing Slack signature"}
+        }
+    )
+    async def slack_events_endpoint(req: Request):
+        """Handle Slack events."""
+        return await slack_handler.handle(req)
+
+    @router.get(
+        "/",
+        response_model=SystemHealthResponse,
+        summary="System health check and API status",
+        description="Basic health check endpoint for monitoring system availability. This endpoint provides: Confirmation that the API is running and responsive, System status information for monitoring tools, Quick connectivity test for client applications. No authentication required - this is a public health check endpoint. Usage: Load balancer health checks, Service monitoring and alerting, Client application connectivity testing, Development environment verification.",
+        responses={
+            200: {
+                "description": "System is healthy and running",
+                "content": {
+                    "application/json": {
+                        "example": {
+                            "message": "Random Access API is running",
+                            "status": "healthy"
+                        }
+                    }
+                }
+            },
+            429: {"description": "Rate limit exceeded"}
+        }
+    )
+    @limiter.limit(f"{settings.rate_limit_requests}/minute")
+    async def root(request: Request):
+        """Root endpoint for health checks."""
+        return {
+            "message": "Random Access API is running",
+            "status": "healthy"
+        }
+
+    return router

src/random_access/routes/users.py

@@ -0,0 +1,84 @@
+"""API routes for user endpoints."""
+
+from typing import Annotated, Optional
+
+from fastapi import APIRouter, Header, HTTPException, Request, status
+from pydantic import BaseModel, Field
+from slowapi import Limiter
+
+from random_access.auth import extract_and_validate_auth
+from random_access.database import get_user_record
+from random_access.security import get_client_ip
+from random_access.settings import settings
+
+# Rate limiter for user endpoints
+limiter = Limiter(key_func=get_client_ip)
+
+
+class UserResponse(BaseModel):
+    """Response model for user data."""
+    id: str = Field(..., description="Unique identifier for the user")
+    display_name: Optional[str] = Field(None, description="User's display name")
+    slack_id: Optional[str] = Field(None, description="User's Slack ID")
+    email: Optional[str] = Field(None, description="User's email address")
+    created: Optional[str] = Field(None, description="ISO timestamp when the user account was created")
+
+
+def create_users_router(sessions_table, users_table) -> APIRouter:
+    """Create and configure the users router."""
+    router = APIRouter(prefix="/users", tags=["users"])
+
+    @router.get(
+        "/me",
+        response_model=UserResponse,
+        summary="Get authenticated user's profile information",
+        description="Retrieve the complete profile information for the currently authenticated user. This endpoint returns: User's unique ID and display name, Associated Slack ID for integration features, Email address and account creation date, Any other profile information stored in the system. Authentication required: Must provide valid Bearer token in Authorization header. User data is cached in Redis for 5 minutes to improve performance. This is useful for: Displaying user profile information in game interfaces, Verifying user identity and permissions, Integrating with Slack workspace features.",
+        responses={
+            200: {
+                "description": "Successfully retrieved user profile",
+                "content": {
+                    "application/json": {
+                        "example": {
+                            "id": "usr456",
+                            "display_name": "PlayerOne",
+                            "slack_id": "U1234567890",
+                            "email": "player@example.com",
+                            "created": "2025-01-01T12:00:00Z"
+                        }
+                    }
+                }
+            },
+            401: {"description": "Invalid or missing authentication token"},
+            404: {"description": "User not found"},
+            429: {"description": "Rate limit exceeded"}
+        }
+    )
+    @limiter.limit(f"{settings.rate_limit_requests}/minute")
+    async def user_info(
+        request: Request,
+        authorization: Annotated[Optional[str], Header(description="Bearer token for authentication (format: 'Bearer <token>')")] = None
+    ):
+        """Fetches user information for the current authenticated user."""
+        if not authorization:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Authorization header required"
+            )
+        
+        game_id, session, user = await extract_and_validate_auth(authorization, sessions_table, users_table)
+        
+        if not user:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="User not found"
+            )
+        
+        return {
+            "id": user["id"],
+            "display_name": user["fields"].get("Display Name"),
+            "slack_id": user["fields"].get("Slack ID"),
+            "email": user["fields"].get("Email"),
+            "created": user["fields"].get("Created")
+        }
+
+    return router

src/random_access/security.py

@@ -0,0 +1,150 @@
+"""Security utilities and validation functions."""
+
+import re
+import secrets
+from typing import Any, Dict, Optional
+
+from fastapi import HTTPException, Request, status
+
+from random_access.settings import settings
+
+# Validation patterns
+AIRTABLE_ID_PATTERN = re.compile(r'^rec[A-Za-z0-9]{14}$')
+UUID_PATTERN = re.compile(r'^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$')
+SLACK_USER_ID_PATTERN = re.compile(r'^U[A-Z0-9]{10}$')
+
+def generate_secure_token() -> str:
+    """Generate a cryptographically secure token."""
+    return secrets.token_urlsafe(32)
+
+def validate_airtable_id(record_id: str, field_name: str = "ID") -> str:
+    """Validate Airtable record ID format."""
+    if not record_id or not isinstance(record_id, str):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Invalid {field_name}: must be a valid Airtable record ID"
+        )
+    
+    if not AIRTABLE_ID_PATTERN.match(record_id):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Invalid {field_name}: must be a valid Airtable record ID"
+        )
+    
+    return record_id
+
+def validate_uuid(uuid_str: str, field_name: str = "UUID") -> str:
+    """Validate UUID format."""
+    if not uuid_str or not isinstance(uuid_str, str):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Invalid {field_name}: must be a valid UUID"
+        )
+    
+    if not UUID_PATTERN.match(uuid_str):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Invalid {field_name}: must be a valid UUID"
+        )
+    
+    return uuid_str
+
+def validate_slack_user_id(user_id: str) -> str:
+    """Validate Slack user ID format."""
+    if not user_id or not isinstance(user_id, str):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Invalid Slack user ID"
+        )
+    
+    if not SLACK_USER_ID_PATTERN.match(user_id):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Invalid Slack user ID format"
+        )
+    
+    return user_id
+
+def sanitize_airtable_formula_input(value: str) -> str:
+    """Sanitize input that might be used in Airtable formulas."""
+    if not isinstance(value, str):
+        return str(value)
+    
+    # Remove potentially dangerous characters that could be used in formula injection
+    dangerous_chars = ['\'', '"', '\\', '{', '}', '(', ')', '&', '|', '=', '+']
+    sanitized = value
+    for char in dangerous_chars:
+        sanitized = sanitized.replace(char, '')
+    
+    return sanitized
+
+def get_client_ip(request: Request) -> str:
+    """Get client IP address, considering proxy headers."""
+    # Check for forwarded IP (common in production behind load balancers)
+    forwarded_for = request.headers.get("X-Forwarded-For")
+    if forwarded_for:
+        # Take the first IP in the chain
+        return forwarded_for.split(",")[0].strip()
+    
+    real_ip = request.headers.get("X-Real-IP")
+    if real_ip:
+        return real_ip
+    
+    # Fallback to direct connection IP
+    return request.client.host if request.client else "unknown"
+
+def create_safe_error_response(error: Exception, user_message: str = "An error occurred") -> Dict[str, Any]:
+    """Create safe error response that doesn't leak sensitive information."""
+    if settings.is_production:
+        return {"detail": user_message}
+    else:
+        # In development, include detailed error information
+        return {
+            "detail": user_message,
+            "debug_info": str(error),
+            "error_type": type(error).__name__
+        }
+
+def validate_bearer_token_format(authorization: Optional[str]) -> str:
+    """Validate Bearer token format and extract token."""
+    if not authorization:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Authorization header required"
+        )
+    
+    if not authorization.startswith("Bearer "):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid authorization header format. Must be 'Bearer <token>'"
+        )
+    
+    token = authorization[7:]  # Remove "Bearer " prefix
+    if len(token) < 10:  # Basic length check
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid token format"
+        )
+    
+    return token
+
+class SecurityHeaders:
+    """Security headers middleware-like functionality."""
+    
+    @staticmethod
+    def get_security_headers() -> Dict[str, str]:
+        """Get recommended security headers."""
+        headers = {
+            "X-Content-Type-Options": "nosniff",
+            "X-Frame-Options": "DENY",
+            "X-XSS-Protection": "1; mode=block",
+            "Referrer-Policy": "strict-origin-when-cross-origin",
+        }
+        
+        if settings.is_production:
+            headers.update({
+                "Strict-Transport-Security": "max-age=31536000; includeSubDomains",
+                "Content-Security-Policy": "default-src 'self'",
+            })
+        
+        return headers

src/random_access/settings.py

@@ -0,0 +1,33 @@
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file='.env', env_file_encoding='utf-8', extra='ignore')
+    airtable_pat: str
+    airtable_base: str
+    slack_signing_secret: str
+    slack_client_id: str
+    slack_client_secret: str
+    app_base_url: str
+    game_id_salt: str
+    
+    # Security settings
+    environment: str = "development"  # development, staging, production
+    max_request_size: int = 1048576  # 1MB default
+    rate_limit_requests: int = 20  # requests per minute per IP
+    allowed_origins: str = "*"  # Comma-separated list or "*" for development
+    
+    # Session security
+    session_ttl_hours: int = 24  # Session expires after 24 hours
+    
+    @property
+    def is_production(self) -> bool:
+        return self.environment == "production"
+    
+    @property
+    def origins_list(self) -> list[str]:
+        if self.allowed_origins == "*":
+            return ["*"]
+        return [origin.strip() for origin in self.allowed_origins.split(",")]
+
+settings = Settings() # type: ignore

src/random_access/slack_integration.py

@@ -0,0 +1,56 @@
+"""Slack integration handlers and utilities."""
+
+import logging
+from logging import Logger
+
+from slack_bolt.async_app import AsyncAck, AsyncApp, AsyncRespond, AsyncSay
+from slack_bolt.response import BoltResponse
+
+from random_access.settings import settings
+
+
+def create_slack_app() -> AsyncApp:
+    """Create and configure the Slack app."""
+    return AsyncApp(signing_secret=settings.slack_signing_secret)
+
+
+async def get_slack_user_id(code: str, slack_app: AsyncApp) -> str:
+    """Get Slack user ID from OAuth code."""
+    redirect_uri = f"{settings.app_base_url}/auth/callback"
+
+    token_resp = await slack_app.client.openid_connect_token(
+        client_id=settings.slack_client_id,
+        client_secret=settings.slack_client_secret,
+        code=code,
+        redirect_uri=redirect_uri,
+    )
+
+    user_info = await slack_app.client.openid_connect_userInfo(
+        token=token_resp.get("access_token")
+    )
+
+    slack_user_id = user_info.get("https://slack.com/user_id")
+    if not slack_user_id:
+        raise ValueError("Could not get Slack user ID")
+
+    return str(slack_user_id)
+
+
+def setup_slack_handlers(slack_app: AsyncApp):
+    """Set up Slack event handlers."""
+    
+    @slack_app.event("app_mention")  # pyright:ignore[reportUnknownMemberType]
+    async def handle_app_mentions(body: BoltResponse, say: AsyncSay, logger: Logger):
+        logger.info(body)
+        _ = await say("What's up?")
+
+    @slack_app.event("message")  # pyright:ignore[reportUnknownMemberType]
+    async def handle_message():
+        pass
+
+    @slack_app.command("/random-access")  # pyright:ignore[reportUnknownMemberType]
+    async def handle_command(ack: AsyncAck, body: BoltResponse, respond: AsyncRespond):
+        await ack()
+        subcommand = dict(body).get("text", "").strip()  # type: ignore
+        # Note: Removed debug print for security - use proper logging in production
+        await respond("hewowo")