diff --git a/.gitignore b/.gitignore index 276272f4..fe2f3c6d 100644 --- a/.gitignore +++ b/.gitignore @@ -48,4 +48,10 @@ yarn-error.* ServiceAccountBitSleuthWallet.json # Prevent accidentally committing local absolute paths -Users/ \ No newline at end of file +Users/ + +# Firebase configuration files (use .example files as templates) +google-services.json +GoogleService-Info.plist +android/app/google-services.json +ios/BitSleuthWallet/GoogleService-Info.plist \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 72c73f7e..3a3b994b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -149,12 +149,19 @@ touch docs/NEW_FEATURE_GUIDE.md cd ios && pod install && cd .. ``` -4. Start the development server: +4. **Set up Firebase configuration** (Required): + - You must create your own Firebase project before running the app + - See [docs/FIREBASE_SETUP.md](docs/FIREBASE_SETUP.md) for complete instructions + - Download `google-services.json` and `GoogleService-Info.plist` from your Firebase project + - Place them in the required locations (see setup guide) + - **Important**: These files are in `.gitignore` and should never be committed + +5. Start the development server: ```bash npm start ``` -5. Run on a device/simulator: +6. Run on a device/simulator: ```bash npm run ios # iOS npm run android # Android @@ -202,6 +209,7 @@ Before submitting a PR, make sure to: ### Security - **Never commit secrets**: No API keys, private keys, or sensitive data +- **Firebase Configuration**: Never commit `google-services.json` or `GoogleService-Info.plist` (they're in `.gitignore`) - **Private Keys**: All key management must remain client-side - **Review Changes**: Security-sensitive changes require thorough review - **Vulnerability Reporting**: Report security issues via our [Security Policy](SECURITY.md), not in public issues diff --git a/GoogleService-Info.example.plist b/GoogleService-Info.example.plist new file mode 100644 index 00000000..91963e89 --- /dev/null +++ b/GoogleService-Info.example.plist @@ -0,0 +1,43 @@ + + + + + + API_KEY + AIzaSy_YOUR_IOS_API_KEY_HERE + GCM_SENDER_ID + YOUR_PROJECT_NUMBER + PLIST_VERSION + 1 + BUNDLE_ID + ai.bitsleuth.wallet + PROJECT_ID + your-project-id + STORAGE_BUCKET + your-project-id.appspot.com + IS_ADS_ENABLED + + IS_ANALYTICS_ENABLED + + IS_APPINVITE_ENABLED + + IS_GCM_ENABLED + + IS_SIGNIN_ENABLED + + GOOGLE_APP_ID + 1:YOUR_PROJECT_NUMBER:ios:YOUR_APP_ID + + \ No newline at end of file diff --git a/GoogleService-Info.plist b/GoogleService-Info.plist deleted file mode 100644 index d95f3870..00000000 --- a/GoogleService-Info.plist +++ /dev/null @@ -1,30 +0,0 @@ - - - - - API_KEY - AIzaSyDnlFxwXvMa7Kfeycf_uj6v_YKMmggwc5g - GCM_SENDER_ID - 510465233305 - PLIST_VERSION - 1 - BUNDLE_ID - ai.bitsleuth.wallet - PROJECT_ID - bitsleuth - STORAGE_BUCKET - bitsleuth.firebasestorage.app - IS_ADS_ENABLED - - IS_ANALYTICS_ENABLED - - IS_APPINVITE_ENABLED - - IS_GCM_ENABLED - - IS_SIGNIN_ENABLED - - GOOGLE_APP_ID - 1:510465233305:ios:54dffa80d37d853185c308 - - \ No newline at end of file diff --git a/README.md b/README.md index 08bc1105..026fe946 100644 --- a/README.md +++ b/README.md @@ -162,12 +162,18 @@ BitSleuth Wallet is a client-side Bitcoin wallet built with React Native and Exp - **Testing**: Expo Go app or configured simulator/emulator ### Firebase Setup (Required) + +**Each developer must configure their own Firebase project.** See [docs/FIREBASE_SETUP.md](docs/FIREBASE_SETUP.md) for detailed instructions. + +Required: - Firebase project with iOS and Android apps configured -- `google-services.json` (Android) in `android/app/` -- `GoogleService-Info.plist` (iOS) in `ios/BitSleuthWallet/` +- `google-services.json` (Android) in `android/app/` and root directory +- `GoogleService-Info.plist` (iOS) in `ios/BitSleuthWallet/` and root directory - **Firebase Services enabled**: Crashlytics (with Release Monitoring), Performance Monitoring - **Firebase Analytics DISABLED** for privacy (explicitly configured) +**Note**: Configuration files are in `.gitignore` and should never be committed to the repository. + --- ## 🚀 Getting Started @@ -192,10 +198,20 @@ cd ios && pod install && cd .. ### 2. Firebase Configuration -Ensure you have the required Firebase configuration files: +**You must set up your own Firebase project** before running the app. Configuration files are not included in this repository for security reasons. + +📖 **See [docs/FIREBASE_SETUP.md](docs/FIREBASE_SETUP.md) for complete setup instructions.** -- **Android**: Place `google-services.json` in `android/app/` -- **iOS**: Place `GoogleService-Info.plist` in `ios/BitSleuthWallet/` +Quick summary: +1. Create a Firebase project at [console.firebase.google.com](https://console.firebase.google.com/) +2. Add iOS and Android apps to your project +3. Download `google-services.json` (Android) and place it in: + - `android/app/google-services.json` + - `google-services.json` (root) +4. Download `GoogleService-Info.plist` (iOS) and place it in: + - `ios/BitSleuthWallet/GoogleService-Info.plist` + - `GoogleService-Info.plist` (root) +5. Enable Crashlytics and Performance Monitoring in Firebase Console ⚠️ **Important**: Firebase Analytics is **prohibited** for privacy reasons. Only Crashlytics (with Release Monitoring) and Performance Monitoring are enabled. See [docs/FIREBASE_INTEGRATION.md](docs/FIREBASE_INTEGRATION.md) for details. diff --git a/SECURITY.md b/SECURITY.md index e3311082..34fec1f6 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -44,6 +44,18 @@ BitSleuth Wallet is designed with security as a top priority: - **Biometric/PIN Protection**: Device-level authentication required - **Open Source**: Our code is publicly auditable - **No Analytics**: We don't track user behavior or collect personal data +- **Firebase API Keys**: Configuration files are excluded from the repository (see [docs/FIREBASE_SETUP.md](docs/FIREBASE_SETUP.md)) + +### Firebase Configuration Security + +This repository does **not** include Firebase configuration files (`google-services.json` and `GoogleService-Info.plist`) for security reasons: + +- **Each developer must use their own Firebase project** for development +- Configuration files contain API keys that, while designed for client use, should not be publicly exposed in repositories +- Example template files are provided for reference +- See [docs/FIREBASE_SETUP.md](docs/FIREBASE_SETUP.md) for complete setup instructions and security best practices + +**Important**: If you find actual Firebase configuration files (not `.example` files) committed to this repository, please report it as a security issue. ### Scope @@ -53,6 +65,8 @@ Security issues in scope: - Data exposure or privacy leaks - Transaction manipulation or double-spending risks - Dependency vulnerabilities in critical packages +- Exposed Firebase configuration files or API keys in the repository +- Misconfigured Firebase security rules Out of scope: - Social engineering attacks diff --git a/android/app/PLACE_GOOGLE_SERVICES_HERE.md b/android/app/PLACE_GOOGLE_SERVICES_HERE.md new file mode 100644 index 00000000..df3652cf --- /dev/null +++ b/android/app/PLACE_GOOGLE_SERVICES_HERE.md @@ -0,0 +1,21 @@ +# Firebase Configuration Required + +Place your `google-services.json` file in this directory. + +## Quick Setup + +1. Create a Firebase project at https://console.firebase.google.com/ +2. Add an Android app with package name: `ai.bitsleuth.wallet` +3. Download `google-services.json` +4. Place it here: `android/app/google-services.json` +5. Also place a copy in the root directory: `google-services.json` + +## Complete Guide + +See [docs/FIREBASE_SETUP.md](../../docs/FIREBASE_SETUP.md) for detailed instructions. + +## Example File + +An example configuration is available at: `android/app/google-services.example.json` + +**Note**: Never commit your actual `google-services.json` file to version control. It's in `.gitignore` for your protection. diff --git a/android/app/google-services.example.json b/android/app/google-services.example.json new file mode 100644 index 00000000..5c769366 --- /dev/null +++ b/android/app/google-services.example.json @@ -0,0 +1,31 @@ +{ + "_comment": "This is an EXAMPLE file. Replace with your own google-services.json from Firebase Console.", + "_instructions": "1. Go to https://console.firebase.google.com/ 2. Create/select your project 3. Add Android app 4. Download google-services.json 5. Replace this file", + "project_info": { + "project_number": "YOUR_PROJECT_NUMBER", + "project_id": "your-project-id", + "storage_bucket": "your-project-id.appspot.com" + }, + "client": [ + { + "client_info": { + "mobilesdk_app_id": "1:YOUR_PROJECT_NUMBER:android:YOUR_APP_ID", + "android_client_info": { + "package_name": "ai.bitsleuth.wallet" + } + }, + "oauth_client": [], + "api_key": [ + { + "current_key": "AIzaSy_YOUR_ANDROID_API_KEY_HERE" + } + ], + "services": { + "appinvite_service": { + "other_platform_oauth_client": [] + } + } + } + ], + "configuration_version": "1" +} \ No newline at end of file diff --git a/android/app/google-services.json b/android/app/google-services.json deleted file mode 100644 index 8c68de5c..00000000 --- a/android/app/google-services.json +++ /dev/null @@ -1,29 +0,0 @@ -{ - "project_info": { - "project_number": "510465233305", - "project_id": "bitsleuth", - "storage_bucket": "bitsleuth.firebasestorage.app" - }, - "client": [ - { - "client_info": { - "mobilesdk_app_id": "1:510465233305:android:17c91346ecafeaaf85c308", - "android_client_info": { - "package_name": "ai.bitsleuth.wallet" - } - }, - "oauth_client": [], - "api_key": [ - { - "current_key": "AIzaSyBCpQwAvY3MyN-OCYvMlJqbInohHSJpgfg" - } - ], - "services": { - "appinvite_service": { - "other_platform_oauth_client": [] - } - } - } - ], - "configuration_version": "1" -} \ No newline at end of file diff --git a/docs/FIREBASE_CONFIG_README.md b/docs/FIREBASE_CONFIG_README.md new file mode 100644 index 00000000..705099b0 --- /dev/null +++ b/docs/FIREBASE_CONFIG_README.md @@ -0,0 +1,61 @@ +# Firebase Configuration Files - Examples + +This directory contains example Firebase configuration files. **These are templates only** and should not be used in production. + +## Files + +- `google-services.example.json` - Example Android Firebase configuration +- `GoogleService-Info.example.plist` - Example iOS Firebase configuration + +## Setup Instructions + +**You must create your own Firebase project and download your own configuration files.** + +### Quick Setup + +1. Create a Firebase project at [Firebase Console](https://console.firebase.google.com/) +2. Add iOS and Android apps with the bundle ID `ai.bitsleuth.wallet` +3. Download your configuration files: + - `google-services.json` for Android + - `GoogleService-Info.plist` for iOS +4. Place them in the correct locations: + - `google-services.json` → `android/app/google-services.json` (and root directory) + - `GoogleService-Info.plist` → `ios/BitSleuthWallet/GoogleService-Info.plist` (and root directory) + +### Complete Setup Guide + +For detailed instructions, including: +- Firebase service configuration +- API key security and restrictions +- App Check setup +- Troubleshooting +- EAS Build configuration + +See: **[docs/FIREBASE_SETUP.md](docs/FIREBASE_SETUP.md)** + +## Security Note + +The configuration files contain Firebase API keys. While these keys are designed for client-side use, they should still be handled with care: + +- ✅ Use your own Firebase project for development +- ✅ Implement proper Firebase security rules +- ✅ Restrict API keys in Google Cloud Console +- ✅ Enable App Check for production +- ❌ **Never commit your actual configuration files to public repositories** + +The actual configuration files are in `.gitignore` to prevent accidental commits. + +## Why Not Include Configuration Files? + +For open-source projects like BitSleuth Wallet, we follow security best practices: + +1. **Prevent Project Enumeration**: Keeping config files private makes it harder for attackers to find and target the Firebase project +2. **Encourage Proper Setup**: Each developer should use their own Firebase project for development +3. **Avoid Abuse**: Even with proper security rules, exposed API keys can lead to quota abuse +4. **Industry Standard**: Most open-source projects with Firebase integration use this approach + +## Need Help? + +- 📖 Read the complete guide: [docs/FIREBASE_SETUP.md](docs/FIREBASE_SETUP.md) +- 🔧 Firebase Integration details: [docs/FIREBASE_INTEGRATION.md](docs/FIREBASE_INTEGRATION.md) +- 🐛 Open an issue if you encounter problems (don't share your actual API keys!) diff --git a/docs/FIREBASE_CONFIG_REMOVAL_SUMMARY.md b/docs/FIREBASE_CONFIG_REMOVAL_SUMMARY.md new file mode 100644 index 00000000..c99c6a0d --- /dev/null +++ b/docs/FIREBASE_CONFIG_REMOVAL_SUMMARY.md @@ -0,0 +1,232 @@ +# Summary: Firebase Configuration Security Enhancement + +## Issue Addressed + +The repository previously had Firebase configuration files committed to the public repository: +- `google-services.json` (Android) - containing Firebase API key +- `GoogleService-Info.plist` (iOS) - containing Firebase API key + +This violates security best practices for open-source projects. + +## Solution Implemented + +### 1. Removed Files from Git Tracking + +Used `git rm --cached` to remove the files from version control while preserving local copies: +- `google-services.json` +- `GoogleService-Info.plist` +- `android/app/google-services.json` +- `ios/BitSleuthWallet/GoogleService-Info.plist` + +These files are now in `.gitignore` and will not be committed in future. + +### 2. Created Template Files + +Added example configuration files with placeholder values: +- `google-services.example.json` (root and `android/app/`) +- `GoogleService-Info.example.plist` (root and `ios/BitSleuthWallet/`) + +All template files have been validated: +- ✅ Valid JSON/PLIST syntax +- ✅ Correct structure expected by Firebase +- ✅ Analytics disabled (privacy requirement) +- ✅ Placeholder values clearly marked + +### 3. Added Comprehensive Documentation + +#### New Documentation Files + +1. **`docs/FIREBASE_SETUP.md`** (10KB) + - Complete step-by-step Firebase project setup + - API key security and restrictions + - App Check configuration + - Troubleshooting guide + - EAS Build integration + +2. **`docs/FIREBASE_SECURITY_ACTION_ITEMS.md`** (6KB) + - Assessment of exposed API keys + - Risk level evaluation + - Immediate and long-term action items + - Verification checklist + - What attackers can/cannot do + +3. **`docs/FIREBASE_CONFIG_README.md`** (2.5KB) + - Quick reference for Firebase config files + - Security rationale + - Links to detailed guides + +4. **Platform-Specific Quick Guides** + - `android/app/PLACE_GOOGLE_SERVICES_HERE.md` + - `ios/BitSleuthWallet/PLACE_GOOGLE_SERVICE_INFO_HERE.md` + +#### Updated Documentation + +1. **`README.md`** + - Updated Firebase Configuration section (step 2) + - Added link to setup guide + - Clarified that developers must create their own Firebase project + +2. **`SECURITY.md`** + - Added Firebase Configuration Security section + - Added to security scope: exposed config files and Firebase rules + - Links to setup documentation + +3. **`CONTRIBUTING.md`** + - Added Firebase setup as step 4 in Development Setup + - Updated Security section to mention Firebase configs + - Fixed step numbering + +### 4. Updated `.gitignore` + +Added entries to prevent future commits: +``` +# Firebase configuration files (use .example files as templates) +google-services.json +GoogleService-Info.plist +android/app/google-services.json +ios/BitSleuthWallet/GoogleService-Info.plist +``` + +## Security Assessment + +### What the Exposed API Keys Allow + +**Firebase API keys are NOT traditional secrets.** They are: +- Designed to be embedded in client applications +- Used to identify the Firebase project +- Protected by Firebase Security Rules and App Check +- NOT sufficient for direct data access + +### Risk Level: LOW to MEDIUM + +**Low Risk** because: +- Keys are meant for client-side use +- Security enforced by Firebase rules, not key secrecy +- BitSleuth only uses Crashlytics and Performance Monitoring (no database/storage) +- Analytics is explicitly disabled + +**Medium Risk** if: +- Firebase security rules are misconfigured +- API keys are not restricted in Google Cloud Console +- No App Check is enabled + +### Recommended Actions + +See `docs/FIREBASE_SECURITY_ACTION_ITEMS.md` for: +- ✅ Immediate actions (verify security rules, restrict keys) +- ✅ Short-term actions (enable App Check, set billing alerts) +- ✅ Long-term actions (consider key rotation if needed) + +## Impact on Development + +### What Developers Must Do + +1. **First-time setup:** + - Create their own Firebase project + - Download configuration files + - Place files in correct locations + - Follow `docs/FIREBASE_SETUP.md` + +2. **Daily development:** + - No impact - local config files work as before + - Files are ignored by git automatically + - Cannot accidentally commit them + +### What Build Systems Must Do + +**Local development builds:** No changes needed - files are still in the same locations + +**EAS Build / CI/CD:** May need to inject config files as secrets (documented in setup guide) + +## Files Changed + +### Deleted (from git tracking) +- `google-services.json` +- `GoogleService-Info.plist` +- `android/app/google-services.json` +- `ios/BitSleuthWallet/GoogleService-Info.plist` + +### Added +- `google-services.example.json` +- `GoogleService-Info.example.plist` +- `android/app/google-services.example.json` +- `ios/BitSleuthWallet/GoogleService-Info.example.plist` +- `android/app/PLACE_GOOGLE_SERVICES_HERE.md` +- `ios/BitSleuthWallet/PLACE_GOOGLE_SERVICE_INFO_HERE.md` +- `docs/FIREBASE_SETUP.md` +- `docs/FIREBASE_CONFIG_README.md` +- `docs/FIREBASE_SECURITY_ACTION_ITEMS.md` + +### Modified +- `.gitignore` +- `README.md` +- `SECURITY.md` +- `CONTRIBUTING.md` + +## Verification + +### ✅ Build Configuration Preserved +- Local config files still exist +- `app.json` still references correct paths +- Android gradle plugins still configured +- iOS CocoaPods still work + +### ✅ Template Files Validated +- JSON syntax valid +- PLIST syntax valid +- Firebase structure correct +- Analytics disabled + +### ✅ Git Tracking Stopped +- Files removed from git index +- Added to `.gitignore` +- Cannot be committed accidentally +- Local copies preserved + +## Historical Note + +**The API keys remain in git history.** This is intentional because: +- Rewriting history requires force push +- Would break all forks and clones +- Not recommended for active projects +- Mitigated by securing the Firebase project + +Instead of removing from history, we: +1. Prevent future commits +2. Secure the Firebase project +3. Document proper setup for new developers +4. Provide action items for the production project + +## Best Practices Followed + +✅ **Industry Standard**: Open-source projects don't commit Firebase configs +✅ **Template-Based**: Example files guide developers +✅ **Well Documented**: Comprehensive setup guides +✅ **Developer Friendly**: Quick reference files in platform directories +✅ **Security First**: Action items and risk assessment provided +✅ **Build Compatible**: No disruption to existing builds + +## Resources for Developers + +- **Setup Guide**: `docs/FIREBASE_SETUP.md` +- **Security Actions**: `docs/FIREBASE_SECURITY_ACTION_ITEMS.md` +- **Quick Reference**: `docs/FIREBASE_CONFIG_README.md` +- **Integration Details**: `docs/FIREBASE_INTEGRATION.md` +- **Security Policy**: `SECURITY.md` +- **Contributing Guide**: `CONTRIBUTING.md` + +## Questions? + +If you have questions about this change: + +1. Read `docs/FIREBASE_SETUP.md` for setup instructions +2. Read `docs/FIREBASE_SECURITY_ACTION_ITEMS.md` for security concerns +3. Check `CONTRIBUTING.md` for development workflow +4. Open a GitHub issue if you need help (don't share actual API keys!) +5. Contact security@bitsleuth.ai for security-specific questions + +--- + +**PR**: #[TBD] +**Date**: 2026-01-08 +**Author**: GitHub Copilot Agent diff --git a/docs/FIREBASE_SECURITY_ACTION_ITEMS.md b/docs/FIREBASE_SECURITY_ACTION_ITEMS.md new file mode 100644 index 00000000..861c0c4a --- /dev/null +++ b/docs/FIREBASE_SECURITY_ACTION_ITEMS.md @@ -0,0 +1,163 @@ +# Action Items: Previously Exposed Firebase API Keys + +## Summary + +Firebase API keys and configuration files were previously committed to this public repository: + +- **Firebase Project**: `bitsleuth` (Project Number: 510465233305) +- Android and iOS API keys were exposed in the configuration files + +## What These Keys Are + +These are **Firebase client API keys**, which are: +- Designed to be embedded in client applications (mobile apps, web apps) +- Used to identify your Firebase project to Google servers +- **Not secret** in the traditional sense - they're expected to be in client code +- Protected by Firebase security rules, App Check, and API restrictions + +## Security Assessment + +### Current Risk Level: LOW to MEDIUM + +The risk depends on your Firebase configuration: + +✅ **Low Risk If:** +- Firebase Security Rules are properly configured (deny by default) +- API keys are restricted in Google Cloud Console +- App Check is enabled +- Only Crashlytics and Performance Monitoring are used (as documented) +- No sensitive data is stored in Firebase Database/Firestore/Storage + +⚠️ **Medium Risk If:** +- Firebase services have permissive security rules +- API keys are not restricted +- High quota services are accessible + +## Recommended Actions + +### Immediate Actions (Priority: HIGH) + +- [ ] **Verify Firebase Security Rules** + - Go to [Firebase Console](https://console.firebase.google.com/project/bitsleuth) + - Check Firestore/Realtime Database rules (if used) + - Check Storage rules (if used) + - Ensure all rules deny access by default and require authentication + +- [ ] **Review Firebase Usage** + - Check Firebase Console for unusual activity + - Review Crashlytics, Performance Monitoring for normal patterns + - Check for any unexpected API calls or data access + +- [ ] **Restrict API Keys in Google Cloud Console** + - Go to [Google Cloud Console](https://console.cloud.google.com/) + - Navigate to APIs & Services > Credentials + - For each API key, add application restrictions: + - Android: Restrict to package name `ai.bitsleuth.wallet` with SHA-1 fingerprint + - iOS: Restrict to bundle ID `ai.bitsleuth.wallet` + - Limit API access to only required APIs (Firebase only) + +### Short-term Actions (Priority: MEDIUM) + +- [ ] **Enable Firebase App Check** + - Go to Firebase Console > Build > App Check + - Enable App Check for iOS (DeviceCheck or App Attest) + - Enable App Check for Android (Play Integrity or SafetyNet) + - This ensures only your apps can access Firebase resources + +- [ ] **Set Up Billing Alerts** + - Go to Google Cloud Console > Billing + - Set up budget alerts for unexpected usage + - Set a budget cap if possible + +- [ ] **Monitor Firebase Metrics** + - Set up monitoring for unusual traffic patterns + - Review Crashlytics and Performance data regularly + - Check for unexpected spikes in usage + +### Long-term Actions (Priority: LOW) + +- [ ] **Consider Rotating Keys (Optional)** + - If you want complete peace of mind, create a new Firebase project + - Migrate the production app to use new configuration files + - This removes any possibility of the old keys being used + - **Note**: This is only necessary if you suspect active abuse + +- [ ] **Implement Additional Security Layers** + - Use server-side validation for critical operations + - Implement rate limiting where applicable + - Add additional authentication layers for sensitive features + +## What Attackers Can/Cannot Do + +### ✅ What Attackers CAN Do (with just the API keys): +- Identify your Firebase project +- Attempt to access Firebase services +- Generate API calls (limited by restrictions) + +### ❌ What Attackers CANNOT Do (with just the API keys): +- Access data protected by Firebase Security Rules +- Impersonate authenticated users +- Access your Google Cloud project's other resources +- Bypass App Check (if enabled) +- Access server-side API keys or service accounts + +## Verification Checklist + +Use this checklist to verify your Firebase project is secure: + +- [ ] Firebase Security Rules reviewed and properly configured +- [ ] No publicly accessible data in Firestore/Database/Storage +- [ ] API keys restricted in Google Cloud Console +- [ ] App Check enabled (or planned for production) +- [ ] Billing alerts configured +- [ ] Recent Firebase activity reviewed (no anomalies) +- [ ] Only Crashlytics and Performance Monitoring are in use +- [ ] Firebase Analytics is disabled (as documented) + +## Current State After This PR + +✅ **Fixed:** +- Firebase config files removed from repository +- Future commits will not include these files (.gitignore) +- Example/template files provided for developers +- Documentation updated with security best practices + +⚠️ **Still Needs Attention:** +- Old API keys are in git history (they will always be there) +- Production Firebase project should have security measures above applied +- Each developer should use their own Firebase project for development + +## Git History + +**Important**: The API keys will remain in git history. To completely remove them from history would require: +- Rewriting git history (force push) +- All contributors would need to re-clone +- All forks would retain the old history +- **Not recommended** for active projects + +Instead, we mitigate by: +- Securing the Firebase project with proper rules and restrictions +- Removing files from future commits +- Educating developers about Firebase security + +## Resources + +- [Firebase Security Checklist](https://firebase.google.com/support/guides/security-checklist) +- [Firebase App Check](https://firebase.google.com/docs/app-check) +- [Restricting API Keys](https://cloud.google.com/docs/authentication/api-keys) +- [Firebase Security Rules](https://firebase.google.com/docs/rules) +- [Setup Guide](./FIREBASE_SETUP.md) + +## Questions? + +If you have questions about Firebase security or need help with any of these actions: + +1. Review the [Firebase Security Checklist](https://firebase.google.com/support/guides/security-checklist) +2. Check the [Setup Guide](./FIREBASE_SETUP.md) +3. Open a GitHub issue (don't include actual API keys in the issue!) +4. Contact security@bitsleuth.ai for security-specific concerns + +--- + +**Last Updated**: 2026-01-08 +**Status**: Config files removed from repo, security measures recommended diff --git a/docs/FIREBASE_SETUP.md b/docs/FIREBASE_SETUP.md new file mode 100644 index 00000000..8f47b501 --- /dev/null +++ b/docs/FIREBASE_SETUP.md @@ -0,0 +1,303 @@ +# Firebase Setup Guide + +This guide explains how to set up your own Firebase project for BitSleuth Wallet development. + +## Why You Need Your Own Firebase Project + +For security and privacy reasons, Firebase configuration files (`google-services.json` and `GoogleService-Info.plist`) are **not** included in this repository. Each developer should use their own Firebase project for development and testing. + +## Quick Start + +### Prerequisites + +- A Google account +- Access to the [Firebase Console](https://console.firebase.google.com/) + +### Step 1: Create a Firebase Project + +1. Go to [Firebase Console](https://console.firebase.google.com/) +2. Click "Add project" or "Create a project" +3. Enter a project name (e.g., "BitSleuth Wallet Dev") +4. (Optional) Enable Google Analytics - **Note: We do NOT use Analytics in the app for privacy reasons** +5. Click "Create project" + +### Step 2: Add iOS App + +1. In your Firebase project, click the iOS icon to add an iOS app +2. **iOS bundle ID**: `ai.bitsleuth.wallet` (or your custom bundle ID) +3. (Optional) App nickname: "BitSleuth Wallet iOS" +4. Click "Register app" +5. **Download `GoogleService-Info.plist`** +6. Place the downloaded file in two locations: + - `ios/BitSleuthWallet/GoogleService-Info.plist` + - `GoogleService-Info.plist` (root directory) +7. Follow the SDK setup instructions (most are already configured in this project) +8. Click "Continue to console" + +### Step 3: Add Android App + +1. In your Firebase project, click the Android icon to add an Android app +2. **Android package name**: `ai.bitsleuth.wallet` (or your custom package name) +3. (Optional) App nickname: "BitSleuth Wallet Android" +4. Click "Register app" +5. **Download `google-services.json`** +6. Place the downloaded file in two locations: + - `android/app/google-services.json` + - `google-services.json` (root directory) +7. Follow the SDK setup instructions (most are already configured in this project) +8. Click "Continue to console" + +### Step 4: Enable Firebase Services + +#### Enable Crashlytics + +1. In Firebase Console, go to **Build > Crashlytics** +2. Click "Enable Crashlytics" +3. Follow the setup wizard (dependencies are already in the project) +4. Note: Crashlytics requires a release build to send crash reports + +#### Enable Performance Monitoring + +1. In Firebase Console, go to **Build > Performance Monitoring** +2. Click "Get started" +3. Follow the setup wizard (dependencies are already in the project) + +#### Disable Analytics (Important!) + +BitSleuth Wallet does **NOT** use Firebase Analytics for privacy reasons. Ensure it's disabled: + +1. Go to **Build > Analytics** (if available) +2. Disable or do not enable Analytics +3. The app configuration in `firebase.json` already disables all analytics features + +### Step 5: Configure API Key Restrictions (Recommended) + +To prevent abuse of your Firebase API keys: + +#### For Web/Browser APIs (if applicable) +1. Go to [Google Cloud Console](https://console.cloud.google.com/) +2. Select your Firebase project +3. Navigate to **APIs & Services > Credentials** +4. Find your browser API key +5. Click "Edit" +6. Under "Application restrictions", select "HTTP referrers (web sites)" +7. Add your authorized domains +8. Click "Save" + +#### For Android/iOS Apps +1. The API keys in `google-services.json` and `GoogleService-Info.plist` are already restricted to your app's package/bundle ID +2. Ensure your package name (Android) and bundle ID (iOS) match your Firebase configuration +3. For additional security, enable App Check (see below) + +### Step 6: Enable App Check (Optional but Recommended) + +App Check helps protect your Firebase resources from abuse: + +1. In Firebase Console, go to **Build > App Check** +2. Click "Get started" +3. Register your iOS app: + - Provider: DeviceCheck or App Attest (for production) + - Follow the setup instructions +4. Register your Android app: + - Provider: Play Integrity API or SafetyNet (for production) + - Follow the setup instructions +5. Enable enforcement for Crashlytics and Performance Monitoring + +## Configuration Files + +### Example Files Provided + +This repository includes example configuration files: + +- `google-services.example.json` - Android configuration template +- `GoogleService-Info.example.plist` - iOS configuration template +- `android/app/google-services.example.json` - Android app configuration template +- `ios/BitSleuthWallet/GoogleService-Info.example.plist` - iOS app configuration template + +You can use these as references for the structure, but you **must** use your own Firebase project's configuration files. + +### File Locations + +After setup, your configuration files should be in these locations: + +``` +BitSleuth-Wallet/ +├── google-services.json # Android (root, referenced in app.json) +├── GoogleService-Info.plist # iOS (root, referenced in app.json) +├── android/ +│ └── app/ +│ └── google-services.json # Android (build time) +└── ios/ + └── BitSleuthWallet/ + └── GoogleService-Info.plist # iOS (build time) +``` + +**Important**: These files are in `.gitignore` and should **NEVER** be committed to version control. + +## Security Best Practices + +### 1. Protect Your Configuration Files + +- **Never commit** `google-services.json` or `GoogleService-Info.plist` to public repositories +- Keep these files secure and don't share them publicly +- Use different Firebase projects for development, staging, and production + +### 2. Implement Proper Security Rules + +Since this is a Bitcoin wallet app with client-side cryptography: + +- **Firestore/Realtime Database**: Not currently used, but if added, ensure strict security rules +- **Cloud Storage**: Not currently used, but if added, require authentication +- **Cloud Functions**: Not currently used, but if added, validate all inputs + +Example security rules (if you add Firestore): + +```javascript +rules_version = '2'; +service cloud.firestore { + match /databases/{database}/documents { + // Deny all access by default + match /{document=**} { + allow read, write: if false; + } + } +} +``` + +### 3. Monitor Usage and Billing + +1. Set up billing alerts in Google Cloud Console +2. Monitor Firebase usage in the Firebase Console +3. Review Crashlytics and Performance data regularly +4. Watch for unusual traffic patterns + +### 4. API Key Security + +- The API keys in `google-services.json` and `GoogleService-Info.plist` are **not secret** +- They identify your Firebase project but don't grant direct access +- Security is enforced through: + - App/Bundle ID restrictions (automatic) + - Firebase Security Rules (if using database/storage) + - App Check (recommended) + - Proper authentication and authorization + +### 5. What Can Be Done With Exposed API Keys? + +If someone obtains your Firebase API keys: + +**They CAN:** +- Identify your Firebase project +- Attempt to access public/misconfigured resources +- Generate traffic/quota usage + +**They CANNOT:** +- Access properly secured resources (with correct security rules) +- Impersonate authenticated users +- Access your Google Cloud project's sensitive resources + +**Protection:** +- Always use proper security rules +- Enable App Check +- Monitor for abuse +- Set billing limits + +## Troubleshooting + +### Build Errors + +If you get build errors about missing Firebase configuration: + +1. Verify `google-services.json` is in `android/app/` +2. Verify `GoogleService-Info.plist` is in `ios/BitSleuthWallet/` +3. Ensure the files are also in the root directory (referenced in `app.json`) +4. Clean and rebuild: + ```bash + # Android + cd android && ./gradlew clean && cd .. + + # iOS + cd ios && pod deintegrate && pod install && cd .. + ``` + +### Crashlytics Not Reporting + +1. Crashlytics only works in release builds, not debug builds +2. Verify Crashlytics is enabled in Firebase Console +3. Check that `firebase.json` has correct Crashlytics configuration +4. Rebuild the app after adding Firebase configuration + +### Performance Monitoring Not Working + +1. Performance data may take up to 24 hours to appear +2. Verify Performance Monitoring is enabled in Firebase Console +3. Test with release builds for accurate data + +### API Key Restrictions + +If you restrict your API keys and the app stops working: + +1. Verify your app's package name (Android) matches Firebase configuration +2. Verify your app's bundle ID (iOS) matches Firebase configuration +3. Check Google Cloud Console for any API restriction errors +4. Ensure App Check is properly configured if enabled + +## Using EAS Build + +When building with Expo Application Services (EAS), you have two options: + +### Option 1: Include in Version Control (Not Recommended for Public Repos) + +If your repository is **private**, you can commit the files. Add to `.gitignore`: + +``` +# Remove these lines to commit Firebase configs (private repos only) +# google-services.json +# GoogleService-Info.plist +# android/app/google-services.json +# ios/BitSleuthWallet/GoogleService-Info.plist +``` + +### Option 2: Use EAS Secrets (Recommended) + +For public repositories, use EAS secrets: + +1. **Encode your files to base64:** + ```bash + # Android + cat google-services.json | base64 + + # iOS + cat GoogleService-Info.plist | base64 + ``` + +2. **Add as EAS secrets:** + ```bash + eas secret:create --scope project --name GOOGLE_SERVICES_JSON --value "" + eas secret:create --scope project --name GOOGLE_SERVICE_INFO_PLIST --value "" + ``` + +3. **Update your `eas.json`** to inject these files during build (requires custom build hooks) + +For detailed EAS Build configuration, see [EAS Build Documentation](https://docs.expo.dev/build/introduction/). + +## Additional Resources + +- [Firebase Documentation](https://firebase.google.com/docs) +- [Firebase Security Checklist](https://firebase.google.com/support/guides/security-checklist) +- [App Check Documentation](https://firebase.google.com/docs/app-check) +- [Crashlytics Documentation](https://firebase.google.com/docs/crashlytics) +- [Performance Monitoring Documentation](https://firebase.google.com/docs/perf-mon) +- [BitSleuth Wallet Firebase Integration Guide](./FIREBASE_INTEGRATION.md) + +## Support + +If you encounter issues with Firebase setup: + +1. Check the [Firebase Documentation](https://firebase.google.com/docs) +2. Review the [troubleshooting section](#troubleshooting) above +3. Open an issue on GitHub with details about your problem +4. Ensure you're not sharing your actual API keys in issue reports + +--- + +**Remember**: The Firebase configuration files contain your project's API keys. While these keys are meant for client-side use, treat them with care and follow security best practices outlined in this guide. diff --git a/google-services.example.json b/google-services.example.json new file mode 100644 index 00000000..5c769366 --- /dev/null +++ b/google-services.example.json @@ -0,0 +1,31 @@ +{ + "_comment": "This is an EXAMPLE file. Replace with your own google-services.json from Firebase Console.", + "_instructions": "1. Go to https://console.firebase.google.com/ 2. Create/select your project 3. Add Android app 4. Download google-services.json 5. Replace this file", + "project_info": { + "project_number": "YOUR_PROJECT_NUMBER", + "project_id": "your-project-id", + "storage_bucket": "your-project-id.appspot.com" + }, + "client": [ + { + "client_info": { + "mobilesdk_app_id": "1:YOUR_PROJECT_NUMBER:android:YOUR_APP_ID", + "android_client_info": { + "package_name": "ai.bitsleuth.wallet" + } + }, + "oauth_client": [], + "api_key": [ + { + "current_key": "AIzaSy_YOUR_ANDROID_API_KEY_HERE" + } + ], + "services": { + "appinvite_service": { + "other_platform_oauth_client": [] + } + } + } + ], + "configuration_version": "1" +} \ No newline at end of file diff --git a/google-services.json b/google-services.json deleted file mode 100644 index 8c68de5c..00000000 --- a/google-services.json +++ /dev/null @@ -1,29 +0,0 @@ -{ - "project_info": { - "project_number": "510465233305", - "project_id": "bitsleuth", - "storage_bucket": "bitsleuth.firebasestorage.app" - }, - "client": [ - { - "client_info": { - "mobilesdk_app_id": "1:510465233305:android:17c91346ecafeaaf85c308", - "android_client_info": { - "package_name": "ai.bitsleuth.wallet" - } - }, - "oauth_client": [], - "api_key": [ - { - "current_key": "AIzaSyBCpQwAvY3MyN-OCYvMlJqbInohHSJpgfg" - } - ], - "services": { - "appinvite_service": { - "other_platform_oauth_client": [] - } - } - } - ], - "configuration_version": "1" -} \ No newline at end of file diff --git a/ios/BitSleuthWallet/GoogleService-Info.example.plist b/ios/BitSleuthWallet/GoogleService-Info.example.plist new file mode 100644 index 00000000..91963e89 --- /dev/null +++ b/ios/BitSleuthWallet/GoogleService-Info.example.plist @@ -0,0 +1,43 @@ + + + + + + API_KEY + AIzaSy_YOUR_IOS_API_KEY_HERE + GCM_SENDER_ID + YOUR_PROJECT_NUMBER + PLIST_VERSION + 1 + BUNDLE_ID + ai.bitsleuth.wallet + PROJECT_ID + your-project-id + STORAGE_BUCKET + your-project-id.appspot.com + IS_ADS_ENABLED + + IS_ANALYTICS_ENABLED + + IS_APPINVITE_ENABLED + + IS_GCM_ENABLED + + IS_SIGNIN_ENABLED + + GOOGLE_APP_ID + 1:YOUR_PROJECT_NUMBER:ios:YOUR_APP_ID + + \ No newline at end of file diff --git a/ios/BitSleuthWallet/GoogleService-Info.plist b/ios/BitSleuthWallet/GoogleService-Info.plist deleted file mode 100644 index d95f3870..00000000 --- a/ios/BitSleuthWallet/GoogleService-Info.plist +++ /dev/null @@ -1,30 +0,0 @@ - - - - - API_KEY - AIzaSyDnlFxwXvMa7Kfeycf_uj6v_YKMmggwc5g - GCM_SENDER_ID - 510465233305 - PLIST_VERSION - 1 - BUNDLE_ID - ai.bitsleuth.wallet - PROJECT_ID - bitsleuth - STORAGE_BUCKET - bitsleuth.firebasestorage.app - IS_ADS_ENABLED - - IS_ANALYTICS_ENABLED - - IS_APPINVITE_ENABLED - - IS_GCM_ENABLED - - IS_SIGNIN_ENABLED - - GOOGLE_APP_ID - 1:510465233305:ios:54dffa80d37d853185c308 - - \ No newline at end of file diff --git a/ios/BitSleuthWallet/PLACE_GOOGLE_SERVICE_INFO_HERE.md b/ios/BitSleuthWallet/PLACE_GOOGLE_SERVICE_INFO_HERE.md new file mode 100644 index 00000000..93d69b37 --- /dev/null +++ b/ios/BitSleuthWallet/PLACE_GOOGLE_SERVICE_INFO_HERE.md @@ -0,0 +1,21 @@ +# Firebase Configuration Required + +Place your `GoogleService-Info.plist` file in this directory. + +## Quick Setup + +1. Create a Firebase project at https://console.firebase.google.com/ +2. Add an iOS app with bundle ID: `ai.bitsleuth.wallet` +3. Download `GoogleService-Info.plist` +4. Place it here: `ios/BitSleuthWallet/GoogleService-Info.plist` +5. Also place a copy in the root directory: `GoogleService-Info.plist` + +## Complete Guide + +See [docs/FIREBASE_SETUP.md](../../docs/FIREBASE_SETUP.md) for detailed instructions. + +## Example File + +An example configuration is available at: `ios/BitSleuthWallet/GoogleService-Info.example.plist` + +**Note**: Never commit your actual `GoogleService-Info.plist` file to version control. It's in `.gitignore` for your protection.