Files
KittyRec2018-Leak/static/SERVER_FLOW.md
2026-07-24 15:33:38 +00:00

26 KiB
Raw Permalink Blame History

KittyRec Server — Complete Flow Reference


High-Level Architecture

Internet
   │
   ▼
Nginx / Reverse Proxy (port 443 → 8080)
   │
   ▼
Flask (Gunicorn / app.py) — port 8080
   ├── HTTP Routes (22 blueprints)
   ├── WebSocket  /api/notification/v2  (flask-sock)
   ├── Admin Panel  /admin  (Flask-Admin 2.x)
   └── SQLite Database (single file, WAL mode)

Background Threads (daemons.py)
   ├── ban-enforcer       (every 5s)
   ├── presence-watchdog  (every 20s)
   ├── count-recorder     (every 5min)
   ├── kittyrec-system    (persistent, PID 23 keepalive)
   └── register_graceful_shutdown (SIGTERM handler)

Discord Bot (separate process — /home/kittyrecbots/KittyNet-DiscordBot/)
   └── Calls Public API + Internal API (/api/internal/discord/*)

Startup Sequence (app.py)

1. ProxyFix applied (x_for=1) → request.remote_addr is correct client IP
2. All 22 blueprints registered
3. Flask-Admin mounted at /admin with Bootstrap4Theme
4. SQLite DB initialized → _create_tables() runs all CREATE TABLE IF NOT EXISTS
5. Daemons started:
     start_ban_enforcer()
     start_player_count_recorder()
     start_presence_watchdog()
     register_graceful_shutdown()
6. bring_system_account_online() → PID 23 fake WS keepalive thread
7. Flask-Sock WebSocket handler registered
8. Server starts listening on 0.0.0.0:8080

Every HTTP Request — Lifecycle

Request arrives
   │
   ├── @limiter (flask-limiter, keyed by real IP via ProxyFix)
   │     Default limits set in core/limiter.py
   │     Route-level overrides via @limiter.limit("N per minute")
   │
   ├── @check_auth (core/auth.py)
   │     Reads JWT from Authorization header
   │     Decodes → profile_id stored in flask.g
   │     Returns 401 if missing/invalid
   │
   ├── Route handler runs
   │
   └── Response sent

Auth token flow:

Login → _issue_token(pid)
         JWT signed with server secret
         Payload: { sub: pid, exp: +30days }
         Returned as "AuthToken" in login response

All subsequent requests:
  Authorization: <token>
  get_current_profile_id() → decodes JWT → returns pid

Authentication System (routes/auth.py)

Login Flow

POST /api/platformlogin/v1/loginaccount
  │
  ├── IP ban check → 403 if banned
  ├── Maintenance mode check → 403 if active (unless exempt)
  ├── Username + password verified (bcrypt)
  ├── Daily login reward awarded (_award_daily_login)
  ├── Cascade ban check (linked IP/platform accounts)
  ├── JWT issued (_issue_token)
  └── Returns full profile + token + avatar + settings

Other Auth Endpoints

Endpoint Purpose
POST /loginaccount Username + password login
POST /logincached Token + Platform + PlatformId (trusted re-auth)
POST /createaccount New account creation
POST /registeraccount Post-OOBE username/password registration
GET/POST /refreshlogin Extend token TTL
POST /logout Invalidate cached login
GET/POST /getcachedlogins List saved logins
POST /removecachedlogin Delete a saved login

WebSocket System (routes/ws.py)

Connection Lifecycle

Client opens WS to /api/notification/v2
   │
   ├── JWT auth check → close if invalid
   ├── IP logged to ip_logins table
   ├── Ban check → send Id:20 (kick) + close if banned
   ├── Maintenance check → close if active
   ├── IP ban check → cascade ban if at banned IP
   │
   ├── Receive handshake JSON from client
   ├── Send { SessionId: N } back
   │
   ├── ws_registry.register(pid, ws)
   ├── record_heartbeat(pid)              ← presence watchdog
   ├── Restore screen mode from DB settings
   │
   ├── First-login Discord webhook (if first ever login)
   ├── Place player in dorm room session (if no session)
   ├── push_presence(pid, session)        ← broadcasts to all online
   │
   ├── Send Id:12 for every already-online player
   ├── Send Id:12 for PID 23 (system account)
   │
   ├── Send temp password DM (if no real password set, after 10s delay)
   │
   └── Enter receive loop ──────────────────────────────────────┐
                                                                │
       heartbeat2                                               │
         record_heartbeat(pid)                                  │
         Read SpecialGamemode from param → update session       │
         Send Id:4 (heartbeat response with current session)    │
                                                                │
       playerSubscriptions/v1/update                           │
         For each subscribed PID → send Id:12 (presence)        │
                                                                │
       (anything else → logged as unhandled)                    │
                                                                │
       ws.receive() returns None (disconnect)  ─────────────────┘
         ws_registry.unregister(pid, ws)
         session_mgr.leave_session(pid)
         push_presence(pid, None, online=False)
         session_gift_reset(pid)

WebSocket Message IDs

Id Direction Meaning
2 Server→Client Chat/DM message push
4 Server→Client Heartbeat response (your own presence)
12 Server→Client Another player's presence update
20 Server→Client Kick / ban notification
22 Server→Client Moderation action (kick from room)
90 Server→Client Chat message push (in-room)

Session & Room System

In-Memory State (core/state.py)

SessionManager — tracks all active game sessions

GameSession:
  session_id          int (auto-increment)
  activity_level_id   GUID string (maps to a known activity or room)
  name                display name (e.g. "Dodgeball")
  activity_key        short key (e.g. "room", "dodgeball")
  private             bool — hides from public session list
  sandbox             bool
  creator_player_id   int
  max_capacity        int (1–40, default 20)
  players             set[int] — PIDs currently in session
  photon_room_id      string (e.g. "room_42")
  rec_room_id         int | None — links to rooms DB table
  special_gamemode    int

ConnectionRegistry — tracks live WebSocket connections

_conns:       dict[pid → ws object]
_screen_mode: dict[pid → bool]  (True = screen mode, False = VR)

Join Flow

POST /api/gamesessions/v2/joinroom  (or joinrandom, join, etc.)
  │
  ├── Auth check
  ├── Determine target activity_level_id
  ├── session_mgr.join_room(pid, activity_level_id, ...)
  │     If private/sandbox/dorm → always new session
  │     Otherwise → find existing public session with space
  │                 create new if none found
  ├── ws push: push_presence(pid, session) to all online
  └── Return GameSession dict to client (Photon room ID etc.)

Dorm Room

  • GUID: 76d98498-60a1-430c-ab76-b54a29b7a163
  • Always private server-side (hidden from public list)
  • to_dict() returns Private: False so invite button works
  • All players placed here on WS connect if not already in a session

Post-Game Gift Flow

reportjoinresult / reportgamejoinresult
  │
  ├── XP awarded for activity
  ├── Level-up check → send level-up gift if leveled
  ├── _generate_gift_for_player(pid, activity_guid, xp)
  │     Picks item by rarity weighted random
  │     Filters: no SDK items (sdk_*), no starter items, no already-owned items
  │     Stores in gifts table (pending, not consumed)
  └── push_gift(pid, gift) via WebSocket

Avatar & Gift System (routes/avatar.py)

Avatar Data Sources

/api/avatar/v2  ← current equipped avatar
  └── Reads avatars table (skin_color, hair_color, outfit parts etc.)

/api/avatar/v3/items  ← full item catalog
  └── Reads data/avatar_items.json + data/custom_items.json
      Merges with unlocked_items table
      Returns owned + unowned items

/api/avatar/v*/saved  ← saved outfits
  └── saved_outfits table (up to 3 slots)

Gift System

gifts table columns:
  profile_id, item_desc (AvatarItemDesc), context (0=Admin,1=Activity,2=Store,3=LevelUp)
  consumed (0=pending, 1=consumed), rarity (0/10/20/30/50)
  equipment_modification_guid (for equipment skins)

GET /api/avatar/v2/gifts  → pending unclaimed gifts
POST /api/avatar/v2/gifts/consume/<id>  → mark consumed, unlock item

Rarity Weights

0  = Common     (base weight: high)
10 = Uncommon
20 = Rare
30 = Epic
50 = Legendary

Store & Economy System (routes/storefronts.py)

Currencies

Type Name
1 LaserTagTickets
2 RecCenterTokens
100 LostSkullsGold

Store Rotation

_ROTATION_WINDOW_SECS = 86400  (24 hours)

GET /api/storefronts/v*/N
  │
  ├── Compute rotation slot = floor(time.time() / 86400)
  ├── Seed random with slot number → deterministic shuffle
  ├── Pick N items from pool for this slot
  └── Return store items with prices in all 3 currencies

POST /admin/api/reroll_store  → force rotation to next slot

Purchase Flow

POST /api/storefronts/v2/buy
  │
  ├── Auth check
  ├── Validate item exists in current rotation
  ├── Check balance (currency type)
  ├── Deduct balance
  ├── Add to unlocked_items
  └── Return updated balance

Checklist / Weekly Challenges

GET /api/checklist/v1/current  → active weekly challenge objectives
POST /api/checklist/v1/complete  → complete an objective, award tokens

GET /api/challenge/v1/getCurrent  → current challenge state
POST /api/challenge/v2/updateProgress  → update progress on challenge

Chat & Social System

Direct Messages (routes/relationships.py)

messages table: from_player_id, to_player_id, type, content, read
Types: 4=FriendRequest, 30=SystemDM, others=game notifications

GET /api/messages/v2/get  → inbox
POST /api/messages/v2/send  → send DM + push via WS (Id:2)
POST /api/offlineinvite/v1/send  → offline room invite

Chat Threads (routes/chat.py)

chat_threads: id, created_at
chat_thread_players: thread_id, profile_id
chat_messages: thread_id, from_player_id, content, sent_at

GET  /api/chat/v2/myChats     → my active threads (with messages only)
GET  /api/chat/v2/getById     → thread by ID
GET  /api/chat/v2/getByPlayers → find existing thread (404 if none)
POST /api/chat/v1/create      → create thread + optional first message
POST /api/chat/v*/sendMessage → send to thread + push WS Id:90
POST /api/chat/v1/addToChat   → add player to thread
POST /api/chat/v1/leaveChat   → leave thread

Relationships (routes/relationships.py)

relationships table: profile_id, target_id, relationship_type
Types: 1=Following, 2=Friend, 3=FriendWithSystem, 4=Ignored

Friend request flow:
  sendfriendrequest → creates pending request message
  acceptfriendrequest → upgrades to friend relationship
  removefriend → deletes relationship both ways

Player Social

GET  /api/players/v1/<id>          → profile by ID
GET  /api/players/v1/getByUsername → profile by username
POST /api/players/v2/displayname   → change display name (profanity checked)
POST /api/players/v1/bio           → update bio
POST /api/players/v2/objective     → XP + objective completion
POST /api/players/v2/updateReputation → +/- reputation

Progression System (routes/players.py + routes/sessions.py)

XP & Leveling

Level thresholds in core/database.py (_LEVEL_THRESHOLDS)

XP is awarded at:
  - Activity completion (reportjoinresult)
  - Objective completion (complete_objective_v2)
  - Daily login reward
  - Admin gift

On level-up:
  → Gift generated (context=LevelUp)
  → push_gift via WS

Daily Login Reward

_award_daily_login(pid)  called on every loginaccount
  daily_login_rewards table tracks last claim date
  If new day → award tokens + XP

Objectives

GET  /api/objectives/v1/myprogress   → current objective state
POST /api/objectives/v1/updateobjective → update progress
POST /api/objectives/v1/completegroup   → complete group + award

Ban System (core/ban_service.py + core/daemons.py)

Ban Flow

db.ban_player(pid, reason, duration_hours, admin_name)
  → writes to ban_log table
  → sets profiles.banned = 1

cascade_kick_linked(pid)
  → finds all platform accounts sharing same platform_id
  → bans + kicks all linked accounts

kick_player(pid)
  → ws_registry.send(pid, {Id:20})  ← ban notification
  → ws_registry.close_and_unregister(pid)
  → session_mgr.leave_session(pid)
  → push_presence offline

Ban Enforcer Daemon

Every 5 seconds:
  For each connected PID:
    if db.is_banned(pid):
      Send Id:20, close socket, leave session, push offline

IP Bans

ip_logins table: profile_id, ip_address, last_seen
is_ip_banned(ip) → checks banned_ips table

On login/WS connect:
  If IP is banned → cascade ban the account + kick

Presence Watchdog Daemon (core/daemons.py)

Every 20 seconds:
  For each connected PID:
    If last heartbeat > 90 seconds ago:
      close_and_unregister(pid)
      leave_session(pid)
      push_presence offline
      session_gift_reset(pid)
      remove from _last_seen

record_heartbeat(pid) called:
  → On WS connect
  → On every heartbeat2 message received

Admin Panel (core/admin_panel.py, /admin)

Auth

Cookie "Authorization" → validated against auth server at http://10.8.2.3:6820
Scopes:
  kittyrec.admin → full access (all actions)
  kittyrec.mod   → limited (view, light moderation only)
No auth → redirect to https://auth.tabbycluster.net
Emergency login at /admin/emergency_login (env-var password)

Dashboard (/admin)

Shows:
  Online players list (username, level, room, VR/Screen badge, Dev badge)
  Actions: Profile, Gift, DM, Reset Password, Kick
  Active sessions list
  Recent admin actions log
  Stats: online count, sessions, total players, banned count

Player Management (/admin/admin_players)

Flask-Admin ModelView on profiles table
Actions:
  Ban (duration select + reason)
  Unban
  Disconnect (WebSocket kick)
  Gift XP (1000)
  Gift Tokens (100)
  Reset Password (generates temp, sends DM)
  Get Temp Password (offline players)
  Send Notification
  Toggle Developer flag

Admin API Endpoints

POST /admin/api/ban/<pid>           → ban player
POST /admin/api/unban/<pid>         → unban player
POST /admin/api/disconnect/<pid>    → kick WS
POST /admin/api/gift_player/<pid>   → send gift
POST /admin/api/reroll_store        → force store rotation
POST /admin/api/send_message        → broadcast system message
POST /admin/api/send_dm/<pid>       → DM a player
POST /admin/api/reset_password/<pid> → temp password + DM
POST /admin/api/gift_all            → gift all online players
POST /admin/api/toggle_dev/<pid>    → toggle developer flag
GET  /admin/api/stats               → server stats JSON
GET  /admin/api/console/read        → tail server log
GET  /admin/api/public_stats        → requires admin auth (not public)

Web Portal & Nameserver Pages

Web Portal (/portal) — authenticated player-facing pages

/portal           → login page
/portal/me        → player dashboard (gifts, profile, photos)
/portal/logout    → logout

POST /portal/api/consume_gift/<id>  → consume pending gift

Nameserver Pages — in-game browser (routes/nameserver.py)

/                   → homepage
/welcome            → welcome / landing
/dashboard          → player dashboard (requires game auth)
/leaderboard        → top players leaderboard
/account            → account management (change password, pfp)
/web/status         → server status JSON (no auth)
/web/leaderboard    → public leaderboard JSON (no auth)
/web/players        → online players (requires auth)
/web/friends        → friends list (requires auth)
/web/my-photos      → player's photos (requires auth)
/web/chats          → chat list + read (requires auth)
/web/notifications  → notification inbox (requires auth)
/web/change-password
/web/upload-pfp
/web/heartbeat      → keep game auth session alive
/web/token-balance  → currency balances

Public API (/api/public/v1/*)

No authentication required. Rate limited.

Endpoint Limit Returns
GET /status 120/min online count, sessions, total players, maintenance
GET /sessions 120/min all public game sessions
GET /players 120/min online players + room names
GET /leaderboard 60/min top 100 by XP
GET /search?q= 20/min player search (min 2 chars, max 20 results)
GET /profile/<id> 60/min public profile
GET /profile/<id>/photos 30/min photos by player
GET /photos 30/min recent photos
GET /activity 60/min activities with live players
GET /docs — this API's JSON spec

Internal API (/api/internal/discord/*)

Requires X-Bot-Secret header (shared secret in config.yaml + bot config.json). Used only by the KittyNet Discord bot.

POST /api/internal/discord/initiate
  Body: { username, discord_user_id, discord_username }
  → Exact username match only
  → Checks: already linked, player exists, profile already linked, player online
  → Rate limit: one code per player per 60 seconds (DB checked)
  → Sends in-game DM with 6-char code (expires 10min)
  → Returns: { status: "sent"|"not_found"|"not_online"|"already_linked"|"rate_limited" }

POST /api/internal/discord/confirm
  Body: { code, discord_user_id, discord_username }
  → Validates code + discord_user_id match in discord_link_codes table
  → Writes permanent link to discord_links table
  → Returns: { status: "linked"|"invalid_code"|"already_linked", profile info }

Discord Integration

Webhooks (core/discord.py)

Three webhook channels, all fire-and-forget (background threads):

Webhook Events
webhook_public First logins, player milestones, online/offline
webhook_admin Bans, server shutdown, admin actions
webhook_anticheat IP bans, suspicious activity

Throttle system prevents spam — configurable cooldown per event key.

Discord Bot (KittyNet-DiscordBot/bot.py)

Runs as a separate process (kittynet systemd service).

Slash commands:

Command Description
/status Server status embed
/players Who's online
/sessions Active game sessions
/ingame Players grouped by room
/leaderboard Top 10 by XP
/profile <username> Player profile (search-based lookup)
/search <username> Player search, up to 10 results
/photos [player] Recent photos, optional player filter
/link <username> Start Discord→KittyRec account linking
/getkittyrec Request alpha access
/analytics growth|activity|channels|voice|users|summary Admin-only analytics

Background loops:

status_loop (5min)   → updates stat voice channels + status embed
analytics_loop (10min) → snapshots member count, cleans old data
milestone_loop (5min)  → announces player count milestones

DM handler:

on_message (DM channel)
  → if message matches [ABCDEFGHJKLMNPQRSTUVWXYZ23456789]{6}
  → calls POST /api/internal/discord/confirm
  → on success: sends linked embed + assigns player_role if configured

Discord linking security:

  • Bot-side: 60s per-user cooldown (in-memory)
  • Server-side: 60s per-player cooldown (DB checked)
  • Code alphabet excludes ambiguous chars (0/O/1/I)
  • Secret comparison uses hmac.compare_digest

KittyLoader (routes/KittyLoader.py)

Used by the game launcher (KittyLoader desktop app).

All routes except /KittyRec/getfile require:
  User-Agent: KittyLoader/*
  Header: Branch: <branch-guid>

Valid branches:
  bff0c094-... → Prod
  fb4ce906-... → Dev
  f94fa96b-... → BVT

GET /api/kittyloader/v1/start
  → Analytics event logged (branch + UA)
  → Returns { exit: false }

GET /api/kittyloader/v1/exit
  → 200 OK

GET /api/kittyloader/v1/KittyRec/get
  → Returns { FileUrl, SHA512 } for the DLL for this branch
  → Reads from data/KittyRecDlls.json

GET /api/kittyloader/v1/KittyRec/getfile?filename=<name>
  → Serves file from kittyrec_dlls/ directory
  → No auth, no UA check (intentional — direct download link)

Download System (routes/downloads.py)

GET /download/current
  → Renders current build download page (HTML)
  → Shows size, SHA-256, download count

GET /download/<date>/<name>/<h1>/<h2>/<h3>/get
  → Actual file download, increments download counter

GET /api/launcher/v1/manifest
  → Build manifest for the launcher

Admin endpoints (require admin auth):
  POST /admin/api/downloads/set_current/<build_id>
  POST /admin/api/downloads/upload  (multipart, chunked)

Images & Photos (routes/images.py, routes/avatar.py)

GET /alt/<name>
  → Serves profile image by name from saved_images table
  → Strips dot-files early (prevents .env leakage)

GET /api/images/v1/<int:id>   → room image by ID
GET /api/images/v3/*          → named image lookup

POST /api/images/v1/upload    → upload room/memory image
POST /web/upload-pfp          → upload profile picture

Rate Limiting (core/limiter.py)

  • Uses flask-limiter, keyed by request.remote_addr (correct after ProxyFix)
  • Global defaults in limiter.py
  • Route overrides: @limiter.limit("N per minute")
  • Internal endpoints (/api/internal/*) protected by secret, not IP rate limit
  • Bot-side layer added for /link command (60s cooldown in-memory)

Database Tables Reference

Core

Table Purpose
profiles All player accounts (username, display_name, xp, level, banned, etc.)
avatars Current equipped avatar data per player
settings Key-value settings per player (screen_mode_user, OOBE, etc.)
platform_accounts Platform→Profile mapping (Steam, Oculus, etc.)
cached_logins Saved login tokens

Social

Table Purpose
relationships Friends, ignored, following (type 1/2/3/4)
messages Direct messages / notifications
chat_threads Group/DM chat threads
chat_thread_players Thread membership
chat_messages Messages within threads

Economy & Progression

Table Purpose
gifts Pending + consumed gifts (avatar items)
unlocked_items Items a player owns
consumable_inventory Consumable item counts
store_featured_items Current store rotation override
subscriptions Player subscriptions
saved_outfits Saved outfit slots (up to 3)
equipment_favorites Favorited equipment skins
leaderboard_scores Per-activity leaderboard entries
daily_login_rewards Last claim dates for daily login
daily_gifts Daily gift tracking
daily_cheers Daily cheer limit tracking

Objectives & Challenges

Table Purpose
player_challenge_progress Weekly challenge progress
daily_objective_completions Daily objective state
weekly_schedule Scheduled challenge definitions
player_events In-game events per player

Rooms

Table Purpose
rooms User-created room definitions
room_permissions Per-room permission entries
room_bookmarks Bookmarked rooms per player
room_cheers Room cheer state
room_visits Visit history
room_gamemode_defaults Default gamemode per room
disabled_activities Activities disabled server-wide

Security & Admin

Table Purpose
ban_log Full ban/unban history
ip_logins IP address history per player
admin_action_log All admin actions with timestamp
admin_todos Admin todo list
admin_issues Admin issue tracker

Images & Media

Table Purpose
saved_images Profile photos + room screenshots
profile_images Profile picture blobs
profile_image_history Profile picture history
memory_uploads MemoryStream video uploads

Discord & System

Table Purpose
discord_links Permanent Discord↔KittyRec account links
discord_link_codes Temporary link codes (10min expiry)
system_reply_queue Bot auto-reply state machine
amplitude_events Analytics events log
player_count_history Historical online count snapshots
dll_archive KittyLoader DLL version archive

System Account (PID 23)

  • Always appears online to all clients
  • Used as sender for all system DMs and notifications
  • Maintained by kittyrec-system daemon thread (fake WS keepalive)
  • Excluded from connected_ids() player count
  • All players auto-friended with PID 23 on account creation

Core Module Map

Module Role
core/database.py All SQL — single Database class, 2000+ lines
core/state.py In-memory state: SessionManager, ConnectionRegistry, GameSession
core/auth.py JWT encode/decode, @check_auth, get_current_profile_id()
core/config.py Loads data/config.yaml → server/auth/discord/sdk sections
core/constants.py KNOWN_ACTIVITIES, DORM_ROOM_GUID
core/builders.py Response builder helpers (activity_info, profile shapes)
core/daemons.py Background threads: ban enforcer, presence watchdog, count recorder, shutdown handler
core/discord.py Webhook fire-and-forget helpers + throttle
core/limiter.py Flask-Limiter setup, IP extraction
core/ws_helpers.py push_presence(), push_gift() WS broadcast helpers
core/ban_service.py cascade_kick_linked(), kick_player()
core/password_crypto.py bcrypt helpers
core/profanity.py Profanity filter for display names
core/admin_auth.py Admin cookie auth, scope checking
core/admin_panel.py Flask-Admin views (900+ lines)
core/anticheat.py Anticheat checks
core/burst_detector.py Request burst detection
core/system_messages.py System DM helpers
core/models.py SQLAlchemy models (Flask-Admin only)