fix(functions): fail-fast with actionable error when declarative security APIs are disabled

[shettyvarun268]

Description

When deploying functions configured with Declarative Security (requiresRole / Function Kits), deployment requires:

1. iam.googleapis.com: To generate, inspect, and provision managed service accounts (firebase-fn-...).
2. cloudresourcemanager.googleapis.com: To inspect and update project IAM policies.

If iam.googleapis.com is disabled on the target Google Cloud project, deployments previously passed the prepare phase, uploaded source code to Cloud Storage, and failed asynchronously 2–3 minutes later inside Cloud Build with an obscure error (generic::permission_denied: Identity and Access Management (IAM) API is disabled).

Rather than adding these APIs to STANDARD_APIS (which would auto-prompt enablement for all function deployments regardless of whether declarative security is used), this PR implements a lean fail-fast pre-flight check:

1. Pre-Flight Validation (checkDeclarativeSecurityApisEnabled):

   • In discoverSecurityDetails(), checks that both iam.googleapis.com and cloudresourcemanager.googleapis.com are enabled on the project using ensureApiEnabled.check().
   • If either API is disabled, aborts immediately in Phase 4 ({ exit: 1 }) before creating service accounts or packaging code.
   • Provides an actionable error message containing:
     • The exact, copy-pasteable CLI command: gcloud services enable <apis> --project <projectId>
     • Direct Google Cloud Console enablement URLs (via ensureApiEnabled.enableApiURI(projectId, api)) for users without gcloud or who need to forward the link to their project owner.

2. Least-Privilege & CI/CD Safety (Fail-Open):

   • Catches errors during the Service Usage inspection check (e.g. if a restricted CI/CD deployment service account lacks serviceusage.services.get) and fails open with logger.debug. This ensures deployment-only credentials that lack Service Usage read access are not falsely blocked when the APIs are actually enabled.

3. Guards & Unenrollment Safety:

   • Standard functions (no requiresRole) bypass this check entirely.
   • Codebases unenrolling / opting out from declarative security (!requiredRoles && existingManagedSA) also bypass the check, ensuring users removing declarative security are never blocked.

---

Scenarios Tested

• Unit Tests (src/deploy/functions/prepare.spec.ts):
  • ✔ Both iam.googleapis.com and cloudresourcemanager.googleapis.com disabled: asserts unified error message, combined gcloud command, and console URLs.
  • ✔ Only iam.googleapis.com disabled: asserts single-API isolation.
  • ✔ Only cloudresourcemanager.googleapis.com disabled: asserts single-API isolation.
  • ✔ Non-declarative codebase: asserts API enablement checks are completely skipped.
  • ✔ Restricted caller permissions: asserts that a 403 on serviceusage.services.get fails open and does not block deployment.
  • ✔ Unenrollment from declarative security: asserts unenrollment succeeds even if security APIs are disabled.
    (All 89 tests passing)

---

Sample Commands & Error Output

When required APIs are disabled:

$ firebase deploy --only functions:firestore-bigquery-export

Error: Cannot deploy functions with declarative security in codebase "firestore-bigquery-export". The following required Google Cloud API(s) are not enabled on project my-project:
  - iam.googleapis.com

Declarative security requires these APIs to provision and configure managed service accounts and IAM roles.
To enable them, run:

  gcloud services enable iam.googleapis.com --project my-project

Or ask a project owner to enable them in the Google Cloud Console:
  - iam.googleapis.com: https://console.cloud.google.com/apis/library/iam.googleapis.com?project=my-project

[gemini-code-assist]

Code Review

This pull request introduces a fail-fast mechanism that checks if the required Google Cloud APIs (IAM and Cloud Resource Manager) are enabled before deploying functions with declarative security, throwing actionable errors if they are not. The review feedback is highly constructive and identifies critical improvements: handling potential permission errors during API checks to avoid blocking users with restricted permissions, mapping service hostnames to friendly names to correctly match legacy GCP error messages, and adding a unit test to verify this mapping.

[ajperel]

A bunch of minor stuff but overall pretty good. Thanks for simplifying.

[ajperel]

Looks great. Thanks for the fast iteration on this.