refactor: centralize environment variable lookups

Introduced FirebaseEnv to unify emulator configuration and project ID resolution across namespaces, replacing scattered Platform.environment lookups.

Also made `projecId` not nullable and moved the `demo-test`
logic into a mock setting

Also refactored InternalExpression

Author: kevmoo

lib/src/common/environment.dart

@@ -0,0 +1,103 @@
+// Copyright 2026 Firebase
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:meta/meta.dart';
+
+/// Provides unified access to environment variables, emulator checks, and
+/// Google Cloud / Firebase configuration.
+class FirebaseEnv {
+  FirebaseEnv({Map<String, String>? environment})
+    : environment = environment ?? mockEnvironment ?? Platform.environment;
+
+  @visibleForTesting
+  static Map<String, String>? mockEnvironment;
+
+  final Map<String, String> environment;
+
+  /// Whether running within a Firebase emulator environment.
+  bool get isEmulator {
+    // Explicit functions emulator flag
+    if (environment['FUNCTIONS_EMULATOR'] == 'true') {
+      return true;
+    }
+
+    // Generic fallback: check if any common emulator hosts are configured
+    if (environment.containsKey('FIRESTORE_EMULATOR_HOST') ||
+        environment.containsKey('FIREBASE_AUTH_EMULATOR_HOST') ||
+        environment.containsKey('FIREBASE_DATABASE_EMULATOR_HOST') ||
+        environment.containsKey('FIREBASE_STORAGE_EMULATOR_HOST')) {
+      return true;
+    }
+
+    return false;
+  }
+
+  /// Timezone setting.
+  String get tz => environment['TZ'] ?? 'UTC';
+
+  /// Whether debug mode is enabled.
+  bool get debugMode => environment['FIREBASE_DEBUG_MODE'] == 'true';
+
+  /// Whether to skip token verification (emulator only).
+  bool get skipTokenVerification => _getDebugFeature('skipTokenVerification');
+
+  /// Whether CORS is enabled (emulator only).
+  bool get enableCors => _getDebugFeature('enableCors');
+
+  bool _getDebugFeature(String key) {
+    if (environment['FIREBASE_DEBUG_FEATURES'] case final String json) {
+      try {
+        if (jsonDecode(json) case final Map<String, dynamic> m) {
+          return switch (m[key]) {
+            final bool value => value,
+            _ => false,
+          };
+        }
+      } on FormatException {
+        // ignore
+      }
+    }
+    return false;
+  }
+
+  /// Returns the current Firebase project ID.
+  ///
+  /// Checks standard environment variables in order:
+  /// 1. FIREBASE_PROJECT
+  /// 2. GCLOUD_PROJECT
+  /// 3. GOOGLE_CLOUD_PROJECT
+  /// 4. GCP_PROJECT
+  ///
+  /// If none are set, throws [StateError].
+  String get projectId {
+    for (final option in _options) {
+      final value = environment[option];
+      if (value != null) return value;
+    }
+
+    throw StateError(
+      'No project ID found in environment. Checked: ${_options.join(', ')}',
+    );
+  }
+}
+
+const _options = [
+  'FIREBASE_PROJECT',
+  'GCLOUD_PROJECT',
+  'GOOGLE_CLOUD_PROJECT',
+  'GCP_PROJECT',
+];

lib/src/common/params.dart

@@ -792,11 +792,26 @@ class _EnumSelectParamInput<T extends Enum> extends ParamInput<List<T>> {
 /// These are special expressions that read from Firebase environment
 /// variables and are always available without being defined by the user.
 class InternalExpression extends Param<String> {
-  const InternalExpression._(String name, this.getter) : super(name, null);
-  final String Function(Map<String, String>) getter;
+  const InternalExpression._(String name, this._configKey) : super(name, null);
+
+  final String _configKey;
 
   @override
-  String runtimeValue() => getter(Platform.environment);
+  String runtimeValue() {
+    if (Platform.environment['FIREBASE_CONFIG'] case final String config) {
+      try {
+        if (jsonDecode(config) case final Map<String, dynamic> m) {
+          return switch (m[_configKey]) {
+            final String value => value,
+            _ => '',
+          };
+        }
+      } on FormatException {
+        // ignore
+      }
+    }
+    return '';
+  }
 
   @override
   WireParamSpec<String> toSpec() {
@@ -820,45 +835,22 @@ sealed class ParamInput<T extends Object> {
 
   // Internal Firebase expressions
 
-  static final databaseURL = InternalExpression._('DATABASE_URL', (env) {
-    if (!env.containsKey('FIREBASE_CONFIG')) return '';
-    try {
-      final config = jsonDecode(env['FIREBASE_CONFIG']!);
-      return config['databaseURL'] as String? ?? '';
-    } on FormatException {
-      return '';
-    }
-  });
+  static const databaseURL = InternalExpression._(
+    'DATABASE_URL',
+    'databaseURL',
+  );
 
-  static final projectId = InternalExpression._('PROJECT_ID', (env) {
-    if (!env.containsKey('FIREBASE_CONFIG')) return '';
-    try {
-      final config = jsonDecode(env['FIREBASE_CONFIG']!);
-      return config['projectId'] as String? ?? '';
-    } on FormatException {
-      return '';
-    }
-  });
+  static const projectId = InternalExpression._('PROJECT_ID', 'projectId');
 
-  static final gcloudProject = InternalExpression._('GCLOUD_PROJECT', (env) {
-    if (!env.containsKey('FIREBASE_CONFIG')) return '';
-    try {
-      final config = jsonDecode(env['FIREBASE_CONFIG']!);
-      return config['projectId'] as String? ?? '';
-    } on FormatException {
-      return '';
-    }
-  });
+  static const gcloudProject = InternalExpression._(
+    'GCLOUD_PROJECT',
+    'projectId',
+  );
 
-  static final storageBucket = InternalExpression._('STORAGE_BUCKET', (env) {
-    if (!env.containsKey('FIREBASE_CONFIG')) return '';
-    try {
-      final config = jsonDecode(env['FIREBASE_CONFIG']!);
-      return config['storageBucket'] as String? ?? '';
-    } on FormatException {
-      return '';
-    }
-  });
+  static const storageBucket = InternalExpression._(
+    'STORAGE_BUCKET',
+    'storageBucket',
+  );
 
   // Factory methods for creating input types
 

lib/src/firebase.dart

@@ -13,7 +13,6 @@
 // limitations under the License.
 
 import 'dart:async';
-import 'dart:io';
 
 import 'package:dart_firebase_admin/dart_firebase_admin.dart';
 import 'package:google_cloud_firestore/google_cloud_firestore.dart' as gfs;
@@ -22,6 +21,7 @@ import 'package:shelf/shelf.dart';
 
 import 'alerts/alerts_namespace.dart';
 import 'common/cloud_run_id.dart';
+import 'common/environment.dart';
 import 'database/database_namespace.dart';
 import 'eventarc/eventarc_namespace.dart';
 import 'firestore/firestore_namespace.dart';
@@ -48,18 +48,8 @@ class Firebase {
 
   /// Initialize the Firebase Admin SDK
   void _initializeAdminSDK() {
-    // Get project ID from environment
-    final projectId =
-        Platform.environment['GCLOUD_PROJECT'] ??
-        Platform.environment['GCP_PROJECT'] ??
-        'demo-test'; // Fallback for emulator
-
-    // Check if running in emulator
-    final firestoreEmulatorHost =
-        Platform.environment['FIRESTORE_EMULATOR_HOST'];
-    final isEmulator = firestoreEmulatorHost != null;
-
-    if (isEmulator) {
+    final env = FirebaseEnv();
+    if (env.isEmulator) {
       // TODO: Implement direct REST API calls to emulator
       // For now, we'll skip document fetching in emulator mode
       return;
@@ -71,7 +61,7 @@ class Firebase {
       _adminApp = FirebaseApp.initializeApp(
         options: AppOptions(
           credential: Credential.fromApplicationDefaultCredentials(),
-          projectId: projectId,
+          projectId: env.projectId,
         ),
       );
 

lib/src/https/https_namespace.dart

@@ -14,32 +14,18 @@
 
 import 'dart:async';
 import 'dart:convert';
-import 'dart:io';
 
 import 'package:meta/meta.dart';
 import 'package:shelf/shelf.dart';
 
+import '../common/environment.dart';
 import '../common/utilities.dart';
 import '../firebase.dart';
 import 'auth.dart';
 import 'callable.dart';
 import 'error.dart';
 import 'options.dart';
 
-/// Checks if token verification should be skipped (emulator mode).
-bool _shouldSkipTokenVerification() {
-  final debugFeatures = Platform.environment['FIREBASE_DEBUG_FEATURES'];
-  if (debugFeatures == null) {
-    return false;
-  }
-  try {
-    final features = jsonDecode(debugFeatures);
-    return features['skipTokenVerification'] as bool? ?? false;
-  } catch (_) {
-    return false;
-  }
-}
-
 /// HTTPS triggers namespace.
 ///
 /// Provides methods to define HTTP-triggered Cloud Functions.
@@ -115,7 +101,7 @@ class HttpsNamespace extends FunctionsNamespace {
       }
 
       // Extract auth and app check tokens
-      final skipVerification = _shouldSkipTokenVerification();
+      final skipVerification = FirebaseEnv().skipTokenVerification;
       final tokens = await checkTokens(
         request,
         skipTokenVerification: skipVerification,
@@ -195,7 +181,7 @@ class HttpsNamespace extends FunctionsNamespace {
       final body = await request.json as Map<String, dynamic>?;
 
       // Extract auth and app check tokens
-      final skipVerification = _shouldSkipTokenVerification();
+      final skipVerification = FirebaseEnv().skipTokenVerification;
       final tokens = await checkTokens(
         request,
         skipTokenVerification: skipVerification,

lib/src/identity/identity_namespace.dart

@@ -17,11 +17,11 @@ library;
 
 import 'dart:async';
 import 'dart:convert';
-import 'dart:io';
 
 import 'package:meta/meta.dart';
 import 'package:shelf/shelf.dart';
 
+import '../common/environment.dart';
 import '../common/utilities.dart';
 import '../firebase.dart';
 import '../https/error.dart';
@@ -277,44 +277,25 @@ class IdentityNamespace extends FunctionsNamespace {
   /// skipTokenVerification debug feature is enabled), verification is skipped.
   Future<Map<String, dynamic>> _decodeAndVerifyJwt(String jwt) async {
     // Get environment configuration
-    final env = Platform.environment;
-    final isEmulator = env['FUNCTIONS_EMULATOR'] == 'true';
-    final skipVerification = _shouldSkipTokenVerification(env);
+    final env = FirebaseEnv();
 
     // Get project ID
-    final projectId =
-        env['GCLOUD_PROJECT'] ??
-        env['GCP_PROJECT'] ??
-        env['FIREBASE_PROJECT'] ??
-        'demo-test';
+    final projectId = env.projectId;
 
     // Create verifier
     final verifier = AuthBlockingTokenVerifier(
       projectId: projectId,
-      isEmulator: isEmulator || skipVerification,
+      isEmulator: env.isEmulator || env.skipTokenVerification,
     );
 
     // Determine audience based on platform
     // Cloud Run uses "run.app", GCF v1 uses default
-    final kService = env['K_SERVICE']; // Cloud Run service name
+    final kService = env.environment['K_SERVICE']; // Cloud Run service name
     final audience = kService != null ? 'run.app' : null;
 
     return verifier.verifyToken(jwt, audience: audience);
   }
 
-  /// Checks if token verification should be skipped based on debug features.
-  bool _shouldSkipTokenVerification(Map<String, String> env) {
-    final debugFeatures = env['FIREBASE_DEBUG_FEATURES'];
-    if (debugFeatures == null) return false;
-
-    try {
-      final features = jsonDecode(debugFeatures) as Map<String, dynamic>;
-      return features['skipTokenVerification'] as bool? ?? false;
-    } on FormatException {
-      return false;
-    }
-  }
-
   /// Validates the auth response for invalid claims.
   void _validateAuthResponse(
     AuthBlockingEventType eventType,

lib/src/logger/logger.dart

@@ -16,6 +16,8 @@ import 'dart:async';
 import 'dart:convert';
 import 'dart:io' as io;
 
+import '../common/environment.dart';
+
 /// Log severity levels for Cloud Logging.
 ///
 /// See [LogSeverity](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#logseverity).
@@ -177,11 +179,9 @@ class Logger {
     // Add trace context if available.
     final traceId = Zone.current[traceIdKey] as String?;
     if (traceId != null) {
-      final project = io.Platform.environment['GCLOUD_PROJECT'];
-      if (project != null) {
-        entry['logging.googleapis.com/trace'] =
-            'projects/$project/traces/$traceId';
-      }
+      final project = FirebaseEnv().projectId;
+      entry['logging.googleapis.com/trace'] =
+          'projects/$project/traces/$traceId';
     }
 
     final sanitized = removeCircular(entry);