MotorSignal-App/docs/archive/2026-08/phase-2/firebase-setup.md

MotorSignal — Phase 2B Firebase Cloud Setup & Security Rules

Document Version: 1.0.0
Phase: Phase 2B — Firebase Cloud Sync & Remote Ride Backup
Status: SPECIFICATION & DEPLOYMENT INSTRUCTIONS

---

1. Overview

MotorSignal utilizes Firebase Cloud Firestore (for structured ride summaries and aggregates) and Firebase Cloud Storage (for compressed 20Hz forensic telemetry bundles).

All client synchronization adheres strictly to:

1. User Isolation: All cloud assets are namespaced under the authenticated user's ID (/users/{uid}/...).
2. Offline-First Downstream Sync: Riding, recording, and local SQLite persistence never require cloud connectivity or authentication.
3. No Secret Embedding: Client apps rely purely on platform configuration files (google-services.json for Android, GoogleService-Info.plist for iOS).

---

2. Cloud Firestore Security Rules

Deploy the following security rules to Firebase Cloud Firestore:

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    
    // User Profile Documents
    match /users/{userId} {
      allow read, write: if request.auth != null && request.auth.uid == userId;
      
      // Ride Summaries and Metadata
      match /rides/{remoteRideId} {
        allow read, write: if request.auth != null && request.auth.uid == userId;
        
        // Discrete Events & Performance Benchmarks Subcollections
        match /{allSubcollections=**} {
          allow read, write: if request.auth != null && request.auth.uid == userId;
        }
      }
    }
  }
}

Security Enforcement:

• Authenticated users can only read and write documents within /users/{request.auth.uid}/.
• Unauthenticated requests are rejected immediately at the Firebase gateway.
• Cross-user reading or writing is blocked.

---

3. Firebase Cloud Storage Security Rules

Deploy the following security rules to Firebase Cloud Storage:

rules_version = '2';
service firebase.storage {
  match /b/{bucket}/o {
    
    // User-Isolated Forensic Telemetry Bundles
    match /users/{userId}/rides/{remoteRideId}/{allPaths=**} {
      allow read, write: if request.auth != null && request.auth.uid == userId;
    }
  }
}

Storage Protection:

• Bundles uploaded to users/{uid}/rides/{remoteRideId}/telemetry.zip are restricted solely to the owner.
• Multi-part and resumable chunked uploads require active authentication tokens.

---

4. Required Firebase Console Setup Steps

Before testing live cloud synchronization with a real Firebase project:

1. Create Firebase Project:
   • Navigate to the Firebase Console.
   • Create a new project (e.g. motorsignal-app).
2. Enable Authentication Providers:
   • Under Build > Authentication > Sign-in method:
     • Enable Email/Password.
     • Enable Google (Configure OAuth Web Client ID and SHA-1 fingerprint for Android).
     • Enable Anonymous (optional for guest linking).
3. Provision Cloud Firestore:
   • Under Build > Firestore Database, click Create Database.
   • Select a region and apply the security rules above.
4. Provision Firebase Storage:
   • Under Build > Storage, click Get Started.
   • Select the default bucket and apply the storage security rules above.
5. Download Platform Configurations:
   • Android: Register com.example.motorcycle_dash (or production package name), download google-services.json, and place it in android/app/.
   • iOS: Register bundle ID, download GoogleService-Info.plist, and place it in ios/Runner/.
   • (Note: Configuration files are gitignored to prevent secret leaks).