bulltrackers-module 1.0.597 → 1.0.598

package/functions/api-v2/helpers/data-fetchers/firestore.js

@@ -519,6 +519,59 @@ const fetchUserVerificationData = async (firestore, userId) => {
     }
 };
 
+/**
+ * Lookup CID by email (server-side only for security)
+ * Searches through all SignedInUsers verification documents to find matching email
+ * Returns only the CID and basic verification status - no email exposure
+ */
+const lookupCidByEmail = async (firestore, userEmail) => {
+    if (!userEmail) {
+        throw new Error('Email is required for lookup');
+    }
+    
+    try {
+        // Normalize email for comparison
+        const normalizedEmail = String(userEmail).toLowerCase().trim();
+        
+        // Get all SignedInUsers documents
+        const signedInUsersSnapshot = await firestore.collection('SignedInUsers').get();
+        
+        // Search through each CID's verification document
+        for (const userDoc of signedInUsersSnapshot.docs) {
+            const verificationRef = userDoc.ref.collection('verification').doc('data');
+            const verificationDoc = await verificationRef.get();
+            
+            if (verificationDoc.exists()) {
+                const verificationData = verificationDoc.data();
+                const emails = Array.isArray(verificationData.email) 
+                    ? verificationData.email 
+                    : (verificationData.email ? [verificationData.email] : []);
+                
+                // Case-insensitive email comparison
+                const normalizedEmails = emails.map(e => String(e).toLowerCase().trim());
+                if (normalizedEmails.includes(normalizedEmail)) {
+                    // Found match - return only CID and verification status (no email)
+                    return {
+                        cid: verificationData.etoroCID || Number(userDoc.id),
+                        accountSetupComplete: verificationData.accountSetupComplete || false,
+                        etoroUsername: verificationData.etoroUsername,
+                        displayName: verificationData.displayName,
+                        photoURL: verificationData.photoURL,
+                        verifiedAt: verificationData.verifiedAt,
+                        setupCompletedAt: verificationData.setupCompletedAt,
+                    };
+                }
+            }
+        }
+        
+        // No match found
+        return null;
+    } catch (error) {
+        console.error(`Error looking up CID by email: ${error}`);
+        throw error;
+    }
+};
+
 
 // 7. PI addition requests fetcher
 // This is used to allow the user to request new PIs to add to the popular investor list to process data each day.
@@ -2244,6 +2297,7 @@ module.exports = {
     pageCollection,
     fetchPopularInvestorMasterList,
     isDeveloper,
+    lookupCidByEmail,
     manageUserWatchlist,
     fetchUserVerificationData,
     requestPopularInvestorAddition,

package/functions/api-v2/middleware/FIREBASE_AUTH_EXPLANATION.md

@@ -0,0 +1,141 @@
+# Firebase Auth Token Verification - How It Works
+
+## Overview
+
+This middleware verifies Firebase Authentication ID tokens server-side to securely extract user information (like email) without relying on client-provided data.
+
+## Why This Is Important
+
+**Without token verification:**
+- Client sends email as query parameter: `GET /verification/lookup?email=user@example.com`
+- Anyone could call this with any email address
+- No way to verify the email actually belongs to the authenticated user
+
+**With token verification:**
+- Client sends Firebase ID token: `Authorization: Bearer <token>`
+- Server verifies the token is valid and not expired
+- Server extracts email from the verified token (cannot be spoofed)
+- Only the authenticated user's email can be used
+
+## How It Works
+
+### 1. Frontend (Client-Side)
+
+```typescript
+// User signs in with Firebase Auth
+const user = await signInWithPopup(auth, googleProvider);
+
+// Get the ID token (this is a JWT signed by Firebase)
+const idToken = await user.getIdToken();
+
+// Send token in Authorization header
+fetch('/verification/lookup', {
+  headers: {
+    'Authorization': `Bearer ${idToken}`
+  }
+});
+```
+
+### 2. Backend (Server-Side)
+
+```javascript
+// Middleware verifies the token
+const decodedToken = await admin.auth().verifyIdToken(token);
+
+// Extract email from verified token
+const email = decodedToken.email; // This is guaranteed to be correct
+
+// Use email for lookup
+const result = await lookupCidByEmail(db, email);
+```
+
+## Token Structure
+
+Firebase ID tokens are JWTs (JSON Web Tokens) that contain:
+- `uid`: User's Firebase UID
+- `email`: User's email address
+- `email_verified`: Whether email is verified
+- `name`: User's display name
+- `picture`: User's profile picture URL
+- `exp`: Expiration timestamp
+- `iat`: Issued at timestamp
+
+The token is **cryptographically signed by Firebase**, so:
+- ✅ Cannot be forged
+- ✅ Cannot be modified
+- ✅ Expires automatically (1 hour default)
+- ✅ Can be verified server-side
+
+## Security Benefits
+
+1. **Prevents Email Spoofing**: Users cannot lookup other users' data by providing a different email
+2. **Automatic Expiration**: Tokens expire after 1 hour, requiring re-authentication
+3. **Cryptographic Verification**: Token signature is verified against Firebase's public keys
+4. **No Client Trust**: Server doesn't trust client-provided data, only verified tokens
+
+## Usage
+
+### In Routes
+
+```javascript
+const { requireFirebaseAuth } = require('../middleware/firebase_auth_middleware.js');
+
+// Require authentication
+router.get('/lookup', requireFirebaseAuth, async (req, res) => {
+  // req.firebaseUser.email is guaranteed to be from verified token
+  const email = req.firebaseUser.email;
+  // ... use email securely
+});
+```
+
+### Optional Auth (for public routes)
+
+```javascript
+const { verifyFirebaseToken } = require('../middleware/firebase_auth_middleware.js');
+
+// Optional authentication
+router.get('/public', verifyFirebaseToken, async (req, res) => {
+  if (req.firebaseUser) {
+    // User is authenticated
+  } else {
+    // Public access
+  }
+});
+```
+
+## Firebase Admin SDK Setup
+
+The middleware automatically initializes Firebase Admin using:
+1. **Cloud Functions**: Uses the function's service account automatically
+2. **Local Development**: Uses `GOOGLE_APPLICATION_CREDENTIALS` environment variable
+3. **Default Credentials**: Falls back to Application Default Credentials (ADC)
+
+No manual configuration needed in Cloud Functions - it "just works"!
+
+## Error Handling
+
+- **Missing Token**: `req.firebaseUser` is `null`, request continues (routes can check)
+- **Invalid Token**: `req.firebaseUser` is `null`, request continues
+- **Expired Token**: `req.firebaseUser` is `null`, request continues
+- **Required Auth**: `requireFirebaseAuth` returns 401 if token is invalid/missing
+
+## Token Refresh
+
+Firebase tokens expire after 1 hour. The frontend automatically refreshes tokens:
+- Firebase SDK handles token refresh automatically
+- `getIdToken()` always returns a valid token (refreshes if needed)
+- No manual refresh logic needed
+
+## Example Flow
+
+```
+1. User signs in → Firebase Auth creates session
+2. Frontend calls getIdToken() → Gets current ID token
+3. Frontend sends token in Authorization header
+4. Backend middleware verifies token with Firebase Admin
+5. Backend extracts email from verified token
+6. Backend uses email for secure lookup
+7. Backend returns result (no email exposure)
+```
+
+This ensures the email used for lookup is **always** the authenticated user's email, with cryptographic proof.

package/functions/api-v2/middleware/firebase_auth_middleware.js

@@ -0,0 +1,132 @@
+/**
+ * @fileoverview Firebase Auth Token Verification Middleware
+ * Verifies Firebase ID tokens and extracts user information
+ */
+
+// Firebase Admin SDK is used server-side to verify tokens
+// Note: This requires firebase-admin to be installed
+let admin = null;
+try {
+    admin = require('firebase-admin');
+} catch (e) {
+    console.warn('[FirebaseAuth] firebase-admin not available. Token verification will be disabled.');
+}
+
+/**
+ * Initialize Firebase Admin if not already initialized
+ */
+function initializeFirebaseAdmin() {
+    if (!admin) {
+        return null;
+    }
+    
+    try {
+        // Check if already initialized
+        if (admin.apps.length > 0) {
+            return admin.app();
+        }
+        
+        // Initialize with default credentials (uses GOOGLE_APPLICATION_CREDENTIALS or default service account)
+        // In Cloud Functions, this automatically uses the function's service account
+        admin.initializeApp({
+            // Credentials are automatically loaded from environment
+            projectId: process.env.GCP_PROJECT_ID || 'stocks-12345'
+        });
+        
+        return admin.app();
+    } catch (error) {
+        // If already initialized, that's fine
+        if (error.code === 'app/already-initialized') {
+            return admin.app();
+        }
+        console.error('[FirebaseAuth] Error initializing Firebase Admin:', error);
+        return null;
+    }
+}
+
+/**
+ * Middleware to verify Firebase Auth ID token
+ * Extracts email and UID from verified token and attaches to req.firebaseUser
+ * 
+ * Usage:
+ *   router.use('/protected-route', verifyFirebaseToken);
+ *   // Then access req.firebaseUser.email and req.firebaseUser.uid
+ */
+const verifyFirebaseToken = async (req, res, next) => {
+    // Skip if Firebase Admin is not available
+    if (!admin) {
+        return next();
+    }
+    
+    try {
+        // Get token from Authorization header
+        // Format: "Bearer <token>" or just "<token>"
+        const authHeader = req.headers.authorization;
+        
+        if (!authHeader) {
+            // No token provided - continue without setting req.firebaseUser
+            // Routes can check for req.firebaseUser to determine if auth is required
+            return next();
+        }
+        
+        // Extract token (handle both "Bearer <token>" and just "<token>" formats)
+        const token = authHeader.startsWith('Bearer ') 
+            ? authHeader.substring(7) 
+            : authHeader;
+        
+        if (!token || token === 'null' || token === 'undefined') {
+            return next();
+        }
+        
+        // Initialize Firebase Admin if needed
+        const app = initializeFirebaseAdmin();
+        if (!app) {
+            console.warn('[FirebaseAuth] Cannot verify token - Firebase Admin not initialized');
+            return next();
+        }
+        
+        // Verify the token
+        const decodedToken = await admin.auth().verifyIdToken(token);
+        
+        // Attach user info to request
+        req.firebaseUser = {
+            uid: decodedToken.uid,
+            email: decodedToken.email,
+            emailVerified: decodedToken.email_verified || false,
+            name: decodedToken.name,
+            picture: decodedToken.picture,
+        };
+        
+        next();
+    } catch (error) {
+        // Token verification failed
+        // Don't block the request - let individual routes decide if auth is required
+        console.warn('[FirebaseAuth] Token verification failed:', error.message);
+        req.firebaseUser = null;
+        next();
+    }
+};
+
+/**
+ * Middleware that REQUIRES authentication
+ * Returns 401 if token is invalid or missing
+ */
+const requireFirebaseAuth = async (req, res, next) => {
+    // First verify the token
+    await verifyFirebaseToken(req, res, () => {
+        // Check if user was authenticated
+        if (!req.firebaseUser || !req.firebaseUser.email) {
+            return res.status(401).json({ 
+                success: false, 
+                error: 'Authentication required. Please provide a valid Firebase ID token.' 
+            });
+        }
+        next();
+    });
+};
+
+module.exports = {
+    verifyFirebaseToken,
+    requireFirebaseAuth,
+    initializeFirebaseAdmin,
+};

package/functions/api-v2/routes/verification.js

@@ -1,8 +1,43 @@
 const express = require('express');
-const { initiateVerification, finalizeVerification, fetchUserVerificationData } = require('../helpers/data-fetchers/firestore.js');
+const { initiateVerification, finalizeVerification, fetchUserVerificationData, lookupCidByEmail } = require('../helpers/data-fetchers/firestore.js');
+const { requireFirebaseAuth } = require('../middleware/firebase_auth_middleware.js');
 
 const router = express.Router();
 
+// GET /verification/lookup
+// Server-side email-to-CID lookup (prevents exposing other users' emails to client)
+// Requires Firebase Auth token in Authorization header: "Bearer <token>"
+// Email is extracted from the verified token (secure - cannot be spoofed)
+router.get('/lookup', requireFirebaseAuth, async (req, res) => {
+    try {
+        const { db } = req.dependencies;
+        
+        // Get email from verified Firebase token (secure - cannot be spoofed)
+        const userEmail = req.firebaseUser?.email;
+        
+        if (!userEmail) {
+            return res.status(400).json({ 
+                success: false, 
+                error: 'Email not found in authentication token' 
+            });
+        }
+        
+        const result = await lookupCidByEmail(db, userEmail);
+        
+        if (result) {
+            res.json({ success: true, data: result });
+        } else {
+            res.status(200).json({ 
+                success: false, 
+                message: 'No verification data found for this email' 
+            });
+        }
+    } catch (error) {
+        console.error('[Verification Lookup] Error:', error);
+        res.status(500).json({ success: false, error: error.message });
+    }
+});
+
 // GET /verification/status
 router.get('/status', async (req, res) => {
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bulltrackers-module",
-  "version": "1.0.597",
+  "version": "1.0.598",
   "description": "Helper Functions for Bulltrackers.",
   "main": "index.js",
   "files": [