fix(cors): defer parameter resolution in https callables and requests

### Description
Fixes an issue where passing a parameterized CORS origin (`Expression`) to HTTPS functions attempts to evaluate the parameter at global module definition time rather than request runtime.
This updates `resolveCorsOrigin` to execute per-request, gracefully catching missing environment variables or empty parameters and disabling CORS (`origin: false`) as a secure fallback.
Additionally, this updates V1 `https.onRequest` to accept an options object (`HttpsOptions`) supporting custom `cors` configuration, aligning with V2.

### Scenarios Tested
- Added unit tests in `spec/common/providers/https.spec.ts` verifying `resolveCorsOrigin` successfully extracts runtime values from `StringParam` and `ListParam` Expressions, and safely defaults to `false` when params are missing or evaluate to empty lists/strings.
- Added unit tests in `spec/v1/providers/https.spec.ts` verifying V1 `onRequest` correctly enforces custom CORS options and does not crash when passed an Expression.
- Added unit tests in `spec/v2/providers/https.spec.ts` verifying passing Expressions to `onRequest` and `onCall` CORS options does not cause definition-time crashes.
- Ran the full `npm test` suite to confirm zero regressions.

### Sample Commands
`npm test`

Author: inlined

spec/common/providers/https.spec.ts

@@ -3,6 +3,7 @@ import { App, initializeApp } from "firebase-admin/app";
 import * as appCheck from "firebase-admin/app-check";
 import * as sinon from "sinon";
 import * as nock from "nock";
+import { defineString, defineList } from "../../../src/params";
 
 import { getApp, setApp } from "../../../src/common/app";
 import * as debug from "../../../src/common/debug";
@@ -949,6 +950,127 @@ describe("onCallHandler", () => {
       });
     });
   });
+
+  describe("CORS resolution", () => {
+    let oldEnv: NodeJS.ProcessEnv;
+
+    beforeEach(() => {
+      oldEnv = process.env;
+      process.env = { ...oldEnv };
+    });
+
+    afterEach(() => {
+      process.env = oldEnv;
+    });
+
+    it("should resolve Expression origin", async () => {
+      process.env.ALLOWED_ORIGIN = "example.org";
+      const param = defineString("ALLOWED_ORIGIN");
+      await runCallableTest({
+        httpRequest: mockRequest(null, "application/json", {}, {
+          origin: "example.org",
+        }),
+        expectedData: null,
+        callableOption: {
+          cors: { origin: param, methods: "POST" },
+        },
+        callableFunction: () => null,
+        callableFunction2: () => null,
+        expectedHttpResponse: {
+          status: 200,
+          headers: {
+            "Access-Control-Allow-Origin": "example.org",
+            "Vary": "Origin",
+          },
+          body: { result: null },
+        },
+      });
+    });
+
+    it("should resolve Expression list origin", async () => {
+      process.env.ALLOWED_ORIGINS = JSON.stringify(["example.com", "example.org"]);
+      const param = defineList("ALLOWED_ORIGINS");
+      await runCallableTest({
+        httpRequest: mockRequest(null, "application/json", {}, {
+          origin: "example.org",
+        }),
+        expectedData: null,
+        callableOption: {
+          cors: { origin: param, methods: "POST" },
+        },
+        callableFunction: () => null,
+        callableFunction2: () => null,
+        expectedHttpResponse: {
+          status: 200,
+          headers: {
+            "Access-Control-Allow-Origin": "example.org",
+            "Vary": "Origin",
+          },
+          body: { result: null },
+        },
+      });
+    });
+  });
+});
+
+describe("resolveCorsOrigin", () => {
+  let oldEnv: NodeJS.ProcessEnv;
+
+  beforeEach(() => {
+    oldEnv = process.env;
+    process.env = { ...oldEnv };
+  });
+
+  afterEach(() => {
+    process.env = oldEnv;
+    sinon.restore();
+  });
+
+  it("should resolve Expression string", () => {
+    process.env.ALLOWED_ORIGIN = "example.com";
+    const param = defineString("ALLOWED_ORIGIN");
+    expect(https.resolveCorsOrigin(param)).to.equal("example.com");
+  });
+
+  it("should resolve Expression list", () => {
+    process.env.ALLOWED_ORIGINS = JSON.stringify(["example.com", "example.org"]);
+    const param = defineList("ALLOWED_ORIGINS");
+    expect(https.resolveCorsOrigin(param)).to.deep.equal(["example.com", "example.org"]);
+  });
+
+  it("should flatten single element array", () => {
+    expect(https.resolveCorsOrigin(["example.com"])).to.equal("example.com");
+  });
+
+  it("should support enableCors debug feature", () => {
+    sinon.stub(debug, "isDebugFeatureEnabled").withArgs("enableCors").returns(true);
+    expect(https.resolveCorsOrigin("example.com")).to.equal(true);
+  });
+
+  it("should respect cors: false even with enableCors debug feature", () => {
+    sinon.stub(debug, "isDebugFeatureEnabled").withArgs("enableCors").returns(true);
+    expect(https.resolveCorsOrigin(false)).to.equal(false);
+  });
+
+  it("should disable CORS when ListParam is missing at runtime", () => {
+    delete process.env.MISSING_ORIGINS;
+    const param = defineList("MISSING_ORIGINS");
+    expect(https.resolveCorsOrigin(param)).to.equal(false);
+  });
+
+  it("should disable CORS when StringParam is missing at runtime", () => {
+    delete process.env.MISSING_ORIGIN;
+    const param = defineString("MISSING_ORIGIN");
+    expect(https.resolveCorsOrigin(param)).to.equal(false);
+  });
+
+  it("should disable CORS when origin is an empty array", () => {
+    expect(https.resolveCorsOrigin([])).to.equal(false);
+  });
+
+  it("should disable CORS when origin is an empty string", () => {
+    expect(https.resolveCorsOrigin("")).to.equal(false);
+  });
 });
 
 describe("encoding/decoding", () => {

spec/v1/providers/https.spec.ts

@@ -21,6 +21,7 @@
 // SOFTWARE.
 
 import { expect } from "chai";
+import { defineString, defineList } from "../../../src/params";
 
 import * as functions from "../../../src/v1";
 import * as https from "../../../src/v1/providers/https";
@@ -91,6 +92,28 @@ describe("CloudHttpsBuilder", () => {
       await runHandler(fn, req as any);
       expect(hello).to.equal("world");
     });
+
+    it("should enforce CORS options", async () => {
+      const func = functions.https.onRequest({ cors: "example.com" }, (req, resp) => {
+        resp.status(200).send("hello");
+      });
+      const req = mockRequest(null, "application/json", {}, { origin: "example.com" });
+      req.method = "GET";
+      const resp = await runHandler(func, req as any);
+      expect(resp.status).to.equal(200);
+      expect(resp.headers?.["Access-Control-Allow-Origin"]).to.equal("example.com");
+    });
+
+    it("should not crash when a string or list parameter is passed in", () => {
+      const stringParam = defineString("ALLOWED_ORIGIN");
+      const listParam = defineList("ALLOWED_ORIGINS");
+
+      const funcString = functions.https.onRequest({ cors: stringParam }, () => {});
+      const funcList = functions.https.onRequest({ cors: listParam }, () => {});
+
+      expect(funcString).to.be.a("function");
+      expect(funcList).to.be.a("function");
+    });
   });
 });
 

spec/v2/providers/https.spec.ts

@@ -32,7 +32,7 @@ import { FULL_ENDPOINT, MINIMAL_V2_ENDPOINT, FULL_OPTIONS, FULL_TRIGGER } from "
 import { onInit } from "../../../src/v2/core";
 import { Handler } from "express";
 import { genkit } from "genkit";
-import { clearParams, defineBoolean, defineList, Expression } from "../../../src/params";
+import { clearParams, defineBoolean, defineList, defineString, Expression } from "../../../src/params";
 
 function request(args: {
   data?: any;
@@ -336,6 +336,17 @@ describe("onRequest", () => {
     await runHandler(func, req);
     expect(hello).to.equal("world");
   });
+
+  it("should not crash when a string or list parameter is passed in", () => {
+    const stringParam = defineString("ALLOWED_ORIGIN");
+    const listParam = defineList("ALLOWED_ORIGINS");
+
+    const funcString = https.onRequest({ cors: stringParam }, () => {});
+    const funcList = https.onRequest({ cors: listParam }, () => {});
+
+    expect(funcString).to.be.a("function");
+    expect(funcList).to.be.a("function");
+  });
 });
 
 describe("onCall", () => {
@@ -605,6 +616,17 @@ describe("onCall", () => {
     expect(hello).to.equal("world");
   });
 
+  it("should not crash when a string or list parameter is passed in", () => {
+    const stringParam = defineString("ALLOWED_ORIGIN");
+    const listParam = defineList("ALLOWED_ORIGINS");
+
+    const funcString = https.onCall({ cors: stringParam }, () => 42);
+    const funcList = https.onCall({ cors: listParam }, () => 42);
+
+    expect(funcString).to.be.a("function");
+    expect(funcList).to.be.a("function");
+  });
+
   describe("authPolicy", () => {
     before(() => {
       sinon.stub(debug, "isDebugFeatureEnabled").withArgs("skipTokenVerification").returns(true);

src/common/providers/https.ts

@@ -33,6 +33,7 @@ import { DecodedIdToken, getAuth } from "firebase-admin/auth";
 import { getApp } from "../app";
 import { isDebugFeatureEnabled } from "../debug";
 import { TaskContext } from "./tasks";
+import { Expression } from "../../params";
 
 const JWT_REGEX = /^[a-zA-Z0-9\-_=]+?\.[a-zA-Z0-9\-_=]+?\.([a-zA-Z0-9\-_=]+)?$/;
 
@@ -710,9 +711,63 @@ type v2CallableHandler<Req, Res, Stream> = (
   response?: CallableResponse<Stream>
 ) => Res;
 
+export type CorsOption =
+  | string
+  | Expression<string>
+  | Expression<string[]>
+  | boolean
+  | RegExp
+  | Array<string | RegExp>;
+
+export function resolveCorsOrigin(corsOption?: CorsOption): cors.CorsOptions["origin"] {
+  let origin: CorsOption | undefined;
+  if (corsOption instanceof Expression) {
+    try {
+      origin = corsOption.value();
+    } catch (e) {
+      logger.warn(`Failed to resolve CORS parameter: ${e}`);
+      origin = false;
+    }
+  } else {
+    origin = corsOption;
+  }
+
+  if (Array.isArray(origin) && origin.length === 0) {
+    logger.warn("CORS parameter resolved to an empty array. Disabling CORS.");
+    origin = false;
+  }
+
+  if (origin === "") {
+    logger.warn("CORS parameter resolved to an empty string. Disabling CORS.");
+    origin = false;
+  }
+
+  if (isDebugFeatureEnabled("enableCors")) {
+    // Respect `cors: false` to turn off cors even if debug feature is enabled.
+    origin = origin === false ? false : true;
+  }
+
+  if (origin === undefined) {
+    origin = true;
+  }
+
+  // Arrays cause the access-control-allow-origin header to be dynamic based
+  // on the origin header of the request. If there is only one element in the
+  // array, this is unnecessary.
+  if (Array.isArray(origin) && origin.length === 1) {
+    origin = origin[0];
+  }
+
+  return origin;
+}
+
+export type CorsInfo = Omit<cors.CorsOptions, "origin"> & {
+  origin?: CorsOption;
+};
+
 /** @internal **/
 export interface CallableOptions<T = any> {
-  cors: cors.CorsOptions;
+  cors: CorsInfo;
   enforceAppCheck?: boolean;
   consumeAppCheckToken?: boolean;
   /* @deprecated */
@@ -736,7 +791,12 @@ export function onCallHandler<Req = any, Res = any, Stream = unknown>(
   return (req: Request, res: express.Response) => {
     return new Promise((resolve) => {
       res.on("finish", resolve);
-      cors(options.cors)(req, res, () => {
+      const origin = resolveCorsOrigin(options.cors.origin);
+      const corsOptions = {
+        ...options.cors,
+        origin,
+      };
+      cors(corsOptions as cors.CorsOptions)(req, res, () => {
         resolve(wrapped(req, res));
       });
     });

src/v1/function-builder.ts

@@ -339,11 +339,26 @@ export class FunctionBuilder {
     return {
       /**
        * Handle HTTP requests.
-       * @param handler A function that takes a request and response object,
+       * @param optsOrHandler Options or a function that takes a request and response object,
        * same signature as an Express app.
        */
-      onRequest: (handler: (req: https.Request, resp: express.Response) => void | Promise<void>) =>
-        https._onRequestWithOptions(handler, this.options),
+      onRequest: (
+        optsOrHandler:
+          | https.HttpsOptions
+          | ((req: https.Request, resp: express.Response) => void | Promise<void>),
+        handler?: (req: https.Request, resp: express.Response) => void | Promise<void>
+      ) => {
+        let opts: https.HttpsOptions;
+        let userHandler: (req: https.Request, resp: express.Response) => void | Promise<void>;
+        if (typeof optsOrHandler === "function") {
+          opts = {};
+          userHandler = optsOrHandler;
+        } else {
+          opts = optsOrHandler as https.HttpsOptions;
+          userHandler = handler!;
+        }
+        return https._onRequestWithOptions(userHandler, { ...this.options, ...opts } as any);
+      },
       /**
        * Declares a callable method for clients to call using a Firebase SDK.
        * @param handler A method that takes a data and context and returns a value.