feat(https): add per-function CORS support

- Update `FirebaseFunctionDeclaration` and `registerFunction` to store `allowedOrigins`

- Update `onRequest`, `onCall`, and `onCallWithData` to pass CORS options

- Update `server.dart` to intercept `OPTIONS` preflight requests and append headers to responses

- Add unit tests for origin matching (`server_test.dart`) and option passing (`https_namespace_test.dart`)

Author: kevmoo

lib/src/firebase.dart

@@ -180,6 +180,7 @@ extension FirebaseX on Firebase {
     bool external = false,
     String? documentPattern,
     String? refPattern,
+    List<String>? allowedOrigins,
   }) {
     // Check for duplicate function names
     if (functions.any((f) => f.name == name)) {
@@ -195,6 +196,7 @@ extension FirebaseX on Firebase {
         name: transformedName,
         handler: handler,
         external: external,
+        allowedOrigins: allowedOrigins,
         documentPattern: documentPattern,
         refPattern: refPattern,
       ),
@@ -214,6 +216,7 @@ final class FirebaseFunctionDeclaration {
     required this.name,
     required this.handler,
     required this.external,
+    this.allowedOrigins,
     this.documentPattern,
     this.refPattern,
   }) : path = name;
@@ -238,6 +241,9 @@ final class FirebaseFunctionDeclaration {
   /// Event-driven functions are internal (false, POST only).
   final bool external;
 
+  /// Allowed origins for CORS (if specified).
+  final List<String>? allowedOrigins;
+
   /// The function handler.
   final FirebaseFunctionHandler handler;
 }

lib/src/https/https_namespace.dart

@@ -51,15 +51,20 @@ class HttpsNamespace extends FunctionsNamespace {
     // ignore: experimental_member_use
     @mustBeConst HttpsOptions? options = const HttpsOptions(),
   }) {
-    firebase.registerFunction(name, (request) async {
-      try {
-        return await handler(request);
-      } on HttpsError catch (e) {
-        return e.toShelfResponse();
-      } catch (e, stackTrace) {
-        return logInternalError(e, stackTrace).toShelfResponse();
-      }
-    }, external: true);
+    firebase.registerFunction(
+      name,
+      (request) async {
+        try {
+          return await handler(request);
+        } on HttpsError catch (e) {
+          return e.toShelfResponse();
+        } catch (e, stackTrace) {
+          return logInternalError(e, stackTrace).toShelfResponse();
+        }
+      },
+      external: true,
+      allowedOrigins: options?.cors?.runtimeValue(),
+    );
   }
 
   /// Creates an HTTPS callable function (untyped data).
@@ -141,7 +146,7 @@ class HttpsNamespace extends FunctionsNamespace {
         (result) => result.data,
         (result) => result.toResponse(),
       );
-    });
+    }, allowedOrigins: options?.cors?.runtimeValue());
   }
 
   /// Creates an HTTPS callable function with typed data.
@@ -225,7 +230,7 @@ class HttpsNamespace extends FunctionsNamespace {
           headers: {'Content-Type': 'application/json'},
         ),
       );
-    });
+    }, allowedOrigins: options?.cors?.runtimeValue());
   }
 
   /// Internal handler for callable functions.

lib/src/server.dart

@@ -99,6 +99,38 @@ const _corsAnyOriginHeaders = {
   'Access-Control-Allow-Headers': '*',
 };
 
+Response _buildOptionsCorsResponse(
+  Request request,
+  List<String> allowedOrigins,
+) => Response.ok('', headers: corsHeadersFor(request, allowedOrigins));
+
+Response _applyCorsHeaders(
+  Request request,
+  Response response,
+  List<String> allowedOrigins,
+) => response.change(headers: corsHeadersFor(request, allowedOrigins));
+
+@visibleForTesting
+Map<String, String> corsHeadersFor(
+  Request request,
+  List<String> allowedOrigins,
+) {
+  if (allowedOrigins.contains('*')) {
+    return _corsAnyOriginHeaders;
+  }
+
+  final origin = request.headers['origin'];
+  if (origin != null && allowedOrigins.contains(origin)) {
+    return {
+      'Access-Control-Allow-Origin': origin,
+      'Access-Control-Allow-Methods': '*',
+      'Access-Control-Allow-Headers': '*',
+    };
+  }
+
+  return const {};
+}
+
 /// Routes incoming requests to the appropriate function handler.
 FutureOr<Response> _routeRequest(
   Request request,
@@ -144,7 +176,7 @@ FutureOr<Response> _routeToTargetFunction(
   Firebase firebase,
   FirebaseEnv env,
   String functionTarget,
-) {
+) async {
   final functions = firebase.functions;
 
   // Find the function with matching name
@@ -165,6 +197,11 @@ FutureOr<Response> _routeToTargetFunction(
   // from the Node.js model does not apply here.
 
   // Validate HTTP method for event functions
+  if (request.method.toUpperCase() == 'OPTIONS' &&
+      targetFunction.allowedOrigins != null) {
+    return _buildOptionsCorsResponse(request, targetFunction.allowedOrigins!);
+  }
+
   if (!targetFunction.external && request.method.toUpperCase() != 'POST') {
     return Response(
       405,
@@ -173,10 +210,12 @@ FutureOr<Response> _routeToTargetFunction(
     );
   }
 
-  // Execute the target function (all requests go to this function)
-  // Wrap with onInit to ensure initialization callback runs before first execution
   final wrappedHandler = withInit(targetFunction.handler);
-  return wrappedHandler(request);
+  final response = await wrappedHandler(request);
+  if (targetFunction.allowedOrigins != null) {
+    return _applyCorsHeaders(request, response, targetFunction.allowedOrigins!);
+  }
+  return response;
 }
 
 /// Routes request by path matching (development/shared process mode).
@@ -215,16 +254,29 @@ FutureOr<Response> _routeByPath(
 
   // Try to find a matching function by name
   for (final function in functions) {
-    // Internal functions (events) only accept POST requests
-    if (!function.external && currentRequest.method.toUpperCase() != 'POST') {
-      continue;
-    }
-
-    // Match by function name
     if (functionName == function.name) {
-      // Wrap with onInit to ensure initialization callback runs before first execution
+      if (currentRequest.method.toUpperCase() == 'OPTIONS' &&
+          function.allowedOrigins != null) {
+        return _buildOptionsCorsResponse(
+          currentRequest,
+          function.allowedOrigins!,
+        );
+      }
+
+      if (!function.external && currentRequest.method.toUpperCase() != 'POST') {
+        continue;
+      }
+
       final wrappedHandler = withInit(function.handler);
-      return wrappedHandler(currentRequest);
+      final response = await wrappedHandler(currentRequest);
+      if (function.allowedOrigins != null) {
+        return _applyCorsHeaders(
+          currentRequest,
+          response,
+          function.allowedOrigins!,
+        );
+      }
+      return response;
     }
   }
 

test/unit/https_namespace_test.dart

@@ -385,7 +385,8 @@ void main() {
           (request) async => Response.ok('OK'),
         );
 
-        expect(_findFunction(firebase, 'options-function'), isNotNull);
+        final func = _findFunction(firebase, 'options-function')!;
+        expect(func.allowedOrigins, ['https://example.com']);
       });
 
       test('CallableOptions can be provided', () {
@@ -399,6 +400,20 @@ void main() {
 
         expect(_findFunction(firebase, 'callable-options-function'), isNotNull);
       });
+
+      test('CallableOptions can be provided passing allowedOrigins', () {
+        https.onCall(
+          name: 'callableOptionsFunctionWithOrigins',
+          options: const CallableOptions(cors: Cors(['https://example.com'])),
+          (request, response) async => CallableResult('OK'),
+        );
+
+        final func = _findFunction(
+          firebase,
+          'callable-options-function-with-origins',
+        )!;
+        expect(func.allowedOrigins, ['https://example.com']);
+      });
     });
   });
 }

test/unit/server_test.dart

@@ -13,6 +13,7 @@
 // limitations under the License.
 
 import 'package:firebase_functions/src/server.dart';
+import 'package:shelf/shelf.dart';
 import 'package:test/test.dart';
 
 void main() {
@@ -49,5 +50,33 @@ void main() {
         expect(extractTraceId('1234567890xyzdef1234567890abcdef/5'), isNull);
       });
     });
+
+    group('corsHeadersFor', () {
+      test('returns asterisk when allowedOrigins contains asterisk', () {
+        final request = Request('GET', Uri.parse('http://localhost/test'));
+        final headers = corsHeadersFor(request, ['*']);
+        expect(headers['Access-Control-Allow-Origin'], '*');
+      });
+
+      test('echoes the Origin header if it matches allowedOrigins', () {
+        final request = Request(
+          'GET',
+          Uri.parse('http://localhost/test'),
+          headers: {'origin': 'https://example.com'},
+        );
+        final headers = corsHeadersFor(request, ['https://example.com']);
+        expect(headers['Access-Control-Allow-Origin'], 'https://example.com');
+      });
+
+      test('returns empty map if no match is found', () {
+        final request = Request(
+          'GET',
+          Uri.parse('http://localhost/test'),
+          headers: {'origin': 'https://evil.com'},
+        );
+        final headers = corsHeadersFor(request, ['https://example.com']);
+        expect(headers, isEmpty);
+      });
+    });
   });
 }