feat: Regional Access Boundary Changes

packages/google-auth-library-nodejs/src/auth/authclient.ts

@@ -21,10 +21,10 @@ import {log as makeLog} from 'google-logging-utils';
 
 import {PRODUCT_NAME, USER_AGENT} from '../shared.cjs';
 import {
-  isTrustBoundaryEnabled,
-  NoOpEncodedLocations,
-  TrustBoundaryData,
-} from './trustboundary';
+  isRegionalAccessBoundaryEnabled,
+  RegionalAccessBoundaryData,
+  RegionalAccessBoundaryManager,
+} from './regionalaccessboundary';
 
 /**
  * An interface for enforcing `fetch`-type compliance.
@@ -237,8 +237,8 @@ export abstract class AuthClient
   eagerRefreshThresholdMillis = DEFAULT_EAGER_REFRESH_THRESHOLD_MILLIS;
   forceRefreshOnFailure = false;
   universeDomain = DEFAULT_UNIVERSE;
-  trustBoundaryEnabled: boolean;
-  trustBoundary?: TrustBoundaryData | null;
+  regionalAccessBoundaryEnabled: boolean;
+  protected regionalAccessBoundaryManager: RegionalAccessBoundaryManager;
 
   /**
    * Symbols that can be added to GaxiosOptions to specify the method name that is
@@ -261,12 +261,17 @@ export abstract class AuthClient
     this.quotaProjectId = options.get('quota_project_id');
     this.credentials = options.get('credentials') ?? {};
     this.universeDomain = options.get('universe_domain') ?? DEFAULT_UNIVERSE;
-    this.trustBoundaryEnabled = isTrustBoundaryEnabled();
-    this.trustBoundary = null;
+    this.regionalAccessBoundaryEnabled = isRegionalAccessBoundaryEnabled();
 
     // Shared client options
     this.transporter = opts.transporter ?? new Gaxios(opts.transporterOptions);
 
+    this.regionalAccessBoundaryManager = new RegionalAccessBoundaryManager({
+      transporter: this.transporter,
+      getLookupUrl: async () => this.getRegionalAccessBoundaryUrl(),
+      isUniverseDomainDefault: () => this.universeDomain === DEFAULT_UNIVERSE,
+    });
+
     if (options.get('useAuthRequestParameters') !== false) {
       this.transporter.interceptors.request.add(
         AuthClient.DEFAULT_REQUEST_INTERCEPTOR,
@@ -371,14 +376,17 @@ export abstract class AuthClient
   }>;
 
   /**
-   * Constructs the trust boundary lookup URL for the client.
+   * Returns the regional access boundary lookup URL for the current client.
+   * This method is intended for internal use by the RegionalAccessBoundaryManager
+   * and should not be called directly by users.
    *
-   * @return The trust boundary URL string, or `null` if the client type
-   * does not support trust boundaries.
+   * @return The regional access boundary URL string, or `null` if the client type
+   * does not support regional access boundaries.
    * @throws {Error} If the URL cannot be constructed for a compatible client,
    * for instance, if a required property like a service account email is missing.
+   * @internal
    */
-  protected async getTrustBoundaryUrl(): Promise<string | null> {
+  public async getRegionalAccessBoundaryUrl(): Promise<string | null> {
     return null;
   }
 
@@ -389,6 +397,22 @@ export abstract class AuthClient
     this.credentials = credentials;
   }
 
+  /**
+   * Returns the current regional access boundary data.
+   * @internal
+   */
+  getRegionalAccessBoundary(): RegionalAccessBoundaryData | null {
+    return this.regionalAccessBoundaryManager.data;
+  }
+
+  /**
+   * Returns the current regional access boundary cooldown time in milliseconds.
+   * @internal
+   */
+  getRegionalAccessBoundaryCooldownTime(): number {
+    return this.regionalAccessBoundaryManager.cooldownTime;
+  }
+
   /**
    * Append additional headers, e.g., x-goog-user-project, shared across the
    * classes inheriting AuthClient. This method should be used by any method
@@ -408,17 +432,28 @@ export abstract class AuthClient
       headers.set('x-goog-user-project', this.quotaProjectId);
     }
 
-    if (this.trustBoundaryEnabled && this.trustBoundary) {
-      //Empty header sent in case trust-boundary has no-op encoded location.
-      headers.set(
-        'x-allowed-locations',
-        this.trustBoundary.encodedLocations === NoOpEncodedLocations
-          ? ''
-          : this.trustBoundary.encodedLocations,
+    return headers;
+  }
+
+  /**
+   * Applies regional access boundary rules to the provided headers.
+   * This includes adding the x-allowed-locations header and triggering
+   * a background refresh if needed.
+   * @param headers The headers to update.
+   * @param url Optional destination URL of the request. If missing, assumed global.
+   */
+  protected applyRegionalAccessBoundary(
+    headers: Headers,
+    url?: string | URL,
+  ): void {
+    const rabHeader =
+      this.regionalAccessBoundaryManager.getRegionalAccessBoundaryHeader(
+        url,
+        headers,
       );
+    if (rabHeader) {
+      headers.set('x-allowed-locations', rabHeader);
     }
-
-    return headers;
   }
 
   /**
@@ -446,7 +481,7 @@ export abstract class AuthClient
       target.set('authorization', authorizationHeader);
     }
 
-    if (xGoogAllowedLocs || xGoogAllowedLocs === '') {
+    if (xGoogAllowedLocs) {
       target.set('x-allowed-locations', xGoogAllowedLocs);
     }
 
@@ -588,87 +623,6 @@ export abstract class AuthClient
     };
   }
 
-  /**
-   * Refreshes trust boundary data for an authenticated client.
-   * Handles caching checks and potential fallbacks.
-   * @param tokens The refreshed credentials containing access token to call the trust boundary endpoint.
-   * @returns A Promise resolving to TrustBoundaryData or empty-string for no-op trust boundaries.
-   * @throws {Error} If the request fails and there is no cache available.
-   */
-  protected async refreshTrustBoundary(
-    tokens: Credentials,
-  ): Promise<TrustBoundaryData | null> {
-    if (!this.trustBoundaryEnabled) {
-      return null;
-    }
-
-    if (this.universeDomain !== DEFAULT_UNIVERSE) {
-      // Skipping check for non-default universe domain as this feature is only supported in GDU
-      return null;
-    }
-
-    const cachedTB = this.trustBoundary;
-    if (cachedTB && cachedTB.encodedLocations === NoOpEncodedLocations) {
-      return cachedTB;
-    }
-
-    const trustBoundaryUrl = await this.getTrustBoundaryUrl();
-    if (!trustBoundaryUrl) {
-      return null;
-    }
-
-    const accessToken = tokens.access_token;
-
-    if (!accessToken || this.isExpired(tokens)) {
-      throw new Error(
-        'TrustBoundary: Error calling lookup endpoint without valid access token',
-      );
-    }
-
-    const headers = this.addSharedMetadataHeaders(
-      new Headers({
-        //we can directly pass the access_token as the trust boundaries are always fetched after token refresh
-        authorization: 'Bearer ' + accessToken,
-      }),
-    );
-
-    const opts: GaxiosOptions = {
-      ...{
-        retry: true,
-        retryConfig: {
-          httpMethodsToRetry: ['GET'],
-        },
-      },
-      headers,
-      url: trustBoundaryUrl,
-    };
-
-    try {
-      const {data: trustBoundaryData} =
-        // Use the transporter directly here. A standard `client.request` would
-        // re-trigger a token refresh, creating an infinite loop.
-        await this.transporter.request<TrustBoundaryData>(opts);
-
-      if (!trustBoundaryData.encodedLocations) {
-        throw new Error(
-          'TrustBoundary: Malformed response from lookup endpoint.',
-        );
-      }
-
-      return trustBoundaryData;
-    } catch (error) {
-      if (this.trustBoundary) {
-        return this.trustBoundary; // return cached tb if call to lookup fails
-      }
-      throw new Error(
-        'TrustBoundary: Failure while getting trust boundaries:',
-        {
-          cause: error,
-        },
-      );
-    }
-  }
-
   /**
    * Returns whether the provided credentials are expired or will expire within
    * eagerRefreshThresholdMillismilliseconds.

packages/google-auth-library-nodejs/src/auth/baseexternalclient.ts

@@ -40,7 +40,7 @@ import {
   SERVICE_ACCOUNT_LOOKUP_ENDPOINT,
   WORKFORCE_LOOKUP_ENDPOINT,
   WORKLOAD_LOOKUP_ENDPOINT,
-} from './trustboundary';
+} from './regionalaccessboundary';
 
 /**
  * The required token exchange grant_type: rfc8693#section-2.1
@@ -424,11 +424,12 @@ export abstract class BaseExternalAccountClient extends AuthClient {
    * The result has the form:
    * { authorization: 'Bearer <access_token_value>' }
    */
-  async getRequestHeaders(): Promise<Headers> {
+  async getRequestHeaders(url?: string | URL): Promise<Headers> {
     const accessTokenResponse = await this.getAccessToken();
     const headers = new Headers({
       authorization: `Bearer ${accessTokenResponse.token}`,
     });
+    this.applyRegionalAccessBoundary(headers, url);
     return this.addSharedMetadataHeaders(headers);
   }
 
@@ -507,13 +508,14 @@ export abstract class BaseExternalAccountClient extends AuthClient {
     reAuthRetried = false,
   ): Promise<GaxiosResponse<T>> {
     let response: GaxiosResponse;
+    const requestOpts = {...opts};
     try {
-      const requestHeaders = await this.getRequestHeaders();
-      opts.headers = Gaxios.mergeHeaders(opts.headers);
+      const requestHeaders = await this.getRequestHeaders(opts.url);
+      requestOpts.headers = Gaxios.mergeHeaders(requestOpts.headers);
 
-      this.applyHeadersFromSource(opts.headers, requestHeaders);
+      this.applyHeadersFromSource(requestOpts.headers, requestHeaders);
 
-      response = await this.transporter.request<T>(opts);
+      response = await this.transporter.request<T>(requestOpts);
     } catch (e) {
       const res = (e as GaxiosError).response;
       if (res) {
@@ -624,7 +626,6 @@ export abstract class BaseExternalAccountClient extends AuthClient {
     Object.assign(this.credentials, this.cachedAccessToken);
     delete (this.credentials as CredentialsWithResponse).res;
 
-    this.trustBoundary = await this.refreshTrustBoundary(this.credentials);
     // Trigger tokens event to notify external listeners.
     this.emit('tokens', {
       refresh_token: null,
@@ -718,42 +719,53 @@ export abstract class BaseExternalAccountClient extends AuthClient {
     return this.tokenUrl;
   }
 
-  protected async getTrustBoundaryUrl(): Promise<string> {
+  /**
+   * Returns the regional access boundary lookup URL for the external account.
+   * This implementation constructs the URL based on the audience of the
+   * workforce or workload pool. If the client is configured for service account
+   * impersonation, it uses the target service account email to generate
+   * the lookup endpoint.
+   *
+   * @return The regional access boundary URL string.
+   * @internal
+   */
+  public async getRegionalAccessBoundaryUrl(): Promise<string> {
     if (this.serviceAccountImpersonationUrl) {
-      // When impersonating a service account, the trust boundary is determined
+      // When impersonating a service account, the regional access boundary is determined
       // by the security policies of the target service account.
       const email = this.getServiceAccountEmail();
       if (!email) {
         throw new Error(
-          `TrustBoundary: A service account email is required for trust boundary lookups but could not be determined from the serviceAccountImpersonationUrl ${this.serviceAccountImpersonationUrl}.`,
+          `RegionalAccessBoundary: A service account email is required for regional access boundary lookups but could not be determined from the serviceAccountImpersonationUrl ${this.serviceAccountImpersonationUrl}.`,
         );
       }
       return SERVICE_ACCOUNT_LOOKUP_ENDPOINT.replace(
-        '{universe_domain}',
-        this.universeDomain,
-      ).replace('{service_account_email}', encodeURIComponent(email));
+        '{service_account_email}',
+        encodeURIComponent(email),
+      );
     }
 
     // Check if the audience corresponds to a workload identity pool.
     const wfPoolId = getWorkforcePoolIdFromAudience(this.audience);
     if (wfPoolId) {
       return WORKFORCE_LOOKUP_ENDPOINT.replace(
-        '{universe_domain}',
-        this.universeDomain,
-      ).replace('{pool_id}', encodeURIComponent(wfPoolId));
+        '{pool_id}',
+        encodeURIComponent(wfPoolId),
+      );
     }
 
     // Check if the audience corresponds to a workforce identity pool.
     const wlPoolId = getWorkloadPoolIdFromAudience(this.audience);
     const projectNumber = this.getProjectNumber(this.audience);
     if (wlPoolId && projectNumber) {
-      return WORKLOAD_LOOKUP_ENDPOINT.replace('{project_id}', projectNumber)
-        .replace('{pool_id}', wlPoolId)
-        .replace('{universe_domain}', this.universeDomain);
+      return WORKLOAD_LOOKUP_ENDPOINT.replace(
+        '{project_id}',
+        projectNumber,
+      ).replace('{pool_id}', wlPoolId);
     }
 
     throw new RangeError(
-      `TrustBoundary: Invalid audience provided: "${this.audience}" does not correspond to a workforce or workload pool.`,
+      `RegionalAccessBoundary: Invalid audience provided: "${this.audience}" does not correspond to a workforce or workload pool.`,
     );
   }
 }

packages/google-auth-library-nodejs/src/auth/computeclient.ts

@@ -21,7 +21,7 @@ import {
   OAuth2Client,
   OAuth2ClientOptions,
 } from './oauth2client';
-import {SERVICE_ACCOUNT_LOOKUP_ENDPOINT} from './trustboundary';
+import {SERVICE_ACCOUNT_LOOKUP_ENDPOINT} from './regionalaccessboundary';
 
 export interface ComputeOptions extends OAuth2ClientOptions {
   /**
@@ -90,7 +90,6 @@ export class Compute extends OAuth2Client {
       tokens.expiry_date = new Date().getTime() + data.expires_in * 1000;
       delete (tokens as CredentialRequest).expires_in;
     }
-    this.trustBoundary = await this.refreshTrustBoundary(data);
     this.emit('tokens', tokens);
     return {tokens, res: null};
   }
@@ -140,13 +139,21 @@ export class Compute extends OAuth2Client {
     }
   }
 
-  protected async getTrustBoundaryUrl(): Promise<string> {
+  /**
+   * Returns the regional access boundary lookup URL for the GCE instance.
+   * This implementation resolves the default service account email of the GCE
+   * instance to construct the lookup endpoint.
+   *
+   * @return The regional access boundary URL string.
+   * @internal
+   */
+  public async getRegionalAccessBoundaryUrl(): Promise<string> {
     const email = await this.resolveServiceAccountEmail();
-    const trustBoundaryUrl = SERVICE_ACCOUNT_LOOKUP_ENDPOINT.replace(
-      '{universe_domain}',
-      this.universeDomain,
-    ).replace('{service_account_email}', encodeURIComponent(email));
-    return trustBoundaryUrl;
+    const regionalAccessBoundaryUrl = SERVICE_ACCOUNT_LOOKUP_ENDPOINT.replace(
+      '{service_account_email}',
+      encodeURIComponent(email),
+    );
+    return regionalAccessBoundaryUrl;
   }
 
   /**
@@ -165,7 +172,7 @@ export class Compute extends OAuth2Client {
       return await gcpMetadata.instance('service-accounts/default/email');
     } catch (e) {
       throw new Error(
-        'TrustBoundary: Failed to retrieve default service account email from metadata server.',
+        'RegionalAccessBoundary: Failed to retrieve default service account email from metadata server.',
         {
           cause: e,
         },