PM-4952: Allow project member BA detail access

README.md

@@ -7,7 +7,7 @@
 - Endpoints:
   - `GET /billing-accounts` 
   - `POST /billing-accounts` 
-  - `GET /billing-accounts/:billingAccountId` (includes locked/consumed arrays + budget totals; line items expose `amount`, `date`, `externalId`, `externalType`, `externalName`, and `challengeId` only for challenge compatibility; copilot, Project Manager, and Talent Manager callers only receive line items for projects they belong to; copilot-only callers receive `memberPaymentsRemaining` and per-line-item `memberPaymentAmount` instead of raw `markup`)
+  - `GET /billing-accounts/:billingAccountId` (includes locked/consumed arrays + budget totals; line items expose `amount`, `date`, `externalId`, `externalType`, `externalName`, and `challengeId` only for challenge compatibility; copilot, project-scoped, and Talent Manager callers only receive line items for projects they belong to; copilot-only callers receive `memberPaymentsRemaining` and per-line-item `memberPaymentAmount` instead of raw `markup`)
   - `GET /billing-accounts/users/:userId` (list billing accounts accessible by the given Topcoder user ID — resolved via Salesforce resource object)
   - `PATCH /billing-accounts/:billingAccountId`
   - `PATCH /billing-accounts/:billingAccountId/lock-amount` (challenge-only typed reference; non-negative amount; 0 amount = unlock; rejects insufficient remaining funds)
@@ -27,16 +27,19 @@
 - Billing-account management endpoints accept `administrator`, `Talent Manager`,
   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`. On `GET /billing-accounts/:billingAccountId`,
-  they can read billing accounts granted to their own user id or assigned to
-  projects they belong to.
+  The detail endpoint additionally accepts `Topcoder User` so project-member
+  callers from Work can be authorized by project membership.
+  Project-scoped billing-account readers are restricted to billing accounts
+  granted to their own 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 active projects where they hold
+  a management or copilot project role.
   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
   responses for copilots also include per-line-item `memberPaymentAmount` values
   that remove the markup fee from locked and consumed amounts. On detail
-  responses, copilot, Project Manager, and Talent
+  responses, copilot, project-scoped, and Talent
   Manager callers only receive locked/consumed line items whose challenge or
   engagement project maps to an active `project_members` row for their user id.
   Line items with unresolved project access are omitted for those callers.

src/auth/constants.ts

@@ -15,5 +15,6 @@ export const ADMIN_ROLE = "administrator";
 export const COPILOT_ROLE = "copilot";
 export const PROJECT_MANAGER_ROLE = "Project Manager";
 export const TOPCODER_PROJECT_MANAGER_ROLE = "Topcoder Project Manager";
+export const TOPCODER_USER_ROLE = "Topcoder User";
 export const TALENT_MANAGER_ROLE = "Talent Manager";
 export const TOPCODER_TALENT_MANAGER_ROLE = "Topcoder Talent Manager";

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

@@ -30,6 +30,7 @@ import {
   PROJECT_MANAGER_ROLE,
   TALENT_MANAGER_ROLE,
   TOPCODER_PROJECT_MANAGER_ROLE,
+  TOPCODER_USER_ROLE,
   TOPCODER_TALENT_MANAGER_ROLE,
 } from "../auth/constants";
 import type { Request } from "express";
@@ -58,6 +59,11 @@ const BILLING_ACCOUNT_PROJECT_READ_ROLES = [
   TOPCODER_PROJECT_MANAGER_ROLE,
 ];
 
+const BILLING_ACCOUNT_DETAIL_READ_ROLES = [
+  ...BILLING_ACCOUNT_PROJECT_READ_ROLES,
+  TOPCODER_USER_ROLE,
+];
+
 const BILLING_ACCOUNT_MANAGE_ROLES = [
   ADMIN_ROLE,
   TALENT_MANAGER_ROLE,
@@ -167,14 +173,14 @@ export class BillingAccountsController {
 
   @Get(":billingAccountId")
   @UseGuards(RolesGuard, ScopesGuard)
-  @Roles(...BILLING_ACCOUNT_PROJECT_READ_ROLES)
+  @Roles(...BILLING_ACCOUNT_DETAIL_READ_ROLES)
   @Scopes(SCOPES.READ_BA, SCOPES.ALL_BA)
   @ApiOperation(
     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 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,
+        "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 and Topcoder User project members can read billing accounts granted to them or assigned to projects where they hold an allowed project billing-account role. Copilot, Project Manager, Topcoder User, 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_DETAIL_READ_ROLES,
       m2mScopes: [SCOPES.READ_BA, SCOPES.ALL_BA],
     }),
   )

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

@@ -29,6 +29,7 @@ import {
   PROJECT_MANAGER_ROLE,
   TALENT_MANAGER_ROLE,
   TOPCODER_PROJECT_MANAGER_ROLE,
+  TOPCODER_USER_ROLE,
   TOPCODER_TALENT_MANAGER_ROLE,
 } from "../auth/constants";
 
@@ -50,15 +51,17 @@ const UNRESTRICTED_BILLING_ACCOUNT_READ_ROLES = [
   TOPCODER_TALENT_MANAGER_ROLE,
 ];
 
-const RESTRICTED_PROJECT_MANAGER_READ_ROLES = [
+const PROJECT_SCOPED_BILLING_ACCOUNT_READ_ROLES = [
   PROJECT_MANAGER_ROLE,
   TOPCODER_PROJECT_MANAGER_ROLE,
+  TOPCODER_USER_ROLE,
 ];
 
 const PROJECT_ACCESS_FILTERED_LINE_ITEM_ROLES = [
   COPILOT_ROLE,
   PROJECT_MANAGER_ROLE,
   TOPCODER_PROJECT_MANAGER_ROLE,
+  TOPCODER_USER_ROLE,
   TALENT_MANAGER_ROLE,
   TOPCODER_TALENT_MANAGER_ROLE,
 ];
@@ -187,26 +190,25 @@ function getNormalizedAuthUserId(
 }
 
 /**
- * Returns the enforced user id for restricted Project Manager billing-account
- * reads.
+ * Returns the enforced user id for project-scoped billing-account reads.
  *
  * `undefined` means the caller keeps unrestricted read behavior. `null`
- * indicates a restricted Project Manager caller without a usable `userId`,
+ * indicates a restricted project-scoped caller without a usable `userId`,
  * which should be treated as no accessible accounts.
  *
  * @param authUser Authenticated caller context from `req.authUser`.
  * @returns Enforced user id, `null`, or `undefined`.
  */
-function resolveRestrictedProjectManagerUserId(
+function resolveProjectScopedBillingAccountReadUserId(
   authUser?: BillingAccountsAuthUser,
 ): string | null | undefined {
   const normalizedRoles = getNormalizedAuthUserRoles(authUser);
-  const hasRestrictedProjectManagerRole =
-    RESTRICTED_PROJECT_MANAGER_READ_ROLES.some((role) =>
+  const hasProjectScopedBillingAccountReadRole =
+    PROJECT_SCOPED_BILLING_ACCOUNT_READ_ROLES.some((role) =>
       normalizedRoles.includes(role.toLowerCase()),
     );
 
-  if (!hasRestrictedProjectManagerRole) {
+  if (!hasProjectScopedBillingAccountReadRole) {
     return undefined;
   }
 
@@ -224,10 +226,10 @@ function resolveRestrictedProjectManagerUserId(
 /**
  * Returns the user id to use for project-level line-item filtering.
  *
- * Administrators keep full line-item visibility. Copilots, Project Managers,
- * and Talent Managers only receive line items whose underlying challenge or
- * engagement project can be resolved to an active project membership for their
- * user id.
+ * Administrators keep full line-item visibility. Copilots, project-scoped
+ * billing-account readers, and Talent Managers only receive line items whose
+ * underlying challenge or engagement project can be resolved to an active
+ * project membership for their user id.
  *
  * @param authUser Authenticated caller context from `req.authUser`.
  * @returns User id to filter by, `null` when missing, or `undefined` when no
@@ -313,7 +315,7 @@ export class BillingAccountsService {
   /**
    * Lists billing accounts with optional filtering, sorting, and pagination.
    *
-   * Project Manager callers are constrained to billing accounts granted to
+   * Project-scoped callers are constrained to billing accounts granted to
    * their own `userId`, regardless of an explicit `userId` query override.
    *
    * @param q Query filters and pagination controls.
@@ -335,10 +337,10 @@ export class BillingAccountsService {
       sortBy,
       sortOrder = "asc",
     } = q;
-    const restrictedProjectManagerUserId =
-      resolveRestrictedProjectManagerUserId(authUser);
+    const projectScopedBillingAccountReadUserId =
+      resolveProjectScopedBillingAccountReadUserId(authUser);
 
-    if (restrictedProjectManagerUserId === null) {
+    if (projectScopedBillingAccountReadUserId === null) {
       return {
         page,
         perPage,
@@ -353,8 +355,10 @@ export class BillingAccountsService {
       ...(status ? { status } : {}),
     };
 
-    if (restrictedProjectManagerUserId) {
-      where.accessGrants = { some: { userId: restrictedProjectManagerUserId } };
+    if (projectScopedBillingAccountReadUserId) {
+      where.accessGrants = {
+        some: { userId: projectScopedBillingAccountReadUserId },
+      };
     } else if (userId) {
       where.accessGrants = { some: { userId } };
     }
@@ -477,16 +481,17 @@ export class BillingAccountsService {
    * Fetches a single billing account, its normalized budget line items, and
    * budget aggregates.
    *
-   * 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;
-   * unresolved project access hides the line item.
+   * Project-scoped callers can read billing accounts granted to their own
+   * `userId`, or billing accounts assigned to a project where they hold an
+   * allowed project billing-account role. 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-scoped, 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.
    * @param authUser Authenticated caller context from `req.authUser`.
@@ -496,36 +501,36 @@ export class BillingAccountsService {
    * caller does not have access to it.
    */
   async get(billingAccountId: number, authUser?: BillingAccountsAuthUser) {
-    const restrictedProjectManagerUserId =
-      resolveRestrictedProjectManagerUserId(authUser);
+    const projectScopedBillingAccountReadUserId =
+      resolveProjectScopedBillingAccountReadUserId(authUser);
     const include = {
       client: true,
       lockedAmounts: true,
       consumedAmounts: true,
     };
     let ba =
-      restrictedProjectManagerUserId === undefined
+      projectScopedBillingAccountReadUserId === undefined
         ? await this.prisma.billingAccount.findUnique({
             where: { id: billingAccountId },
             include,
           })
-        : restrictedProjectManagerUserId === null
+        : projectScopedBillingAccountReadUserId === null
           ? null
           : await this.prisma.billingAccount.findFirst({
               where: {
                 id: billingAccountId,
                 accessGrants: {
-                  some: { userId: restrictedProjectManagerUserId },
+                  some: { userId: projectScopedBillingAccountReadUserId },
                 },
               },
               include,
             });
 
-    if (!ba && restrictedProjectManagerUserId) {
+    if (!ba && projectScopedBillingAccountReadUserId) {
       const hasProjectBillingAccountAccess =
         await this.externalBudgetEntryLookup.hasProjectBillingAccountAccess(
           billingAccountId,
-          restrictedProjectManagerUserId,
+          projectScopedBillingAccountReadUserId,
         );
 
       if (hasProjectBillingAccountAccess) {

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

@@ -36,6 +36,16 @@ interface ProjectBillingAccountAccessRow {
   hasAccess: boolean;
 }
 
+const PROJECT_BILLING_ACCOUNT_DETAIL_ROLES = [
+  "manager",
+  "account_manager",
+  "account_executive",
+  "project_manager",
+  "program_manager",
+  "solution_architect",
+  "copilot",
+];
+
 /**
  * Resolves budget-entry external metadata from service-owned persistence stores.
  *
@@ -193,15 +203,17 @@ export class ExternalBudgetEntryLookupService implements OnModuleDestroy {
   /**
    * 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.
+   * Project-scoped Work users may open billing-account details from 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 management/copilot 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`.
+   * project assigned to the billing account with an allowed billing-account
+   * detail role; otherwise `false`.
    */
   async hasProjectBillingAccountAccess(
     billingAccountId: number,
@@ -233,6 +245,9 @@ export class ExternalBudgetEntryLookupService implements OnModuleDestroy {
           )}
             AND project."deletedAt" IS NULL
             AND project_member."userId" = ${BigInt(normalizedUserId)}
+            AND project_member."role"::text IN (${Prisma.join(
+              PROJECT_BILLING_ACCOUNT_DETAIL_ROLES,
+            )})
             AND project_member."deletedAt" IS NULL
           LIMIT 1
         `,