feat: add IAM and Resource Manager utilities for service accounts (PR 2)

[inlined]

Description

This is PR 2 in the requiresRole PR chain.
It implements low-level Cloud IAM and Resource Manager API utilities:

1. generateManagedServiceAccountName for collision-resolved SA names.
2. computeRolesEtag for salt-and-hash role etag calculations.
3. addServiceAccountRoles and removeServiceAccountRoles to mutate project IAM policies.
4. Static cache of standard roles in knownRoles.json to prevent API roundtrips.

Scenarios Tested

• Run unit tests: npx mocha src/gcp/iam.spec.ts src/gcp/resourceManager.spec.ts
• Run npm run build & npm run lint

Sample Commands

N/A

[gemini-code-assist]

Code Review

This pull request introduces several IAM utility functions, including getRoleName, generateManagedServiceAccountName, computeRolesEtag, removeServiceAccountRoles, and getServiceAccountRoles, along with a local map of known roles and corresponding unit tests. The review feedback focuses on improving type safety and robustness: specifically, avoiding the use of any by utilizing the getErrStatus utility, using a default import for the JSON roles map, adhering to strict null checks for role lookups, and defensively handling potentially undefined bindings in the project policy to prevent runtime crashes.

[gemini-code-assist]

Avoid using any as an escape hatch. Instead, use the getErrStatus utility from ../error to safely check the error status in a type-safe manner.

Suggested change

	} catch (err: any) {
	if (err.status === 404) {
	return accountId;
	}
	throw err;
	}
	} catch (err) {
	if (getErrStatus(err) === 404) {
	return accountId;
	}
	throw err;
	}

References

1. Never use any or unknown as an escape hatch. Define proper interfaces/types or use type guards. ^(link)

[gemini-code-assist]

Import getErrStatus from ../error to use it for safe error status checking in generateManagedServiceAccountName without resorting to any.

Suggested change

	import { FirebaseError } from "../error";
	import { FirebaseError, getErrStatus } from "../error";

[gemini-code-assist]

Use a default import for the JSON file instead of a namespace import. When using import * as knownRoles, the imported object is a module namespace containing a default property (under esModuleInterop), which causes type mismatch issues when assigning it to Record<string, string>.

Suggested change

	import * as knownRoles from "./knownRoles.json";
	import knownRoles from "./knownRoles.json";

[gemini-code-assist]

Type the map as Record<string, string | undefined> to adhere to strict null checks. Since not all arbitrary strings are valid keys in the knownRoles map, accessing map[role] can return undefined.

Suggested change

	const map: Record<string, string> = knownRoles;
	const map: Record<string, string | undefined> = knownRoles;

References

1. Use strict null checks and handle undefined/null explicitly. ^(link)

[gemini-code-assist]

Defensively initialize projectPolicy.bindings to an empty array if it is undefined. GCP's getIamPolicy API can return a policy without the bindings field if no bindings exist, which would cause a runtime crash (TypeError: Cannot read properties of undefined (reading 'length')) when attempting to iterate over it.

Suggested change

	const projectPolicy = await getIamPolicy(projectId);
	const memberName = `serviceAccount:${serviceAccountEmail}`;
	const projectPolicy = await getIamPolicy(projectId);
	projectPolicy.bindings = projectPolicy.bindings || [];
	const memberName = `serviceAccount:${serviceAccountEmail}`;

[gemini-code-assist]

Defensively handle the case where projectPolicy.bindings is undefined to prevent a potential runtime crash when iterating over the bindings.

Suggested change

	for (const binding of projectPolicy.bindings) {
	if (binding.members.includes(memberName)) {
	roles.push(binding.role);
	}
	}
	for (const binding of projectPolicy.bindings || []) {
	if (binding.members.includes(memberName)) {
	roles.push(binding.role);
	}
	}