cyberhybridhub/TODO.md

# Firebase Google Sign-In setup

## Quick setup (Ubuntu CLI)

Reload your shell after the first run (or open a new terminal):

```bash
source ~/.bashrc
```

One-shot setup (installs tools, logs in, configures FlutterFire, registers debug SHA-1):

```bash
cd ~/cyberhybridhub.com
chmod +x scripts/setup-firebase-google-auth.sh scripts/get-android-sha.sh

# Optional: set your Firebase project id to skip the interactive picker
export FIREBASE_PROJECT_ID=your-firebase-project-id

./scripts/setup-firebase-google-auth.sh
```

Or run step by step:

```bash
# 1. Tools (if not already installed)
npm install -g firebase-tools
dart pub global activate flutterfire_cli

# 2. Login (FlutterFire uses the Firebase CLI session)
firebase login

# 3. Register apps + download config (android, ios, web)
cd ~/cyberhybridhub.com
flutterfire configure \
  --project=YOUR_FIREBASE_PROJECT_ID \
  --platforms=android,ios,web \
  --android-package-name=com.cyberhybridhub.cyberhybridhub \
  --ios-bundle-id=com.cyberhybridhub.cyberhybridhub \
  --out=lib/firebase_options.dart

# 4. Debug SHA-1 (Android Google Sign-In)
./scripts/get-android-sha.sh
firebase apps:list --project=YOUR_FIREBASE_PROJECT_ID
firebase apps:android:sha:create ANDROID_APP_ID YOUR_SHA1 --project=YOUR_FIREBASE_PROJECT_ID
flutterfire configure --project=YOUR_FIREBASE_PROJECT_ID --platforms=android,ios,web --yes

# 5. Enable Google provider (browser — required)
#    https://console.firebase.google.com/ → Authentication → Sign-in method → Google → Enable

# 6. Run
flutter pub get && flutter run
```

`~/.bashrc` includes `~/.pub-cache/bin` (for `flutterfire`) and `CYBERHYBRIDHUB_ROOT`.

---

## Linux desktop development (`flutter run -d linux`)

Official FlutterFire does not register native plugins on Linux, so this app uses:

- `google_sign_in_all_platforms` (system browser OAuth)
- Firebase Auth REST (`signInWithIdp`) with web API key from `lib/firebase_options.dart`

### One-time Linux OAuth setup

1. [Google Cloud Console](https://console.cloud.google.com/) → project **cyberhybridhub** → **APIs & Services** → **Credentials**
2. Open your **Web application** OAuth 2.0 client (or create one)
3. Add authorized redirect URI: `http://127.0.0.1`
4. Copy **Client ID** and **Client secret** into `lib/config/auth_config.dart`:

```dart
const String? googleWebOAuthClientId = 'YOUR_CLIENT_ID.apps.googleusercontent.com';
const String? googleOAuthDesktopClientSecret = 'YOUR_CLIENT_SECRET';
```

### Web browser (`flutter run -d web-server` or Chrome)

Uses the same `googleWebOAuthClientId`. In Google Cloud, on that Web OAuth client, add **Authorized JavaScript origins**:

- `http://localhost`
- `http://127.0.0.1`

(Uncomment the `google-signin-client_id` meta tag in `web/index.html` only if you prefer HTML config over Dart.)

5. Enable Google sign-in in Firebase Console (if not already)
6. Run:

```bash
flutter run -d linux
```

---

## Manual checklist

Complete these steps to replace placeholder config files and enable Google authentication.

App identifiers used by this project:

| Platform | Identifier |
|----------|------------|
| Android package | `com.cyberhybridhub.cyberhybridhub` |
| iOS bundle ID | `com.cyberhybridhub.cyberhybridhub` |

---

## 1. Create a Firebase project

- [ ] Open [Firebase Console](https://console.firebase.google.com/).
- [ ] Create a project (or select an existing one).
- [ ] Enable **Google Analytics** only if you need it (optional for auth).

---

## 2. Register the Flutter app in Firebase

- [ ] In Firebase Console → **Project settings** → **Your apps**, add:
  - [ ] **Android** app with package name `com.cyberhybridhub.cyberhybridhub`
  - [ ] **iOS** app with bundle ID `com.cyberhybridhub.cyberhybridhub`
  - [ ] **Web** app (required for the web OAuth client used by Google Sign-In on mobile)
- [ ] Download config files when prompted:
  - [ ] `google-services.json` → replace `android/app/google-services.json`
  - [ ] `GoogleService-Info.plist` → replace `ios/Runner/GoogleService-Info.plist`

### Recommended: FlutterFire CLI

```bash
dart pub global activate flutterfire_cli
flutterfire configure
```

This regenerates `lib/firebase_options.dart` and downloads the platform config files.

---

## 3. Enable Google sign-in in Firebase

- [ ] Firebase Console → **Build** → **Authentication** → **Sign-in method**
- [ ] Enable **Google**
- [ ] Set a support email and save

---

## 4. Google Cloud Console (OAuth & credentials)

Firebase links to a Google Cloud project. Open it from Firebase → **Project settings** → **General** → **Google Cloud Platform resource location** → link to GCP, or go to [Google Cloud Console](https://console.cloud.google.com/) and select the same project.

### 4.1 OAuth consent screen

- [ ] **APIs & Services** → **OAuth consent screen**
- [ ] Choose **External** (or Internal for Workspace-only)
- [ ] Fill app name, user support email, developer contact
- [ ] Add scopes if needed (default `email`, `profile`, `openid` are usually enough)
- [ ] Add test users while the app is in **Testing** mode

### 4.2 OAuth 2.0 Client IDs

- [ ] **APIs & Services** → **Credentials**
- [ ] Confirm these clients exist (Firebase often creates them automatically):

| Client type | Purpose |
|-------------|---------|
| **Web application** | `serverClientId` / ID token for Firebase Auth on Android |
| **Android** | Package name + SHA-1 certificate fingerprints |
| **iOS** | Bundle ID |

#### Android SHA-1 fingerprints

Debug keystore (local development):

```bash
keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android
```

Release keystore (production):

```bash
keytool -list -v -keystore /path/to/your-release.keystore -alias your-alias
```

- [ ] Add **SHA-1** (and **SHA-256** if offered) to the Android OAuth client in Google Cloud Console
- [ ] Re-download `google-services.json` after adding fingerprints

#### iOS URL scheme

- [ ] Open `ios/Runner/GoogleService-Info.plist` and copy `REVERSED_CLIENT_ID`
- [ ] In Xcode (or `ios/Runner/Info.plist`), add a URL type:
  - **URL Schemes**: value of `REVERSED_CLIENT_ID`
  - Example: `com.googleusercontent.apps.123456789-abcdef`

---

## 5. App code configuration

- [ ] Replace placeholders in `lib/firebase_options.dart` (or run `flutterfire configure`)
- [ ] If sign-in fails on Android with a `serverClientId` error, set the Web client ID in `lib/config/auth_config.dart`:

```dart
const String? googleSignInServerClientId = 'YOUR_WEB_CLIENT_ID.apps.googleusercontent.com';
```

Find the Web client ID in Firebase → Project settings → Your apps → Web app, or in `google-services.json` under `oauth_client` with `"client_type": 3`.

---

## 6. Verify

```bash
flutter pub get
flutter run
```

- [ ] Tap **Continue with Google** on the login screen
- [ ] Complete Google account selection
- [ ] Confirm the home screen shows your name and email
- [ ] Sign out and sign in again

---

## Troubleshooting

| Symptom | Likely fix |
|---------|------------|
| `clientConfigurationError` | Wrong package/bundle ID, missing SHA-1, or invalid `google-services.json` |
| Sign-in cancels immediately after account pick | Missing web OAuth client in `google-services.json` or wrong SHA-1 |
| `serverClientId must be provided on Android` | Add Web app in Firebase, re-download `google-services.json`, or set `googleSignInServerClientId` |
| iOS sign-in fails after Google UI | Add `REVERSED_CLIENT_ID` URL scheme to `Info.plist` |
| `REPLACE_ME` / invalid API key at runtime | Run `flutterfire configure` or paste real values from Firebase |

---

## Reference

- [FlutterFire setup](https://firebase.flutter.dev/docs/overview)
- [Firebase Auth – Google](https://firebase.google.com/docs/auth/flutter/federated-auth#google)
- [google_sign_in plugin](https://pub.dev/packages/google_sign_in)