PM-4952: Allow project managers to open project billing accounts

What was broken

Project Managers who could access a Work project could still receive a not found response from GET /billing-accounts/:billingAccountId when the billing account was not present in BillingAccountAccess.

Root cause (if identifiable)

The billing-account detail endpoint only checked legacy billing-account access grants for restricted Project Manager reads. Work project pages rely on project membership and the project's billingAccountId, so missing imported legacy grants blocked project-level billing-account access.

What was changed

Added a Projects DB membership fallback for restricted Project Manager detail reads. When no direct billing-account grant exists, the API checks for a non-deleted project with the requested billingAccountId and a non-deleted project_members row for the caller before loading details.

Updated Swagger and README authorization documentation to describe the project-membership fallback.

Any added/updated tests

No automated tests were added because billing-accounts-api-v6 does not define a test script. Validation was performed with pnpm lint and pnpm build; pnpm test reports that the test script is missing.

Author: jmgasper

README.md

@@ -28,7 +28,9 @@
   and `Topcoder Talent Manager` JWT roles; read-only billing-account lookups
   also continue to allow `copilot`, `Project Manager`, and `Topcoder Project Manager`.
   Project Managers are restricted to billing accounts granted to their own
-  user id on `GET /billing-accounts` and `GET /billing-accounts/:billingAccountId`.
+  user id on `GET /billing-accounts`. On `GET /billing-accounts/:billingAccountId`,
+  they can read billing accounts granted to their own user id or assigned to
+  projects they belong to.
   Copilot-only callers receive billing-account responses with `markup` omitted
   and `memberPaymentsRemaining` derived server-side as total remaining minus
   the total remaining markup amount. Billing-account detail

src/billing-accounts/billing-accounts.controller.ts

@@ -173,7 +173,7 @@ export class BillingAccountsController {
     buildOperationDoc({
       summary: "Get a billing account",
       description:
-        "Fetch a billing account by its identifier, including budget, client data, and normalized locked/consumed line items. Line items include amount, date, externalId, externalType, externalName, and challengeId only for legacy challenge compatibility. Project Managers can read only billing accounts granted to them. Copilot, Project Manager, and Talent Manager callers only receive locked/consumed line items for projects they belong to. Copilot-only callers receive copilot-safe budget data without the raw markup field, including memberPaymentsRemaining and per-line-item memberPaymentAmount values.",
+        "Fetch a billing account by its identifier, including budget, client data, and normalized locked/consumed line items. Line items include amount, date, externalId, externalType, externalName, and challengeId only for legacy challenge compatibility. Project Managers can read billing accounts granted to them or assigned to projects they belong to. Copilot, Project Manager, and Talent Manager callers only receive locked/consumed line items for projects they belong to. Copilot-only callers receive copilot-safe budget data without the raw markup field, including memberPaymentsRemaining and per-line-item memberPaymentAmount values.",
       jwtRoles: BILLING_ACCOUNT_PROJECT_READ_ROLES,
       m2mScopes: [SCOPES.READ_BA, SCOPES.ALL_BA],
     }),

src/billing-accounts/billing-accounts.service.ts

@@ -187,8 +187,8 @@ function getNormalizedAuthUserId(
 }
 
 /**
- * Returns the enforced access-grant user id for restricted Project Manager
- * billing-account reads.
+ * Returns the enforced user id for restricted Project Manager billing-account
+ * reads.
  *
  * `undefined` means the caller keeps unrestricted read behavior. `null`
  * indicates a restricted Project Manager caller without a usable `userId`,
@@ -477,14 +477,15 @@ export class BillingAccountsService {
    * Fetches a single billing account, its normalized budget line items, and
    * budget aggregates.
    *
-   * Project Manager callers can read only billing accounts granted to their own
-   * `userId`. Missing access is surfaced as not found to avoid leaking account
-   * existence. Locked and consumed line items expose `amount`, `date`,
-   * `externalId`, `externalType`, and `externalName`; challenge rows also expose
-   * the deprecated `challengeId` compatibility alias. Copilot-only callers also
+   * Project Manager callers can read billing accounts granted to their own
+   * `userId`, or billing accounts assigned to a project they belong to. Missing
+   * access is surfaced as not found to avoid leaking account existence. Locked
+   * and consumed line items expose `amount`, `date`, `externalId`,
+   * `externalType`, and `externalName`; challenge rows also expose the
+   * deprecated `challengeId` compatibility alias. Copilot-only callers also
    * receive `memberPaymentAmount` on each line item so the UI can show the
-   * payment value without exposing markup. Copilot, Project Manager, and Talent
-   * Manager callers only receive line items for projects they belong to;
+   * payment value without exposing markup. Copilot, Project Manager, and
+   * Talent Manager callers only receive line items for projects they belong to;
    * unresolved project access hides the line item.
    *
    * @param billingAccountId Billing-account identifier.
@@ -502,7 +503,7 @@ export class BillingAccountsService {
       lockedAmounts: true,
       consumedAmounts: true,
     };
-    const ba =
+    let ba =
       restrictedProjectManagerUserId === undefined
         ? await this.prisma.billingAccount.findUnique({
             where: { id: billingAccountId },
@@ -520,6 +521,21 @@ export class BillingAccountsService {
               include,
             });
 
+    if (!ba && restrictedProjectManagerUserId) {
+      const hasProjectBillingAccountAccess =
+        await this.externalBudgetEntryLookup.hasProjectBillingAccountAccess(
+          billingAccountId,
+          restrictedProjectManagerUserId,
+        );
+
+      if (hasProjectBillingAccountAccess) {
+        ba = await this.prisma.billingAccount.findUnique({
+          where: { id: billingAccountId },
+          include,
+        });
+      }
+    }
+
     if (!ba)
       throw new NotFoundException(
         `Billing account with ID ${billingAccountId} not found`,

src/billing-accounts/external-budget-entry-lookup.service.ts

@@ -32,6 +32,10 @@ interface ProjectAccessRow {
   projectId: string;
 }
 
+interface ProjectBillingAccountAccessRow {
+  hasAccess: boolean;
+}
+
 /**
  * Resolves budget-entry external metadata from service-owned persistence stores.
  *
@@ -186,6 +190,63 @@ export class ExternalBudgetEntryLookupService implements OnModuleDestroy {
     return accessibleReferenceKeys;
   }
 
+  /**
+   * Checks whether a user belongs to a project using a billing account.
+   *
+   * Project Managers may open billing-account details from Work project pages
+   * even when the legacy billing-account resource grant was not imported for
+   * that account. This lookup validates access against non-deleted projects
+   * and non-deleted project membership in projects-api-v6.
+   *
+   * @param billingAccountId Topcoder billing-account id from the detail route.
+   * @param userId Topcoder user id from the authenticated caller.
+   * @returns `true` when the user has non-deleted project membership for a
+   * project assigned to the billing account; otherwise `false`.
+   */
+  async hasProjectBillingAccountAccess(
+    billingAccountId: number,
+    userId: string,
+  ): Promise<boolean> {
+    const normalizedBillingAccountId =
+      this.normalizeNumericTextId(billingAccountId);
+    const normalizedUserId = this.normalizeNumericTextId(userId);
+
+    if (!normalizedBillingAccountId || !normalizedUserId) {
+      return false;
+    }
+
+    const client = this.getProjectsClient();
+
+    if (!client) {
+      return false;
+    }
+
+    try {
+      const rows = await client.$queryRaw<ProjectBillingAccountAccessRow[]>(
+        Prisma.sql`
+          SELECT true AS "hasAccess"
+          FROM projects project
+          INNER JOIN project_members project_member
+            ON project_member."projectId" = project."id"
+          WHERE project."billingAccountId" = ${BigInt(
+            normalizedBillingAccountId,
+          )}
+            AND project."deletedAt" IS NULL
+            AND project_member."userId" = ${BigInt(normalizedUserId)}
+            AND project_member."deletedAt" IS NULL
+          LIMIT 1
+        `,
+      );
+
+      return rows.some((row) => row.hasAccess);
+    } catch (error) {
+      this.logger.warn(
+        `Failed to resolve project billing-account access: ${this.getErrorMessage(error)}`,
+      );
+      return false;
+    }
+  }
+
   /**
    * Disconnects optional lookup clients created for external stores.
    *
@@ -555,7 +616,7 @@ export class ExternalBudgetEntryLookupService implements OnModuleDestroy {
     this.projectsClient = this.createOptionalClient(
       process.env.PROJECTS_DB_URL || process.env.PROJECT_DB_URL,
       "PROJECTS_DB_URL or PROJECT_DB_URL",
-      "project-access filtering will hide line items whose access cannot be resolved.",
+      "project-access checks will hide line items and deny project-based billing-account access when access cannot be resolved.",
     );
 
     return this.projectsClient;