dubs-server 1.0.0

package/routes/authRoutes.js

@@ -0,0 +1,2310 @@
+/**
+ * 🔐 Authentication API Routes
+ * 
+ * Endpoints for wallet-based authentication and user registration
+ */
+
+const express = require('express');
+const router = express.Router();
+const nacl = require('tweetnacl');
+const bs58 = require('bs58').default;
+const { PublicKey } = require('@solana/web3.js');
+const { pool } = require('../services/db'); // Shared database pool
+const {
+  authenticate,
+  generateToken,
+  createSession,
+  deleteSession,
+  deleteAllSessions,
+  JWT_EXPIRES_IN
+} = require('../middleware/authenticate');
+const { forwardChatNotification } = require('../services/telegramNotifications');
+const { getVapidPublicKey } = require('../services/pushNotifications');
+const promoService = require('../services/promoService');
+
+// Load environment variables
+require('dotenv').config();
+
+// Initialize tables
+async function initializeTables() {
+  if (!process.env.DATABASE_URL) {
+    console.log('⚠️  Auth tables skipped: DATABASE_URL not set (database features disabled)');
+    return;
+  }
+
+  try {
+    await pool.query(`
+      CREATE TABLE IF NOT EXISTS users (
+        id SERIAL PRIMARY KEY,
+        wallet_address VARCHAR(44) UNIQUE NOT NULL,
+        email VARCHAR(255),
+        username VARCHAR(50) NOT NULL,
+        avatar TEXT,
+        referral_code VARCHAR(50), -- The referral code they ENTERED (not unique - multiple users can use same code)
+        my_referral_code VARCHAR(50) UNIQUE, -- Their OWN referral code to share (must be unique)
+        signature TEXT,
+        onboarding_complete BOOLEAN DEFAULT false,
+        created_at TIMESTAMP DEFAULT NOW(),
+        updated_at TIMESTAMP DEFAULT NOW()
+      );
+
+      CREATE TABLE IF NOT EXISTS auth_nonces (
+        wallet_address VARCHAR(44) PRIMARY KEY,
+        nonce VARCHAR(64) NOT NULL,
+        expires_at TIMESTAMP NOT NULL,
+        used BOOLEAN DEFAULT false,
+        created_at TIMESTAMP DEFAULT NOW()
+      );
+
+      CREATE TABLE IF NOT EXISTS user_sessions (
+        id SERIAL PRIMARY KEY,
+        wallet_address VARCHAR(44) NOT NULL,
+        user_id INTEGER REFERENCES users(id) ON DELETE CASCADE,
+        token_hash VARCHAR(64) NOT NULL,
+        expires_at TIMESTAMP NOT NULL,
+        created_at TIMESTAMP DEFAULT NOW(),
+        last_activity TIMESTAMP DEFAULT NOW(),
+        UNIQUE(wallet_address, token_hash)
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_users_wallet ON users(wallet_address);
+      CREATE INDEX IF NOT EXISTS idx_users_username_lower ON users(LOWER(username));
+      CREATE INDEX IF NOT EXISTS idx_users_referral_code ON users(referral_code) WHERE referral_code IS NOT NULL;
+      CREATE INDEX IF NOT EXISTS idx_users_my_referral_code ON users(my_referral_code) WHERE my_referral_code IS NOT NULL;
+      CREATE INDEX IF NOT EXISTS idx_nonces_expires ON auth_nonces(expires_at);
+      CREATE INDEX IF NOT EXISTS idx_sessions_wallet ON user_sessions(wallet_address);
+      CREATE INDEX IF NOT EXISTS idx_sessions_expires ON user_sessions(expires_at);
+      CREATE INDEX IF NOT EXISTS idx_sessions_token_hash ON user_sessions(token_hash);
+
+      -- User badges/rewards table
+      CREATE TABLE IF NOT EXISTS user_badges (
+        id SERIAL PRIMARY KEY,
+        user_id INTEGER REFERENCES users(id) ON DELETE CASCADE,
+        badge_type VARCHAR(50) NOT NULL,
+        badge_name VARCHAR(100) NOT NULL,
+        badge_description TEXT,
+        badge_icon VARCHAR(255),
+        earned_at TIMESTAMP DEFAULT NOW(),
+        referral_count INTEGER,
+        UNIQUE(user_id, badge_type)
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_user_badges_user_id ON user_badges(user_id);
+      CREATE INDEX IF NOT EXISTS idx_user_badges_type ON user_badges(badge_type);
+
+      -- Pending game dismissals (tracks which pending game deeplinks user has dismissed)
+      CREATE TABLE IF NOT EXISTS pending_game_dismissals (
+        id SERIAL PRIMARY KEY,
+        wallet_address VARCHAR(44) NOT NULL,
+        game_id VARCHAR(255) NOT NULL,
+        dismissed_at TIMESTAMP DEFAULT NOW(),
+        UNIQUE(wallet_address, game_id)
+      );
+      CREATE INDEX IF NOT EXISTS idx_pending_dismissals_wallet ON pending_game_dismissals(wallet_address);
+    `);
+    
+    // Migration: Add my_referral_code column if it doesn't exist (for existing databases)
+    try {
+      await pool.query(`
+        DO $$ 
+        BEGIN
+          IF NOT EXISTS (
+            SELECT 1 FROM information_schema.columns 
+            WHERE table_name = 'users' AND column_name = 'my_referral_code'
+          ) THEN
+            ALTER TABLE users ADD COLUMN my_referral_code VARCHAR(50) UNIQUE;
+            CREATE INDEX IF NOT EXISTS idx_users_my_referral_code ON users(my_referral_code) WHERE my_referral_code IS NOT NULL;
+            RAISE NOTICE 'Added my_referral_code column to users table';
+          END IF;
+        END $$;
+      `);
+    } catch (migrationError) {
+      console.log('⚠️  Migration note (may be expected):', migrationError.message);
+    }
+
+    // Migration: Add Telegram connection fields if they don't exist
+    try {
+      await pool.query(`
+        DO $$ 
+        BEGIN 
+          -- Add telegram_user_id column
+          IF NOT EXISTS (
+            SELECT 1 FROM information_schema.columns 
+            WHERE table_name = 'users' AND column_name = 'telegram_user_id'
+          ) THEN
+            ALTER TABLE users ADD COLUMN telegram_user_id BIGINT UNIQUE;
+            CREATE INDEX IF NOT EXISTS idx_users_telegram_user_id ON users(telegram_user_id) WHERE telegram_user_id IS NOT NULL;
+            RAISE NOTICE 'Added telegram_user_id column to users table';
+          END IF;
+
+          -- Add telegram_username column
+          IF NOT EXISTS (
+            SELECT 1 FROM information_schema.columns 
+            WHERE table_name = 'users' AND column_name = 'telegram_username'
+          ) THEN
+            ALTER TABLE users ADD COLUMN telegram_username VARCHAR(255);
+            RAISE NOTICE 'Added telegram_username column to users table';
+          END IF;
+
+          -- Add telegram_first_name column
+          IF NOT EXISTS (
+            SELECT 1 FROM information_schema.columns 
+            WHERE table_name = 'users' AND column_name = 'telegram_first_name'
+          ) THEN
+            ALTER TABLE users ADD COLUMN telegram_first_name VARCHAR(255);
+            RAISE NOTICE 'Added telegram_first_name column to users table';
+          END IF;
+
+          -- Add telegram_last_name column
+          IF NOT EXISTS (
+            SELECT 1 FROM information_schema.columns 
+            WHERE table_name = 'users' AND column_name = 'telegram_last_name'
+          ) THEN
+            ALTER TABLE users ADD COLUMN telegram_last_name VARCHAR(255);
+            RAISE NOTICE 'Added telegram_last_name column to users table';
+          END IF;
+
+          -- Add telegram_photo_url column
+          IF NOT EXISTS (
+            SELECT 1 FROM information_schema.columns 
+            WHERE table_name = 'users' AND column_name = 'telegram_photo_url'
+          ) THEN
+            ALTER TABLE users ADD COLUMN telegram_photo_url TEXT;
+            RAISE NOTICE 'Added telegram_photo_url column to users table';
+          END IF;
+
+          -- Add telegram_connected_at column
+          IF NOT EXISTS (
+            SELECT 1 FROM information_schema.columns 
+            WHERE table_name = 'users' AND column_name = 'telegram_connected_at'
+          ) THEN
+            ALTER TABLE users ADD COLUMN telegram_connected_at TIMESTAMP;
+            RAISE NOTICE 'Added telegram_connected_at column to users table';
+          END IF;
+        END $$;
+      `);
+    } catch (migrationError) {
+      console.log('⚠️  Telegram migration note (may be expected):', migrationError.message);
+    }
+
+    // Migration: Create telegram notification preferences table
+    try {
+      await pool.query(`
+        CREATE TABLE IF NOT EXISTS telegram_notification_preferences (
+          user_id INTEGER PRIMARY KEY REFERENCES users(id) ON DELETE CASCADE,
+          notify_reply BOOLEAN DEFAULT true,
+          notify_reaction BOOLEAN DEFAULT true,
+          notify_friend_request BOOLEAN DEFAULT true,
+          notify_friend_request_accepted BOOLEAN DEFAULT true,
+          notify_friend_request_declined BOOLEAN DEFAULT true,
+          notify_referral BOOLEAN DEFAULT true,
+          notify_mention BOOLEAN DEFAULT true,
+          notify_friend_message BOOLEAN DEFAULT true,
+          notify_game_joined BOOLEAN DEFAULT true,
+          notify_game_invite BOOLEAN DEFAULT true,
+          created_at TIMESTAMP DEFAULT NOW(),
+          updated_at TIMESTAMP DEFAULT NOW()
+        );
+      `);
+      console.log('✅ Telegram notification preferences table initialized');
+    } catch (prefError) {
+      console.log('⚠️  Telegram preferences table note:', prefError.message);
+    }
+    
+    // Migration: Add notify_game_invite column if it doesn't exist
+    try {
+      await pool.query(`
+        DO $$ 
+        BEGIN
+          IF NOT EXISTS (
+            SELECT 1 FROM information_schema.columns 
+            WHERE table_name = 'telegram_notification_preferences' AND column_name = 'notify_game_invite'
+          ) THEN
+            ALTER TABLE telegram_notification_preferences 
+            ADD COLUMN notify_game_invite BOOLEAN DEFAULT true;
+            RAISE NOTICE 'Added notify_game_invite column';
+          END IF;
+        END $$;
+      `);
+    } catch (columnError) {
+      console.log('⚠️  notify_game_invite column migration:', columnError.message);
+    }
+    
+    console.log('✅ Auth tables initialized (with JWT sessions and Telegram support)');
+  } catch (error) {
+    console.error('❌ Failed to initialize auth tables:', error.message);
+    console.error('   Full error:', error);
+  }
+}
+
+initializeTables();
+
+module.exports = () => {
+  
+  /**
+   * GET /auth/nonce/:walletAddress
+   * Get a nonce for signing (prevents replay attacks)
+   */
+  router.get('/nonce/:walletAddress', async (req, res) => {
+    try {
+      const { walletAddress } = req.params;
+      console.log('[Auth] Generating nonce for:', walletAddress);
+      
+      // Generate cryptographically secure nonce
+      const nonce = require('crypto').randomBytes(32).toString('hex');
+      
+      // Store nonce in database (use NOW() + interval for timezone safety)
+      await pool.query(
+        `INSERT INTO auth_nonces (wallet_address, nonce, expires_at, used)
+         VALUES ($1, $2, NOW() + INTERVAL '5 minutes', false)
+         ON CONFLICT (wallet_address) 
+         DO UPDATE SET nonce = $2, expires_at = NOW() + INTERVAL '5 minutes', used = false`,
+        [walletAddress, nonce]
+      );
+
+      const message = `Welcome to Dubs 🚀 Please sign this message to verify wallet ownership. This won't cost any SOL. \n\nNonce: ${nonce}`;
+      console.log('[Auth] Nonce generated successfully');
+      
+      res.json({
+        success: true,
+        nonce,
+        message
+      });
+    } catch (error) {
+      console.error('[Auth] Error generating nonce:', error);
+      console.error('[Auth] Full error:', error);
+      res.status(500).json({
+        success: false,
+        error: error.message
+      });
+    }
+  });
+
+  /**
+   * GET /auth/check-username/:username
+   * Check if a username is available (case-insensitive)
+   * Public endpoint - no authentication required
+   */
+  router.get('/check-username/:username', async (req, res) => {
+    try {
+      const { username } = req.params;
+      
+      // Validate username format
+      if (!username || username.length < 3) {
+        return res.json({
+          success: true,
+          available: false,
+          error: 'Username must be at least 3 characters'
+        });
+      }
+      
+      if (username.length > 20) {
+        return res.json({
+          success: true,
+          available: false,
+          error: 'Username must be 20 characters or less'
+        });
+      }
+      
+      if (!/^[a-zA-Z0-9_]+$/.test(username)) {
+        return res.json({
+          success: true,
+          available: false,
+          error: 'Username can only contain letters, numbers, and underscores'
+        });
+      }
+
+      // Check if username already exists (case-insensitive)
+      const result = await pool.query(
+        'SELECT id FROM users WHERE LOWER(username) = LOWER($1)',
+        [username]
+      );
+
+      const available = result.rows.length === 0;
+      
+      console.log(`[Auth] Username check: "${username}" is ${available ? 'available' : 'taken'}`);
+
+      res.json({
+        success: true,
+        available,
+        username
+      });
+    } catch (error) {
+      console.error('[Auth] Error checking username:', error);
+      res.status(500).json({
+        success: false,
+        error: error.message
+      });
+    }
+  });
+  
+  /**
+   * GET /auth/user/me
+   * Get authenticated user's FULL profile (requires authentication)
+   * Returns all fields including private data and referrer info
+   * IMPORTANT: Must be defined BEFORE /user/:walletAddress to avoid route collision
+   */
+  router.get('/user/me', authenticate, async (req, res) => {
+    try {
+      const result = await pool.query(
+        'SELECT * FROM users WHERE wallet_address = $1',
+        [req.user.walletAddress]
+      );
+
+      if (result.rows.length === 0) {
+        return res.status(404).json({
+          success: false,
+          error: 'User not found'
+        });
+      }
+
+      const user = result.rows[0];
+
+      // If user was referred by someone, fetch the referrer's info including their highest badge
+      let referrer = null;
+      if (user.referral_code) {
+        try {
+          const referrerResult = await pool.query(
+            'SELECT id, wallet_address, username, avatar FROM users WHERE my_referral_code = $1',
+            [user.referral_code]
+          );
+          
+          if (referrerResult.rows.length > 0) {
+            const referrerUser = referrerResult.rows[0];
+            
+            // Get referrer's highest badge (Captain > Ambassador > Recruiter)
+            const badgeResult = await pool.query(
+              `SELECT badge_type, badge_name, badge_icon
+               FROM user_badges
+               WHERE user_id = $1
+               ORDER BY 
+                 CASE badge_type
+                   WHEN 'captain' THEN 1
+                   WHEN 'ambassador' THEN 2
+                   WHEN 'recruiter' THEN 3
+                   ELSE 4
+                 END
+               LIMIT 1`,
+              [referrerUser.id]
+            );
+            
+            referrer = {
+              wallet_address: referrerUser.wallet_address,
+              username: referrerUser.username,
+              avatar: referrerUser.avatar,
+              badge: badgeResult.rows.length > 0 ? {
+                type: badgeResult.rows[0].badge_type,
+                name: badgeResult.rows[0].badge_name,
+                icon: badgeResult.rows[0].badge_icon
+              } : null
+            };
+            
+            console.log('[Auth] Found referrer for user:', referrer.username, 'with badge:', referrer.badge?.name || 'none');
+          }
+        } catch (referrerError) {
+          console.error('[Auth] Error fetching referrer:', referrerError.message);
+        }
+      }
+
+      // Return ALL fields (it's the user's own data) plus referrer info
+      res.json({
+        success: true,
+        user: user,
+        referrer: referrer
+      });
+    } catch (error) {
+      console.error('Error fetching user profile:', error);
+      res.status(500).json({
+        success: false,
+        error: error.message
+      });
+    }
+  });
+
+  /**
+   * GET /auth/user/:walletAddress
+   * Get PUBLIC user profile by wallet address
+   * Returns only public-safe fields (no email, referral code, etc.)
+   * Returns user: null if not found (instead of 404 to reduce console noise)
+   */
+  router.get('/user/:walletAddress', async (req, res) => {
+    try {
+      const { walletAddress } = req.params;
+
+      const result = await pool.query(
+        'SELECT wallet_address, username, avatar, onboarding_complete, created_at FROM users WHERE wallet_address = $1',
+        [walletAddress]
+      );
+
+      if (result.rows.length === 0) {
+        // Return success with null user (not a 404 error - this is a valid lookup)
+        return res.json({
+          success: true,
+          user: null
+        });
+      }
+
+      // Return only public-safe fields
+      const user = result.rows[0];
+      res.json({
+        success: true,
+        user: {
+          wallet_address: user.wallet_address,
+          username: user.username,
+          avatar: user.avatar,
+          onboarding_complete: user.onboarding_complete,
+          created_at: user.created_at,
+          // Note: email, referral_code, signature are NOT included
+        }
+      });
+    } catch (error) {
+      console.error('Error fetching user:', error);
+      res.status(500).json({
+        success: false,
+        error: error.message
+      });
+    }
+  });
+
+  /**
+   * GET /auth/user-by-username/:username
+   * Get PUBLIC user profile by username
+   * Returns only public-safe fields (no email, referral code, etc.)
+   * Returns user: null if not found (instead of 404 to reduce console noise)
+   */
+  router.get('/user-by-username/:username', async (req, res) => {
+    try {
+      const { username } = req.params;
+
+      const result = await pool.query(
+        'SELECT wallet_address, username, avatar, onboarding_complete, created_at FROM users WHERE LOWER(username) = LOWER($1)',
+        [username]
+      );
+
+      if (result.rows.length === 0) {
+        // Return success with null user (not a 404 error - this is a valid lookup)
+        return res.json({
+          success: true,
+          user: null
+        });
+      }
+
+      // Return only public-safe fields
+      const user = result.rows[0];
+      res.json({
+        success: true,
+        user: {
+          wallet_address: user.wallet_address,
+          username: user.username,
+          avatar: user.avatar,
+          onboarding_complete: user.onboarding_complete,
+          created_at: user.created_at,
+          // Note: email, referral_code, signature are NOT included
+        }
+      });
+    } catch (error) {
+      console.error('Error fetching user by username:', error);
+      res.status(500).json({
+        success: false,
+        error: error.message
+      });
+    }
+  });
+
+  /**
+   * GET /auth/referrer/:referralCode
+   * Get PUBLIC user profile by their referral code (my_referral_code)
+   * Used to show who invited a new user when they visit with ?ref= param
+   * Returns only public-safe fields (no email, wallet address, etc.)
+   */
+  router.get('/referrer/:referralCode', async (req, res) => {
+    try {
+      const { referralCode } = req.params;
+      
+      if (!referralCode || referralCode.length < 4) {
+        return res.json({
+          success: true,
+          user: null
+        });
+      }
+
+      console.log('[Auth] Looking up referrer by code:', referralCode);
+
+      const result = await pool.query(
+        'SELECT username, avatar, created_at FROM users WHERE my_referral_code = $1',
+        [referralCode.toUpperCase()]
+      );
+
+      if (result.rows.length === 0) {
+        return res.json({
+          success: true,
+          user: null
+        });
+      }
+
+      // Return only public-safe fields (no wallet address for privacy)
+      const user = result.rows[0];
+      res.json({
+        success: true,
+        user: {
+          username: user.username,
+          avatar: user.avatar,
+          created_at: user.created_at,
+        }
+      });
+    } catch (error) {
+      console.error('[Auth] Error fetching referrer:', error);
+      res.status(500).json({
+        success: false,
+        error: error.message
+      });
+    }
+  });
+
+  /**
+   * POST /auth/verify-signature
+   * Verify that a signature matches the wallet AND nonce is valid
+   */
+  router.post('/verify-signature', async (req, res) => {
+    try {
+      const { walletAddress, message, signature, nonce } = req.body;
+      console.log('[Auth] Verifying signature for:', walletAddress);
+      console.log('[Auth] Nonce:', nonce);
+
+      // 1. Check nonce exists and hasn't been used
+      const nonceResult = await pool.query(
+        'SELECT * FROM auth_nonces WHERE wallet_address = $1 AND nonce = $2 AND used = false AND expires_at > NOW()',
+        [walletAddress, nonce]
+      );
+
+      console.log('[Auth] Nonce check result:', nonceResult.rows.length, 'rows');
+
+      if (nonceResult.rows.length === 0) {
+        console.log('[Auth] Nonce validation failed - checking why...');
+        
+        // Debug: check if nonce exists at all
+        const debugNonce = await pool.query(
+          'SELECT * FROM auth_nonces WHERE wallet_address = $1',
+          [walletAddress]
+        );
+        console.log('[Auth] All nonces for wallet:', debugNonce.rows);
+        
+        return res.status(400).json({
+          success: false,
+          valid: false,
+          error: 'Invalid or expired nonce'
+        });
+      }
+
+      // 2. Verify signature
+      console.log('[Auth] Verifying cryptographic signature...');
+      const signatureUint8 = bs58.decode(signature);
+      const messageUint8 = new TextEncoder().encode(message);
+      const publicKeyUint8 = new PublicKey(walletAddress).toBytes();
+
+      const valid = nacl.sign.detached.verify(
+        messageUint8,
+        signatureUint8,
+        publicKeyUint8
+      );
+
+      console.log('[Auth] Signature valid:', valid);
+
+      if (!valid) {
+        return res.status(400).json({
+          success: false,
+          valid: false,
+          error: 'Invalid signature'
+        });
+      }
+
+      // 3. Mark nonce as used
+      await pool.query(
+        'UPDATE auth_nonces SET used = true WHERE wallet_address = $1 AND nonce = $2',
+        [walletAddress, nonce]
+      );
+
+      console.log('[Auth] Signature verified successfully, nonce marked as used');
+
+      res.json({
+        success: true,
+        valid: true
+      });
+    } catch (error) {
+      console.error('[Auth] Error verifying signature:', error.message);
+      console.error('[Auth] Full error:', error);
+      res.status(400).json({
+        success: false,
+        valid: false,
+        error: error.message
+      });
+    }
+  });
+
+  /**
+   * POST /auth/register
+   * Register a new user (nonce should already be verified/used from verify-signature)
+   * Issues JWT token on successful registration
+   */
+  router.post('/register', async (req, res) => {
+    try {
+      const { walletAddress, signature, nonce, email, username, avatar, referralCode, promoCode } = req.body;
+
+      // Check if user already exists
+      const existing = await pool.query(
+        'SELECT * FROM users WHERE wallet_address = $1',
+        [walletAddress]
+      );
+
+      if (existing.rows.length > 0) {
+        return res.status(400).json({
+          success: false,
+          error: 'User already registered'
+        });
+      }
+
+      // Check if email is already registered
+      if (email) {
+        const emailCheck = await pool.query(
+          'SELECT id FROM users WHERE LOWER(email) = LOWER($1)',
+          [email]
+        );
+
+        if (emailCheck.rows.length > 0) {
+          return res.status(400).json({
+            success: false,
+            error: 'This email is already registered with another account',
+            field: 'email'
+          });
+        }
+      }
+
+      // Check if username is already taken (case-insensitive)
+      if (username) {
+        const usernameCheck = await pool.query(
+          'SELECT id FROM users WHERE LOWER(username) = LOWER($1)',
+          [username]
+        );
+
+        if (usernameCheck.rows.length > 0) {
+          return res.status(400).json({
+            success: false,
+            error: 'This username is already taken. Please choose a different one.',
+            field: 'username'
+          });
+        }
+      }
+
+      // Check if referral code exists (if provided)
+      if (referralCode && referralCode.trim()) {
+        const referralCheck = await pool.query(
+          'SELECT id FROM users WHERE my_referral_code = $1',
+          [referralCode.trim()]
+        );
+
+        if (referralCheck.rows.length === 0) {
+          return res.status(400).json({
+            success: false,
+            error: 'Invalid referral code. Please check the code and try again.',
+            field: 'referralCode'
+          });
+        }
+      }
+
+      // 🎁 Validate and reserve promo code if provided
+      // Promo codes are ONLY for new users (already checked above that user doesn't exist)
+      let promoReservation = null;
+      if (promoCode && promoCode.trim()) {
+        console.log('[Auth] 🎁 User registering with promo code:', promoCode);
+
+        // Reserve the promo code for this user
+        promoReservation = await promoService.reserveCode(promoCode.trim(), walletAddress);
+
+        if (!promoReservation.success && !promoReservation.valid) {
+          console.log('[Auth] ❌ Promo code reservation failed:', promoReservation.error);
+          return res.status(400).json({
+            success: false,
+            error: promoReservation.error || 'Invalid or unavailable promo code',
+            field: 'promoCode',
+            code: promoReservation.code || 'PROMO_ERROR' // Pass through error code (e.g., IP_ALREADY_USED)
+          });
+        }
+
+        console.log('[Auth] ✅ Promo code reserved:', promoReservation.code, promoReservation.amountSOL, 'SOL');
+      }
+
+      // Insert new user
+      const result = await pool.query(
+        `INSERT INTO users 
+         (wallet_address, email, username, avatar, referral_code, signature, created_at, onboarding_complete)
+         VALUES ($1, $2, $3, $4, $5, $6, NOW(), false)
+         RETURNING *`,
+        [walletAddress, email, username, avatar, referralCode || null, signature]
+      );
+
+      let user = result.rows[0];
+      
+      // 🎁 Generate the user's own referral code automatically
+      try {
+        const generateMyReferralCode = () => {
+          const chars = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789'; // Exclude confusing chars (0, O, I, 1)
+          let code = '';
+          for (let i = 0; i < 8; i++) {
+            code += chars.charAt(Math.floor(Math.random() * chars.length));
+          }
+          return code;
+        };
+
+        let myNewReferralCode;
+        let attempts = 0;
+        const maxAttempts = 10;
+
+        while (attempts < maxAttempts) {
+          myNewReferralCode = generateMyReferralCode();
+          
+          // Check if code already exists
+          const existingCodeResult = await pool.query(
+            'SELECT id FROM users WHERE my_referral_code = $1',
+            [myNewReferralCode]
+          );
+
+          if (existingCodeResult.rows.length === 0) {
+            // Code is unique, use it
+            break;
+          }
+
+          attempts++;
+          myNewReferralCode = null;
+        }
+
+        if (myNewReferralCode) {
+          const updateResult = await pool.query(
+            'UPDATE users SET my_referral_code = $1 WHERE id = $2 RETURNING *',
+            [myNewReferralCode, user.id]
+          );
+          user = updateResult.rows[0];
+          console.log('[Auth] Generated referral code for new user:', myNewReferralCode);
+        } else {
+          console.error('[Auth] Failed to generate unique referral code after', maxAttempts, 'attempts');
+        }
+      } catch (refCodeError) {
+        console.error('[Auth] Error generating referral code:', refCodeError.message);
+        // Non-fatal error - user can generate code later
+      }
+      
+      // Generate JWT token
+      const token = generateToken(user.wallet_address, user.id);
+      
+      // Calculate expiration date
+      const expiresAt = new Date();
+      const daysMatch = JWT_EXPIRES_IN.match(/(\d+)d/);
+      if (daysMatch) {
+        expiresAt.setDate(expiresAt.getDate() + parseInt(daysMatch[1]));
+      } else {
+        expiresAt.setDate(expiresAt.getDate() + 7); // Default 7 days
+      }
+      
+      // Store session in database
+      await createSession(user.wallet_address, user.id, token, expiresAt);
+
+      console.log('[Auth] User registered and session created:', user.wallet_address);
+
+      // 🎉 If user registered with a referral code, notify the referrer via existing notification system
+      if (referralCode) {
+        try {
+          // Find the user who owns this referral code
+          const referrerResult = await pool.query(
+            'SELECT id, wallet_address, username FROM users WHERE my_referral_code = $1',
+            [referralCode]
+          );
+
+          if (referrerResult.rows.length > 0) {
+            const referrer = referrerResult.rows[0];
+            console.log('[Auth] Notifying referrer:', referrer.wallet_address);
+
+            // Create notification in database using the existing chat_notifications table
+            const notifResult = await pool.query(
+              `INSERT INTO chat_notifications (user_id, sender_user_id, notification_type, created_at)
+               VALUES ($1, $2, 'referral', NOW())
+               RETURNING id`,
+              [referrer.id, user.id]
+            );
+
+            const notificationId = notifResult.rows[0].id;
+
+            // Forward to Telegram if connected
+            forwardChatNotification(pool, referrer.id, 'referral', user.username).catch(err => 
+              console.error('[Auth] Error forwarding referral notification to Telegram:', err.message)
+            );
+
+            // Send real-time notification via the existing WebSocket system
+            if (global.chatNamespace && global.onlineUsers) {
+              const targetSocketId = global.onlineUsers.get(referrer.id);
+              
+              if (targetSocketId) {
+                global.chatNamespace.to(targetSocketId).emit('notification', {
+                  id: notificationId,
+                  type: 'referral',
+                  read: false,
+                  message: user.username, // Store the new user's username as the message
+                  senderUsername: user.username,
+                  senderWallet: user.wallet_address,
+                  createdAt: new Date(),
+                });
+                console.log('[Auth] ✅ Referral notification sent to:', referrer.wallet_address);
+              } else {
+                console.log('[Auth] Referrer is offline, notification saved to database');
+              }
+            }
+
+            // 🏆 Check and award badges to the referrer
+            try {
+              // Count referrals for this referrer
+              const referralCountResult = await pool.query(
+                'SELECT COUNT(*) as count FROM users WHERE referral_code = $1',
+                [referralCode]
+              );
+              const referralCount = parseInt(referralCountResult.rows[0].count);
+              console.log('[Auth] Referrer now has', referralCount, 'referrals');
+
+              // Badge thresholds
+              const badgeChecks = [
+                { type: 'recruiter', name: 'Recruiter', threshold: 1, icon: '/badges/badge_0-removebg-preview.png', description: 'Referred your first user' },
+                { type: 'ambassador', name: 'Ambassador', threshold: 5, icon: '/badges/badge_1-removebg-preview.png', description: 'Referred 5 users' },
+                { type: 'captain', name: 'Captain', threshold: 10, icon: '/badges/badge_2-removebg-preview.png', description: 'Referred 10 or more users' }
+              ];
+
+              for (const badge of badgeChecks) {
+                if (referralCount >= badge.threshold) {
+                  await pool.query(
+                    `INSERT INTO user_badges (user_id, badge_type, badge_name, badge_description, badge_icon, referral_count)
+                     VALUES ($1, $2, $3, $4, $5, $6)
+                     ON CONFLICT (user_id, badge_type) DO NOTHING`,
+                    [referrer.id, badge.type, badge.name, badge.description, badge.icon, referralCount]
+                  );
+                }
+              }
+            } catch (badgeError) {
+              console.error('[Auth] Failed to check badges:', badgeError.message);
+            }
+
+            // 🤝 Automatically make referrer and new user friends
+            try {
+              await pool.query(
+                `INSERT INTO user_relationships (user_id, target_user_id, relationship_type)
+                 VALUES ($1, $2, 'friend'), ($2, $1, 'friend')
+                 ON CONFLICT (user_id, target_user_id)
+                 DO UPDATE SET relationship_type = 'friend'`,
+                [referrer.id, user.id]
+              );
+              console.log('[Auth] ✅ Automatic friendship created between', user.username, 'and', referrer.username);
+
+              // 📡 Emit WebSocket event to referrer so their friends list updates in real-time
+              // Using room-based emission (user-${userId}) which is more reliable than socket ID lookup
+              if (global.chatNamespace) {
+                const roomName = `user-${referrer.id}`;
+                console.log('[Auth] 📡 Emitting friend_added to room:', roomName);
+                global.chatNamespace.to(roomName).emit('friend_added', {
+                  friendId: user.id,
+                  friendUsername: user.username,
+                  friendWallet: user.wallet_address,
+                  friendAvatar: user.avatar,
+                  source: 'referral'
+                });
+                console.log('[Auth] 📡 Sent friend_added event to referrer room:', roomName, 'for user:', referrer.username);
+              } else {
+                console.log('[Auth] ⚠️ chatNamespace not available, cannot send friend_added event');
+              }
+            } catch (friendError) {
+              console.error('[Auth] Failed to create automatic friendship:', friendError.message);
+            }
+          }
+        } catch (notificationError) {
+          // Don't fail the registration if notification fails
+          console.error('[Auth] Failed to send referral notification:', notificationError.message);
+        }
+      }
+
+      // Build response
+      const response = {
+        success: true,
+        user: user,
+        token: token, // Return JWT token for Authorization header
+        authenticated: true
+      };
+
+      // Include promo reservation info if a promo code was reserved
+      if (promoReservation && promoReservation.success) {
+        // 🎁 Confirm the reservation so it won't expire (user successfully completed registration)
+        console.log('[Auth] 🎁 Confirming reservation for wallet:', walletAddress);
+        const confirmResult = await promoService.confirmReservation(walletAddress);
+        console.log('[Auth] 🎁 Confirm result:', confirmResult);
+
+        response.promoReservation = {
+          code: promoReservation.code,
+          amountSOL: promoReservation.amountSOL,
+          amountLamports: promoReservation.amountLamports
+          // Note: expiresAt removed since reservation is now permanent until used
+        };
+        console.log('[Auth] 🎁 User registered with promo code:', promoReservation.code, 'for wallet:', walletAddress);
+      }
+
+      res.json(response);
+    } catch (error) {
+      console.error('[Auth] Error registering user:', error.message);
+      console.error('[Auth] Full error:', error);
+      res.status(500).json({
+        success: false,
+        error: error.message
+      });
+    }
+  });
+
+  /**
+   * PUT /auth/user/:walletAddress
+   * Update user profile (requires authentication)
+   */
+  router.put('/user/:walletAddress', authenticate, async (req, res) => {
+    try {
+      const { walletAddress } = req.params;
+      const { email, username, avatar, preferred_currency } = req.body;
+
+      // Security: Verify user can only update their own profile
+      if (req.user.walletAddress !== walletAddress) {
+        return res.status(403).json({
+          success: false,
+          error: 'Unauthorized: Cannot update another user\'s profile'
+        });
+      }
+
+      // Validate preferred_currency if provided
+      const supportedCurrencies = ['USD', 'EUR', 'CAD', 'GBP', 'JPY', 'AUD', 'CHF', 'CNY', 'SEK', 'NZD'];
+      if (preferred_currency && !supportedCurrencies.includes(preferred_currency)) {
+        return res.status(400).json({
+          success: false,
+          error: `Invalid currency. Supported currencies: ${supportedCurrencies.join(', ')}`
+        });
+      }
+
+      const result = await pool.query(
+        `UPDATE users 
+         SET email = COALESCE($2, email),
+             username = COALESCE($3, username),
+             avatar = COALESCE($4, avatar),
+             preferred_currency = COALESCE($5, preferred_currency),
+             updated_at = NOW()
+         WHERE wallet_address = $1
+         RETURNING *`,
+        [walletAddress, email, username, avatar, preferred_currency]
+      );
+
+      if (result.rows.length === 0) {
+        return res.status(404).json({
+          success: false,
+          error: 'User not found'
+        });
+      }
+
+      res.json({
+        success: true,
+        user: result.rows[0]
+      });
+    } catch (error) {
+      console.error('Error updating user:', error);
+      res.status(500).json({
+        success: false,
+        error: error.message
+      });
+    }
+  });
+
+  /**
+   * POST /auth/user/:walletAddress/onboarding-complete
+   * Mark onboarding as complete (requires authentication)
+   */
+  router.post('/user/:walletAddress/onboarding-complete', authenticate, async (req, res) => {
+    try {
+      const { walletAddress } = req.params;
+      
+      // Verify user can only complete their own onboarding
+      if (req.user.walletAddress !== walletAddress) {
+        return res.status(403).json({
+          success: false,
+          error: 'Unauthorized'
+        });
+      }
+
+      console.log('[Auth] Completing onboarding for:', walletAddress);
+
+      await pool.query(
+        'UPDATE users SET onboarding_complete = true, updated_at = NOW() WHERE wallet_address = $1',
+        [walletAddress]
+      );
+
+      console.log('[Auth] Onboarding completed successfully');
+
+      res.json({
+        success: true
+      });
+    } catch (error) {
+      console.error('[Auth] Error completing onboarding:', error.message);
+      console.error('[Auth] Full error:', error);
+      res.status(500).json({
+        success: false,
+        error: error.message
+      });
+    }
+  });
+
+  /**
+   * POST /auth/user/me/generate-referral-code
+   * Generate a unique referral code for the authenticated user
+   * Requires authentication - users can only generate their own referral code
+   */
+  router.post('/user/me/generate-referral-code', authenticate, async (req, res) => {
+    try {
+      const walletAddress = req.user.walletAddress;
+      
+      console.log('[Auth] Generating referral code for:', walletAddress);
+
+      // Check if user already has their own referral code
+      const userResult = await pool.query(
+        'SELECT my_referral_code FROM users WHERE wallet_address = $1',
+        [walletAddress]
+      );
+
+      if (userResult.rows.length === 0) {
+        return res.status(404).json({
+          success: false,
+          error: 'User not found'
+        });
+      }
+
+      const existingCode = userResult.rows[0].my_referral_code;
+
+      // If user already has their own referral code, return it instead of generating a new one
+      if (existingCode) {
+        console.log('[Auth] User already has their own referral code:', existingCode);
+        return res.json({
+          success: true,
+          referralCode: existingCode,
+          message: 'Referral code already exists'
+        });
+      }
+
+      // Generate a unique referral code
+      // Format: 8 characters, alphanumeric uppercase (e.g., "ABC123XY")
+      const generateReferralCode = () => {
+        const chars = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789'; // Exclude confusing chars (0, O, I, 1)
+        let code = '';
+        for (let i = 0; i < 8; i++) {
+          code += chars.charAt(Math.floor(Math.random() * chars.length));
+        }
+        return code;
+      };
+
+      // Ensure uniqueness - try up to 10 times
+      let referralCode;
+      let attempts = 0;
+      const maxAttempts = 10;
+
+      while (attempts < maxAttempts) {
+        referralCode = generateReferralCode();
+        
+        // Check if code already exists
+        const existingCodeResult = await pool.query(
+          'SELECT id FROM users WHERE my_referral_code = $1',
+          [referralCode]
+        );
+
+        if (existingCodeResult.rows.length === 0) {
+          // Code is unique, break out of loop
+          break;
+        }
+
+        attempts++;
+        console.log(`[Auth] Referral code collision detected, attempt ${attempts}/${maxAttempts}`);
+      }
+
+      if (attempts >= maxAttempts) {
+        throw new Error('Failed to generate unique referral code after multiple attempts');
+      }
+
+      // Update user with new referral code (their own code, not the one they entered)
+      const updateResult = await pool.query(
+        'UPDATE users SET my_referral_code = $1, updated_at = NOW() WHERE wallet_address = $2 RETURNING *',
+        [referralCode, walletAddress]
+      );
+
+      console.log('[Auth] Referral code generated successfully:', referralCode);
+
+      res.json({
+        success: true,
+        referralCode: referralCode,
+        user: updateResult.rows[0]
+      });
+    } catch (error) {
+      console.error('[Auth] Error generating referral code:', error.message);
+      console.error('[Auth] Full error:', error);
+      res.status(500).json({
+        success: false,
+        error: error.message
+      });
+    }
+  });
+
+  /**
+   * GET /auth/user/me/referred-users
+   * Get list of users who joined using the authenticated user's referral code
+   * Requires authentication
+   */
+  router.get('/user/me/referred-users', authenticate, async (req, res) => {
+    try {
+      const walletAddress = req.user.walletAddress;
+      
+      console.log('[Auth] Fetching referred users for:', walletAddress);
+
+      // First, get the user's own referral code
+      const userResult = await pool.query(
+        'SELECT my_referral_code FROM users WHERE wallet_address = $1',
+        [walletAddress]
+      );
+
+      if (userResult.rows.length === 0) {
+        return res.status(404).json({
+          success: false,
+          error: 'User not found'
+        });
+      }
+
+      const myReferralCode = userResult.rows[0].my_referral_code;
+
+      if (!myReferralCode) {
+        // User hasn't generated a referral code yet, so no one could have used it
+        return res.json({
+          success: true,
+          referredUsers: [],
+          totalReferrals: 0
+        });
+      }
+
+      // Get all users who joined using this referral code
+      const referredUsersResult = await pool.query(
+        `SELECT 
+          wallet_address,
+          username,
+          avatar,
+          created_at
+        FROM users 
+        WHERE referral_code = $1
+        ORDER BY created_at DESC`,
+        [myReferralCode]
+      );
+
+      console.log('[Auth] Found', referredUsersResult.rows.length, 'referred users');
+
+      res.json({
+        success: true,
+        referredUsers: referredUsersResult.rows.map(user => ({
+          walletAddress: user.wallet_address,
+          username: user.username,
+          avatar: user.avatar,
+          joinedAt: user.created_at
+        })),
+        totalReferrals: referredUsersResult.rows.length
+      });
+    } catch (error) {
+      console.error('[Auth] Error fetching referred users:', error.message);
+      console.error('[Auth] Full error:', error);
+      res.status(500).json({
+        success: false,
+        error: error.message
+      });
+    }
+  });
+
+  /**
+   * GET /auth/user/me/badges
+   * Get authenticated user's earned badges
+   * Requires authentication
+   */
+  router.get('/user/me/badges', authenticate, async (req, res) => {
+    try {
+      const walletAddress = req.user.walletAddress;
+      
+      console.log('[Auth] Fetching badges for:', walletAddress);
+
+      // Get user ID
+      const userResult = await pool.query(
+        'SELECT id FROM users WHERE wallet_address = $1',
+        [walletAddress]
+      );
+
+      if (userResult.rows.length === 0) {
+        return res.status(404).json({
+          success: false,
+          error: 'User not found'
+        });
+      }
+
+      const userId = userResult.rows[0].id;
+
+      // Get user's badges
+      const badgesResult = await pool.query(
+        `SELECT 
+          badge_type,
+          badge_name,
+          badge_description,
+          badge_icon,
+          earned_at,
+          referral_count
+        FROM user_badges
+        WHERE user_id = $1
+        ORDER BY earned_at DESC`,
+        [userId]
+      );
+
+      console.log('[Auth] Found', badgesResult.rows.length, 'badges');
+
+      res.json({
+        success: true,
+        badges: badgesResult.rows
+      });
+    } catch (error) {
+      console.error('[Auth] Error fetching badges:', error.message);
+      console.error('[Auth] Full error:', error);
+      res.status(500).json({
+        success: false,
+        error: error.message
+      });
+    }
+  });
+
+  /**
+   * POST /auth/user/me/check-badges
+   * Check and award badges based on referral count
+   * Requires authentication
+   */
+  router.post('/user/me/check-badges', authenticate, async (req, res) => {
+    try {
+      const walletAddress = req.user.walletAddress;
+      
+      console.log('[Auth] Checking badges for:', walletAddress);
+
+      // Get user ID and referral code
+      const userResult = await pool.query(
+        'SELECT id, my_referral_code FROM users WHERE wallet_address = $1',
+        [walletAddress]
+      );
+
+      if (userResult.rows.length === 0) {
+        return res.status(404).json({
+          success: false,
+          error: 'User not found'
+        });
+      }
+
+      const userId = userResult.rows[0].id;
+      const myReferralCode = userResult.rows[0].my_referral_code;
+
+      if (!myReferralCode) {
+        return res.json({
+          success: true,
+          message: 'No referral code generated yet',
+          badgesAwarded: []
+        });
+      }
+
+      // Count referrals
+      const referralCountResult = await pool.query(
+        'SELECT COUNT(*) as count FROM users WHERE referral_code = $1',
+        [myReferralCode]
+      );
+
+      const referralCount = parseInt(referralCountResult.rows[0].count);
+      console.log('[Auth] User has', referralCount, 'referrals');
+
+      // Define badge thresholds
+      const badges = [
+        {
+          type: 'recruiter',
+          name: 'Recruiter',
+          description: 'Referred your first user',
+          icon: '/badges/badge_0-removebg-preview.png',
+          threshold: 1
+        },
+        {
+          type: 'ambassador',
+          name: 'Ambassador',
+          description: 'Referred 5 users',
+          icon: '/badges/badge_1-removebg-preview.png',
+          threshold: 5
+        },
+        {
+          type: 'captain',
+          name: 'Captain',
+          description: 'Referred 10 or more users',
+          icon: '/badges/badge_2-removebg-preview.png',
+          threshold: 10
+        }
+      ];
+
+      const badgesAwarded = [];
+
+      // Check each badge threshold
+      for (const badge of badges) {
+        if (referralCount >= badge.threshold) {
+          // Try to award badge (will be ignored if already exists due to UNIQUE constraint)
+          try {
+            const insertResult = await pool.query(
+              `INSERT INTO user_badges (user_id, badge_type, badge_name, badge_description, badge_icon, referral_count)
+               VALUES ($1, $2, $3, $4, $5, $6)
+               ON CONFLICT (user_id, badge_type) DO NOTHING
+               RETURNING *`,
+              [userId, badge.type, badge.name, badge.description, badge.icon, referralCount]
+            );
+
+            if (insertResult.rows.length > 0) {
+              badgesAwarded.push({
+                ...badge,
+                earnedAt: insertResult.rows[0].earned_at
+              });
+              console.log('[Auth] ✅ Awarded badge:', badge.name);
+            }
+          } catch (badgeError) {
+            console.error('[Auth] Error awarding badge:', badge.name, badgeError.message);
+          }
+        }
+      }
+
+      res.json({
+        success: true,
+        referralCount,
+        badgesAwarded,
+        message: badgesAwarded.length > 0 
+          ? `Congratulations! You earned ${badgesAwarded.length} badge(s)!`
+          : 'Keep referring to earn more badges!'
+      });
+    } catch (error) {
+      console.error('[Auth] Error checking badges:', error.message);
+      console.error('[Auth] Full error:', error);
+      res.status(500).json({
+        success: false,
+        error: error.message
+      });
+    }
+  });
+
+  /**
+   * POST /auth/login
+   * Login existing user after signature verification
+   * Issues JWT token for authenticated session
+   */
+  router.post('/login', async (req, res) => {
+    try {
+      const { walletAddress, signature, nonce, message } = req.body;
+      console.log('[Auth] Login attempt for:', walletAddress);
+
+      // 1. Check nonce exists and hasn't been used
+      const nonceResult = await pool.query(
+        'SELECT * FROM auth_nonces WHERE wallet_address = $1 AND nonce = $2 AND used = false AND expires_at > NOW()',
+        [walletAddress, nonce]
+      );
+
+      if (nonceResult.rows.length === 0) {
+        return res.status(400).json({
+          success: false,
+          error: 'Invalid or expired nonce'
+        });
+      }
+
+      // 2. Verify signature
+      const signatureUint8 = bs58.decode(signature);
+      const messageUint8 = new TextEncoder().encode(message);
+      const publicKeyUint8 = new PublicKey(walletAddress).toBytes();
+
+      const valid = nacl.sign.detached.verify(
+        messageUint8,
+        signatureUint8,
+        publicKeyUint8
+      );
+
+      if (!valid) {
+        return res.status(400).json({
+          success: false,
+          error: 'Invalid signature'
+        });
+      }
+
+      // 3. Mark nonce as used
+      await pool.query(
+        'UPDATE auth_nonces SET used = true WHERE wallet_address = $1 AND nonce = $2',
+        [walletAddress, nonce]
+      );
+
+      // 4. Get user from database
+      const userResult = await pool.query(
+        'SELECT * FROM users WHERE wallet_address = $1',
+        [walletAddress]
+      );
+
+      if (userResult.rows.length === 0) {
+        return res.status(404).json({
+          success: false,
+          error: 'User not found. Please register first.'
+        });
+      }
+
+      const user = userResult.rows[0];
+
+      // 5. Generate JWT token
+      const token = generateToken(user.wallet_address, user.id);
+      
+      // Calculate expiration date
+      const expiresAt = new Date();
+      const daysMatch = JWT_EXPIRES_IN.match(/(\d+)d/);
+      if (daysMatch) {
+        expiresAt.setDate(expiresAt.getDate() + parseInt(daysMatch[1]));
+      } else {
+        expiresAt.setDate(expiresAt.getDate() + 7);
+      }
+      
+      // 6. Store session in database
+      await createSession(user.wallet_address, user.id, token, expiresAt);
+
+      console.log('[Auth] User logged in successfully:', user.wallet_address);
+
+      res.json({
+        success: true,
+        user: user,
+        token: token, // Return JWT token for Authorization header
+        authenticated: true
+      });
+    } catch (error) {
+      console.error('[Auth] Error logging in user:', error.message);
+      res.status(500).json({
+        success: false,
+        error: error.message
+      });
+    }
+  });
+
+  /**
+   * GET /auth/validate-session
+   * Check if current session is valid (requires authentication)
+   */
+  router.get('/validate-session', authenticate, async (req, res) => {
+    try {
+      // If middleware passed, session is valid
+      // Get fresh user data
+      const result = await pool.query(
+        'SELECT * FROM users WHERE wallet_address = $1',
+        [req.user.walletAddress]
+      );
+
+      if (result.rows.length === 0) {
+        return res.status(404).json({
+          success: false,
+          valid: false,
+          error: 'User not found'
+        });
+      }
+
+      res.json({
+        success: true,
+        valid: true,
+        user: result.rows[0]
+      });
+    } catch (error) {
+      console.error('[Auth] Error validating session:', error);
+      res.status(500).json({
+        success: false,
+        valid: false,
+        error: error.message
+      });
+    }
+  });
+
+  /**
+   * POST /auth/logout
+   * Logout user and invalidate session
+   */
+  router.post('/logout', authenticate, async (req, res) => {
+    try {
+      // Get token from Authorization header
+      const authHeader = req.headers.authorization;
+      const token = authHeader ? authHeader.substring(7) : null;
+      
+      if (token) {
+        // Delete session from database
+        await deleteSession(req.user.walletAddress, token);
+      }
+
+      console.log('[Auth] User logged out:', req.user.walletAddress);
+
+      res.json({
+        success: true,
+        message: 'Logged out successfully'
+      });
+    } catch (error) {
+      console.error('[Auth] Error logging out:', error);
+      res.status(500).json({
+        success: false,
+        error: error.message
+      });
+    }
+  });
+
+  /**
+   * POST /auth/logout-all
+   * Logout from all devices (requires authentication)
+   */
+  router.post('/logout-all', authenticate, async (req, res) => {
+    try {
+      // Delete all sessions for this wallet
+      await deleteAllSessions(req.user.walletAddress);
+
+      console.log('[Auth] User logged out from all devices:', req.user.walletAddress);
+
+      res.json({
+        success: true,
+        message: 'Logged out from all devices'
+      });
+    } catch (error) {
+      console.error('[Auth] Error logging out from all devices:', error);
+      res.status(500).json({
+        success: false,
+        error: error.message
+      });
+    }
+  });
+
+  // ===== TELEGRAM CONNECTION ENDPOINTS =====
+
+  /**
+   * POST /auth/user/me/link-telegram
+   * Link Telegram account to authenticated user
+   */
+  router.post('/user/me/link-telegram', authenticate, async (req, res) => {
+    try {
+      const { telegramUser } = req.body;
+      const walletAddress = req.user.walletAddress;
+
+      console.log('[Auth] Linking Telegram for user:', walletAddress, 'Telegram ID:', telegramUser.id);
+
+      // Validate Telegram data
+      if (!telegramUser || !telegramUser.id) {
+        return res.status(400).json({
+          success: false,
+          error: 'Invalid Telegram user data'
+        });
+      }
+
+      // Verify Telegram auth hash
+      const crypto = require('crypto');
+      const botToken = process.env.TELEGRAM_BOT_TOKEN;
+      
+      if (botToken && telegramUser.hash) {
+        // Create data check string
+        const dataCheckArr = Object.keys(telegramUser)
+          .filter(key => key !== 'hash')
+          .sort()
+          .map(key => `${key}=${telegramUser[key]}`);
+        const dataCheckString = dataCheckArr.join('\n');
+        
+        // Create secret key
+        const secretKey = crypto.createHash('sha256').update(botToken).digest();
+        
+        // Calculate hash
+        const calculatedHash = crypto
+          .createHmac('sha256', secretKey)
+          .update(dataCheckString)
+          .digest('hex');
+        
+        // Verify hash matches
+        if (calculatedHash !== telegramUser.hash) {
+          console.error('[Auth] Telegram auth hash verification failed');
+          return res.status(401).json({
+            success: false,
+            error: 'Invalid Telegram authentication'
+          });
+        }
+
+        // Check auth date (must be within 24 hours)
+        const authDate = parseInt(telegramUser.auth_date);
+        const now = Math.floor(Date.now() / 1000);
+        if (now - authDate > 86400) {
+          return res.status(401).json({
+            success: false,
+            error: 'Telegram authentication expired'
+          });
+        }
+      }
+
+      // Check if this Telegram account is already linked to another user
+      const existingTelegramUser = await pool.query(
+        'SELECT wallet_address FROM users WHERE telegram_user_id = $1 AND wallet_address != $2',
+        [telegramUser.id, walletAddress]
+      );
+
+      if (existingTelegramUser.rows.length > 0) {
+        return res.status(400).json({
+          success: false,
+          error: 'This Telegram account is already linked to another user'
+        });
+      }
+
+      // Update user with Telegram info
+      const result = await pool.query(
+        `UPDATE users 
+         SET telegram_user_id = $1,
+             telegram_username = $2,
+             telegram_first_name = $3,
+             telegram_last_name = $4,
+             telegram_photo_url = $5,
+             telegram_connected_at = NOW(),
+             updated_at = NOW()
+         WHERE wallet_address = $6
+         RETURNING *`,
+        [
+          telegramUser.id,
+          telegramUser.username || null,
+          telegramUser.first_name || null,
+          telegramUser.last_name || null,
+          telegramUser.photo_url || null,
+          walletAddress
+        ]
+      );
+
+      if (result.rows.length === 0) {
+        return res.status(404).json({
+          success: false,
+          error: 'User not found'
+        });
+      }
+
+      const updatedUser = result.rows[0];
+
+      console.log('[Auth] Telegram linked successfully for user:', walletAddress);
+
+      res.json({
+        success: true,
+        message: 'Telegram account linked successfully',
+        telegram: {
+          telegramUserId: updatedUser.telegram_user_id,
+          telegramUsername: updatedUser.telegram_username,
+          telegramFirstName: updatedUser.telegram_first_name,
+          telegramLastName: updatedUser.telegram_last_name,
+          telegramPhotoUrl: updatedUser.telegram_photo_url,
+          connectedAt: updatedUser.telegram_connected_at
+        }
+      });
+    } catch (error) {
+      console.error('[Auth] Error linking Telegram:', error);
+      res.status(500).json({
+        success: false,
+        error: error.message
+      });
+    }
+  });
+
+  /**
+   * POST /auth/user/me/unlink-telegram
+   * Unlink Telegram account from authenticated user
+   */
+  router.post('/user/me/unlink-telegram', authenticate, async (req, res) => {
+    try {
+      const walletAddress = req.user.walletAddress;
+
+      console.log('[Auth] Unlinking Telegram for user:', walletAddress);
+
+      // Update user to remove Telegram info
+      const result = await pool.query(
+        `UPDATE users 
+         SET telegram_user_id = NULL,
+             telegram_username = NULL,
+             telegram_first_name = NULL,
+             telegram_last_name = NULL,
+             telegram_photo_url = NULL,
+             telegram_connected_at = NULL,
+             updated_at = NOW()
+         WHERE wallet_address = $1
+         RETURNING *`,
+        [walletAddress]
+      );
+
+      if (result.rows.length === 0) {
+        return res.status(404).json({
+          success: false,
+          error: 'User not found'
+        });
+      }
+
+      console.log('[Auth] Telegram unlinked successfully for user:', walletAddress);
+
+      res.json({
+        success: true,
+        message: 'Telegram account unlinked successfully'
+      });
+    } catch (error) {
+      console.error('[Auth] Error unlinking Telegram:', error);
+      res.status(500).json({
+        success: false,
+        error: error.message
+      });
+    }
+  });
+
+  /**
+   * GET /auth/user/me/telegram
+   * Get Telegram connection status for authenticated user
+   */
+  router.get('/user/me/telegram', authenticate, async (req, res) => {
+    try {
+      const walletAddress = req.user.walletAddress;
+
+      const result = await pool.query(
+        `SELECT telegram_user_id, telegram_username, telegram_first_name, 
+                telegram_last_name, telegram_photo_url, telegram_connected_at
+         FROM users 
+         WHERE wallet_address = $1`,
+        [walletAddress]
+      );
+
+      if (result.rows.length === 0) {
+        return res.status(404).json({
+          success: false,
+          error: 'User not found'
+        });
+      }
+
+      const user = result.rows[0];
+      const isConnected = user.telegram_user_id !== null;
+
+      res.json({
+        connected: isConnected,
+        telegram: isConnected ? {
+          telegramUserId: user.telegram_user_id,
+          telegramUsername: user.telegram_username,
+          telegramFirstName: user.telegram_first_name,
+          telegramLastName: user.telegram_last_name,
+          telegramPhotoUrl: user.telegram_photo_url,
+          connectedAt: user.telegram_connected_at
+        } : undefined
+      });
+    } catch (error) {
+      console.error('[Auth] Error getting Telegram connection:', error);
+      res.status(500).json({
+        success: false,
+        error: error.message
+      });
+    }
+  });
+
+  /**
+   * GET /auth/user/me/telegram-notification-preferences
+   * Get Telegram notification preferences for authenticated user
+   */
+  router.get('/user/me/telegram-notification-preferences', authenticate, async (req, res) => {
+    try {
+      const walletAddress = req.user.walletAddress;
+
+      // Get user ID from wallet address
+      const userResult = await pool.query('SELECT id FROM users WHERE wallet_address = $1', [walletAddress]);
+      if (userResult.rows.length === 0) {
+        return res.status(404).json({ success: false, error: 'User not found' });
+      }
+      const userId = userResult.rows[0].id;
+
+      const result = await pool.query(
+        `SELECT notify_reply, notify_reaction, notify_friend_request, 
+                notify_friend_request_accepted, notify_friend_request_declined, 
+                notify_referral, notify_mention, notify_friend_message,
+                notify_game_joined, notify_game_invite
+         FROM telegram_notification_preferences 
+         WHERE user_id = $1`,
+        [userId]
+      );
+
+      if (result.rows.length === 0) {
+        // Return defaults if no preferences set
+        return res.json({
+          success: true,
+          preferences: {
+            reply: true,
+            reaction: true,
+            friend_request: true,
+            friend_request_accepted: true,
+            friend_request_declined: true,
+            referral: true,
+            mention: true,
+            friend_message: true,
+            game_joined: true,
+            game_invite: true
+          }
+        });
+      }
+
+      const prefs = result.rows[0];
+      res.json({
+        success: true,
+        preferences: {
+          reply: prefs.notify_reply,
+          reaction: prefs.notify_reaction,
+          friend_request: prefs.notify_friend_request,
+          friend_request_accepted: prefs.notify_friend_request_accepted,
+          friend_request_declined: prefs.notify_friend_request_declined,
+          referral: prefs.notify_referral,
+          mention: prefs.notify_mention,
+          friend_message: prefs.notify_friend_message,
+          game_joined: prefs.notify_game_joined,
+          game_invite: prefs.notify_game_invite
+        }
+      });
+    } catch (error) {
+      console.error('[Auth] Error getting Telegram notification preferences:', error);
+      res.status(500).json({
+        success: false,
+        error: error.message
+      });
+    }
+  });
+
+  /**
+   * PUT /auth/user/me/telegram-notification-preferences
+   * Update Telegram notification preferences for authenticated user
+   */
+  router.put('/user/me/telegram-notification-preferences', authenticate, async (req, res) => {
+    try {
+      const walletAddress = req.user.walletAddress;
+      const { preferences } = req.body;
+
+      if (!preferences) {
+        return res.status(400).json({
+          success: false,
+          error: 'Preferences object required'
+        });
+      }
+
+      // Get user ID from wallet address
+      const userResult = await pool.query('SELECT id FROM users WHERE wallet_address = $1', [walletAddress]);
+      if (userResult.rows.length === 0) {
+        return res.status(404).json({ success: false, error: 'User not found' });
+      }
+      const userId = userResult.rows[0].id;
+
+      await pool.query(
+        `INSERT INTO telegram_notification_preferences 
+         (user_id, notify_reply, notify_reaction, notify_friend_request, 
+          notify_friend_request_accepted, notify_friend_request_declined, 
+          notify_referral, notify_mention, notify_friend_message, 
+          notify_game_joined, notify_game_invite, updated_at)
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, NOW())
+         ON CONFLICT (user_id) 
+         DO UPDATE SET 
+           notify_reply = $2,
+           notify_reaction = $3,
+           notify_friend_request = $4,
+           notify_friend_request_accepted = $5,
+           notify_friend_request_declined = $6,
+           notify_referral = $7,
+           notify_mention = $8,
+           notify_friend_message = $9,
+           notify_game_joined = $10,
+           notify_game_invite = $11,
+           updated_at = NOW()`,
+        [
+          userId,
+          preferences.reply !== undefined ? preferences.reply : true,
+          preferences.reaction !== undefined ? preferences.reaction : true,
+          preferences.friend_request !== undefined ? preferences.friend_request : true,
+          preferences.friend_request_accepted !== undefined ? preferences.friend_request_accepted : true,
+          preferences.friend_request_declined !== undefined ? preferences.friend_request_declined : true,
+          preferences.referral !== undefined ? preferences.referral : true,
+          preferences.mention !== undefined ? preferences.mention : true,
+          preferences.friend_message !== undefined ? preferences.friend_message : true,
+          preferences.game_joined !== undefined ? preferences.game_joined : true,
+          preferences.game_invite !== undefined ? preferences.game_invite : true
+        ]
+      );
+
+      res.json({
+        success: true,
+        message: 'Telegram notification preferences updated'
+      });
+    } catch (error) {
+      console.error('[Auth] Error updating Telegram notification preferences:', error);
+      res.status(500).json({
+        success: false,
+        error: error.message
+      });
+    }
+  });
+
+  /**
+   * POST /auth/pending-game/dismiss
+   * Dismiss a pending game deeplink so it never shows again
+   */
+  router.post('/pending-game/dismiss', async (req, res) => {
+    try {
+      const { walletAddress, gameId } = req.body;
+
+      if (!walletAddress || !gameId) {
+        return res.status(400).json({
+          success: false,
+          error: 'walletAddress and gameId are required'
+        });
+      }
+
+      await pool.query(
+        `INSERT INTO pending_game_dismissals (wallet_address, game_id, dismissed_at)
+         VALUES ($1, $2, NOW())
+         ON CONFLICT (wallet_address, game_id) DO NOTHING`,
+        [walletAddress, gameId]
+      );
+
+      console.log(`[Auth] User ${walletAddress} dismissed pending game ${gameId}`);
+
+      res.json({ success: true });
+    } catch (error) {
+      console.error('[Auth] Error dismissing pending game:', error);
+      res.status(500).json({ success: false, error: error.message });
+    }
+  });
+
+  /**
+   * GET /auth/pending-game/dismissed/:walletAddress/:gameId
+   * Check if a pending game was dismissed
+   */
+  router.get('/pending-game/dismissed/:walletAddress/:gameId', async (req, res) => {
+    try {
+      const { walletAddress, gameId } = req.params;
+
+      const result = await pool.query(
+        `SELECT id FROM pending_game_dismissals
+         WHERE wallet_address = $1 AND game_id = $2`,
+        [walletAddress, gameId]
+      );
+
+      res.json({
+        success: true,
+        dismissed: result.rows.length > 0
+      });
+    } catch (error) {
+      console.error('[Auth] Error checking pending game dismissal:', error);
+      res.status(500).json({ success: false, error: error.message });
+    }
+  });
+
+  // ============================================
+  // PUSH NOTIFICATION ROUTES (PWA/Seeker Mode)
+  // ============================================
+
+  /**
+   * GET /auth/vapid-public-key
+   * Get VAPID public key for push subscription (no auth required)
+   */
+  router.get('/vapid-public-key', (req, res) => {
+    const publicKey = getVapidPublicKey();
+    if (!publicKey) {
+      return res.status(503).json({
+        success: false,
+        error: 'Push notifications not configured'
+      });
+    }
+    res.json({
+      success: true,
+      publicKey
+    });
+  });
+
+  /**
+   * POST /auth/user/me/push-subscription
+   * Register a push subscription for authenticated user
+   */
+  router.post('/user/me/push-subscription', authenticate, async (req, res) => {
+    try {
+      const walletAddress = req.user.walletAddress;
+      const { subscription, deviceType } = req.body;
+
+      if (!subscription || !subscription.endpoint || !subscription.keys) {
+        return res.status(400).json({
+          success: false,
+          error: 'Valid subscription object required (endpoint, keys.p256dh, keys.auth)'
+        });
+      }
+
+      // Get user ID from wallet address
+      const userResult = await pool.query('SELECT id FROM users WHERE wallet_address = $1', [walletAddress]);
+      if (userResult.rows.length === 0) {
+        return res.status(404).json({ success: false, error: 'User not found' });
+      }
+      const userId = userResult.rows[0].id;
+
+      // Upsert push subscription
+      await pool.query(
+        `INSERT INTO push_subscriptions
+         (user_id, endpoint, p256dh, auth, device_type, updated_at)
+         VALUES ($1, $2, $3, $4, $5, NOW())
+         ON CONFLICT (user_id, endpoint)
+         DO UPDATE SET
+           p256dh = $3,
+           auth = $4,
+           device_type = $5,
+           updated_at = NOW()`,
+        [
+          userId,
+          subscription.endpoint,
+          subscription.keys.p256dh,
+          subscription.keys.auth,
+          deviceType || 'android_pwa'
+        ]
+      );
+
+      // Create default notification preferences if they don't exist
+      await pool.query(
+        `INSERT INTO push_notification_preferences (user_id)
+         VALUES ($1)
+         ON CONFLICT (user_id) DO NOTHING`,
+        [userId]
+      );
+
+      console.log(`[Auth] Push subscription registered for user ${walletAddress} (${deviceType || 'android_pwa'})`);
+
+      res.json({
+        success: true,
+        message: 'Push subscription registered'
+      });
+    } catch (error) {
+      console.error('[Auth] Error registering push subscription:', error);
+      res.status(500).json({
+        success: false,
+        error: error.message
+      });
+    }
+  });
+
+  /**
+   * DELETE /auth/user/me/push-subscription
+   * Remove a push subscription for authenticated user
+   */
+  router.delete('/user/me/push-subscription', authenticate, async (req, res) => {
+    try {
+      const walletAddress = req.user.walletAddress;
+      const { endpoint } = req.body;
+
+      if (!endpoint) {
+        return res.status(400).json({
+          success: false,
+          error: 'Endpoint required'
+        });
+      }
+
+      // Get user ID from wallet address
+      const userResult = await pool.query('SELECT id FROM users WHERE wallet_address = $1', [walletAddress]);
+      if (userResult.rows.length === 0) {
+        return res.status(404).json({ success: false, error: 'User not found' });
+      }
+      const userId = userResult.rows[0].id;
+
+      const result = await pool.query(
+        'DELETE FROM push_subscriptions WHERE user_id = $1 AND endpoint = $2',
+        [userId, endpoint]
+      );
+
+      console.log(`[Auth] Push subscription removed for user ${walletAddress}`);
+
+      res.json({
+        success: true,
+        message: 'Push subscription removed',
+        deleted: result.rowCount > 0
+      });
+    } catch (error) {
+      console.error('[Auth] Error removing push subscription:', error);
+      res.status(500).json({
+        success: false,
+        error: error.message
+      });
+    }
+  });
+
+  /**
+   * GET /auth/user/me/push-subscription
+   * Get push subscription status for authenticated user
+   */
+  router.get('/user/me/push-subscription', authenticate, async (req, res) => {
+    try {
+      const walletAddress = req.user.walletAddress;
+
+      // Get user ID from wallet address
+      const userResult = await pool.query('SELECT id FROM users WHERE wallet_address = $1', [walletAddress]);
+      if (userResult.rows.length === 0) {
+        return res.status(404).json({ success: false, error: 'User not found' });
+      }
+      const userId = userResult.rows[0].id;
+
+      const result = await pool.query(
+        'SELECT device_type, created_at FROM push_subscriptions WHERE user_id = $1',
+        [userId]
+      );
+
+      res.json({
+        success: true,
+        hasSubscription: result.rows.length > 0,
+        subscriptions: result.rows.map(row => ({
+          deviceType: row.device_type,
+          createdAt: row.created_at
+        }))
+      });
+    } catch (error) {
+      console.error('[Auth] Error getting push subscription status:', error);
+      res.status(500).json({
+        success: false,
+        error: error.message
+      });
+    }
+  });
+
+  /**
+   * GET /auth/user/me/push-notification-preferences
+   * Get push notification preferences for authenticated user
+   */
+  router.get('/user/me/push-notification-preferences', authenticate, async (req, res) => {
+    try {
+      const walletAddress = req.user.walletAddress;
+
+      // Get user ID from wallet address
+      const userResult = await pool.query('SELECT id FROM users WHERE wallet_address = $1', [walletAddress]);
+      if (userResult.rows.length === 0) {
+        return res.status(404).json({ success: false, error: 'User not found' });
+      }
+      const userId = userResult.rows[0].id;
+
+      const result = await pool.query(
+        `SELECT notify_reply, notify_reaction, notify_friend_request,
+                notify_friend_request_accepted, notify_friend_request_declined,
+                notify_referral, notify_mention, notify_friend_message,
+                notify_game_joined, notify_game_invite
+         FROM push_notification_preferences
+         WHERE user_id = $1`,
+        [userId]
+      );
+
+      if (result.rows.length === 0) {
+        // Return defaults if no preferences set
+        return res.json({
+          success: true,
+          preferences: {
+            reply: true,
+            reaction: true,
+            friend_request: true,
+            friend_request_accepted: true,
+            friend_request_declined: true,
+            referral: true,
+            mention: true,
+            friend_message: true,
+            game_joined: true,
+            game_invite: true
+          }
+        });
+      }
+
+      const prefs = result.rows[0];
+      res.json({
+        success: true,
+        preferences: {
+          reply: prefs.notify_reply,
+          reaction: prefs.notify_reaction,
+          friend_request: prefs.notify_friend_request,
+          friend_request_accepted: prefs.notify_friend_request_accepted,
+          friend_request_declined: prefs.notify_friend_request_declined,
+          referral: prefs.notify_referral,
+          mention: prefs.notify_mention,
+          friend_message: prefs.notify_friend_message,
+          game_joined: prefs.notify_game_joined,
+          game_invite: prefs.notify_game_invite
+        }
+      });
+    } catch (error) {
+      console.error('[Auth] Error getting push notification preferences:', error);
+      res.status(500).json({
+        success: false,
+        error: error.message
+      });
+    }
+  });
+
+  /**
+   * PUT /auth/user/me/push-notification-preferences
+   * Update push notification preferences for authenticated user
+   */
+  router.put('/user/me/push-notification-preferences', authenticate, async (req, res) => {
+    try {
+      const walletAddress = req.user.walletAddress;
+      const { preferences } = req.body;
+
+      if (!preferences) {
+        return res.status(400).json({
+          success: false,
+          error: 'Preferences object required'
+        });
+      }
+
+      // Get user ID from wallet address
+      const userResult = await pool.query('SELECT id FROM users WHERE wallet_address = $1', [walletAddress]);
+      if (userResult.rows.length === 0) {
+        return res.status(404).json({ success: false, error: 'User not found' });
+      }
+      const userId = userResult.rows[0].id;
+
+      await pool.query(
+        `INSERT INTO push_notification_preferences
+         (user_id, notify_reply, notify_reaction, notify_friend_request,
+          notify_friend_request_accepted, notify_friend_request_declined,
+          notify_referral, notify_mention, notify_friend_message,
+          notify_game_joined, notify_game_invite, updated_at)
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, NOW())
+         ON CONFLICT (user_id)
+         DO UPDATE SET
+           notify_reply = $2,
+           notify_reaction = $3,
+           notify_friend_request = $4,
+           notify_friend_request_accepted = $5,
+           notify_friend_request_declined = $6,
+           notify_referral = $7,
+           notify_mention = $8,
+           notify_friend_message = $9,
+           notify_game_joined = $10,
+           notify_game_invite = $11,
+           updated_at = NOW()`,
+        [
+          userId,
+          preferences.reply !== undefined ? preferences.reply : true,
+          preferences.reaction !== undefined ? preferences.reaction : true,
+          preferences.friend_request !== undefined ? preferences.friend_request : true,
+          preferences.friend_request_accepted !== undefined ? preferences.friend_request_accepted : true,
+          preferences.friend_request_declined !== undefined ? preferences.friend_request_declined : true,
+          preferences.referral !== undefined ? preferences.referral : true,
+          preferences.mention !== undefined ? preferences.mention : true,
+          preferences.friend_message !== undefined ? preferences.friend_message : true,
+          preferences.game_joined !== undefined ? preferences.game_joined : true,
+          preferences.game_invite !== undefined ? preferences.game_invite : true
+        ]
+      );
+
+      res.json({
+        success: true,
+        message: 'Push notification preferences updated'
+      });
+    } catch (error) {
+      console.error('[Auth] Error updating push notification preferences:', error);
+      res.status(500).json({
+        success: false,
+        error: error.message
+      });
+    }
+  });
+
+  return router;
+};
+