googleauth 1.14.0 → 1.15.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e2eef22c1062f2fd2216760e90a1af9ece1b99838bccea486a7b4ce43be9734
-  data.tar.gz: 1e60ef4856de1e4f7a3d423f3953e5e39f86c7002216ad2d98ee46ec88aaaf25
+  metadata.gz: 4b360d5a61b05e86f04c2eab04af61b421ffc5c2e1f6833741d59d9c96d94a19
+  data.tar.gz: 8727a84fa541a8e6a2abeb0544d4608d32d1e205a0d9371e695b079fb8d3fa0a
 SHA512:
-  metadata.gz: d5a87f962d04eb59c9ae083a4d3c46fd54ef4d4c53f0571b3952f6d1a9d30e3af89fb2c50e04b118e301097850c9985c713968dc29c62c5d388d0d8a4c3d306d
-  data.tar.gz: fae67434766ed2d4bb67e2c7ba2784a9397843110c28d96368d368b1dd30229a1ea83c5ee05e70a712446781e67ca84149fbaa72dd4239eb349d6943ff42b9b3
+  metadata.gz: 262a5af69278586d4a13e8776b7fd5c627591aa8434585ea3a80f6e24035e4c78498f02f236fb84b63b7c59ef23e4021f2f21aa5dcf49c5bf46a9a9bb80b66c9
+  data.tar.gz: 9356b779fbb2340328a55850ce434957715d50accb842d24a4233bdb7ce532b49c564d63a068c087439e9cd75d9dc3bfff7b17205cb30f811ddb0d3b0567e101

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Release History
 
+### 1.15.1 (2025-10-14)
+
+#### Bug Fixes
+
+* Deprecate method make_creds in DefaultCredentials ([#545](https://github.com/googleapis/google-auth-library-ruby/issues/545)) 
+
+### 1.15.0 (2025-08-25)
+
+#### Features
+
+* add typed errors to authentication library ([#533](https://github.com/googleapis/google-auth-library-ruby/issues/533)) 
+* Support for JWT 3.x ([#542](https://github.com/googleapis/google-auth-library-ruby/issues/542)) 
+#### Bug Fixes
+
+* fix incorrect error and apply some code complexity refactoring ([#529](https://github.com/googleapis/google-auth-library-ruby/issues/529)) 
+* support Pathname for cred loading ([#537](https://github.com/googleapis/google-auth-library-ruby/issues/537)) 
+#### Documentation
+
+* add summary documentation on credentials types and improve YARD comments 
+* add summary documentation on credentials types and improve YARD comments ([#530](https://github.com/googleapis/google-auth-library-ruby/issues/530)) 
+
 ### 1.14.0 (2025-03-14)
 
 #### Features

data/Credentials.md

@@ -0,0 +1,110 @@
+# Introduction
+
+The closest thing to a base credentials class is the `BaseClient` module. 
+It includes functionality common to most credentials, such as applying authentication tokens to request headers, managing token expiration and refresh, handling logging, and providing updater procs for API clients.
+
+Many credentials classes inherit from `Signet::OAuth2::Client` (`lib/googleauth/signet.rb`) class which provides OAuth-based authentication.
+The `Signet::OAuth2::Client` includes the `BaseClient` functionality.
+
+Most credential types either inherit from `Signet::OAuth2::Client` or include the `BaseClient` module directly.
+
+Notably, `Google::Auth::Credentials` (`lib/googleauth/credentials.rb`) is not a base type or a credentials type per se. It is a wrapper for other credential classes
+that exposes common initialization functionality, such as creating credentials from environment variables, default paths, or application defaults. It is used and subclassed by Google's API client libraries.
+
+# List of credentials types
+
+## Simple Authentication (non-OAuth)
+
+**Google::Auth::APIKeyCredentials** - `lib/googleauth/api_key.rb`
+   - Includes `Google::Auth::BaseClient` module
+   - Implements Google API Key authentication
+   - API Keys are text strings that don't have an associated JSON file
+   - API Keys provide project information but don't reference an IAM principal
+   - They do not expire and cannot be refreshed
+   - Can be loaded from the `GOOGLE_API_KEY` environment variable
+
+2. **Google::Auth::BearerTokenCredentials** - `lib/googleauth/bearer_token.rb`
+   - Includes `Google::Auth::BaseClient` module
+   - Implements Bearer Token authentication
+   - Bearer tokens are strings representing an authorization grant
+   - Can be OAuth2 tokens, JWTs, ID tokens, or any token sent as a `Bearer` in an `Authorization` header
+   - Used when the end-user is managing the token separately (e.g., with another service)
+   - Token lifetime tracking and refresh are outside this class's scope
+   - No JSON representation for this type of credentials
+
+## GCP-Specialized authentication
+
+3. **Google::Auth::GCECredentials < Signet::OAuth2::Client** - `lib/googleauth/compute_engine.rb`
+   - For obtaining authentication tokens from GCE metadata server
+   - Used automatically when code is running on Google Compute Engine
+   - Fetches tokens from the metadata server with no additional configuration needed
+   - This credential type does not have a supported JSON form
+
+4. **Google::Auth::IAMCredentials < Signet::OAuth2::Client** - `lib/googleauth/iam.rb`
+   - For IAM-based authentication (e.g. service-to-service)
+   - Implements authentication-as-a-service for systems already authenticated
+   - Exchanges existing credentials for a short-lived access token
+   - This credential type does not have a supported JSON form
+
+## Service Account Authentication
+
+5. **Google::Auth::ServiceAccountCredentials < Signet::OAuth2::Client** - `lib/googleauth/service_account.rb`
+   - Authenticates requests using Service Account credentials via an OAuth access token
+   - Created from JSON key file downloaded from Google Cloud Console. The JSON form of this credential type has a `"type"` field with the value `"service_account"`.
+   - Supports both OAuth access tokens and self-signed JWT authentication
+   - Can specify scopes for access token requests
+
+6. **Google::Auth::ServiceAccountJwtHeaderCredentials** - `lib/googleauth/service_account_jwt_header.rb`
+   - Authenticates using Service Account credentials with JWT headers
+   - Typically used via `ServiceAccountCredentials` and not by itself
+   - Creates JWT directly for making authenticated calls
+   - Does not require a round trip to the authorization server
+   - Doesn't support OAuth scopes - uses audience (target API) instead
+
+7. **Google::Auth::ImpersonatedServiceAccountCredentials < Signet::OAuth2::Client** - `lib/googleauth/impersonated_service_account.rb`
+   - For service account impersonation
+   - Allows a GCP principal identified by a set of source credentials to impersonate a service account
+   - Useful for delegation of authority and managing permissions across service accounts
+   - Source credentials must have the Service Account Token Creator role on the target
+   - This credential type does not have a supported JSON form
+
+## User Authentication
+
+8. **Google::Auth::UserRefreshCredentials < Signet::OAuth2::Client** - `lib/googleauth/user_refresh.rb`
+   - For user refresh token authentication (from 3-legged OAuth flow)
+   - Authenticates on behalf of a user who has authorized the application
+   - Handles token refresh when original access token expires
+   - Typically obtained through web or installed application flow. The JSON form of this credential type has a `"type"` field with the value `"authorized_user"`.
+
+`Google::Auth::UserAuthorizer` (`lib/googleauth/user_authorizer.rb`) and `Google::Auth::WebUserAuthorizer` (`lib/googleauth/web_user_authorizer.rb`)
+ are used to facilitate user authentication. The `UserAuthorizer` handles interactive 3-Legged-OAuth2 (3LO) user consent authorization for command-line applications.
+ The `WebUserAuthorizer` is a variation of UserAuthorizer adapted for Rack-based web applications that manages OAuth state and provides callback handling.
+
+## External Account Authentication
+  `Google::Auth::ExternalAccount::Credentials` (`lib/googleauth/external_account.rb`) is not a credentials type, it is a module
+  that procides an entry point for External Account credentials. It also serves as a factory that creates appropriate credential
+  types based on credential source (similar to `Google::Auth::get_application_default`).
+  It is included in all External Account credentials types, and it itself includes `Google::Auth::BaseClient` module so all External
+  Account credentials types include `Google::Auth::BaseClient`.
+  The JSON form of this credential type has a `"type"` field with the value `"external_account"`.
+
+9. **Google::Auth::ExternalAccount::AwsCredentials** - `lib/googleauth/external_account/aws_credentials.rb`
+     - Includes `Google::Auth::BaseClient` module
+     - Includes `ExternalAccount::BaseCredentials` module
+     - Uses AWS credentials to authenticate to Google Cloud
+     - Exchanges temporary AWS credentials for Google access tokens
+     - Used for workloads running on AWS that need to access Google Cloud
+
+10. **Google::Auth::ExternalAccount::IdentityPoolCredentials** - `lib/googleauth/external_account/identity_pool_credentials.rb`
+     - Includes `Google::Auth::BaseClient` module
+     - Includes `ExternalAccount::BaseCredentials` module
+     - Authenticates using external identity pool
+     - Exchanges external identity tokens for Google access tokens
+     - Supports file-based and URL-based credential sources
+
+11. **Google::Auth::ExternalAccount::PluggableCredentials** - `lib/googleauth/external_account/pluggable_credentials.rb`
+     - Includes `Google::Auth::BaseClient` module
+     - Includes `ExternalAccount::BaseCredentials` module
+     - Supports executable-based credential sources
+     - Executes external programs to retrieve credentials
+     - Allows for custom authentication mechanisms via external executables

data/Errors.md

@@ -0,0 +1,152 @@
+# Error Handling in Google Auth Library for Ruby
+
+## Overview
+
+The Google Auth Library for Ruby provides a structured approach to error handling. This document explains the error hierarchy, how to access detailed error information, and provides examples of handling errors effectively.
+
+## Error Hierarchy
+
+The Google Auth Library has two main error hierarchies: the core authentication errors and the specialized ID token flow errors.
+
+### Core Authentication Errors
+
+These errors are used throughout the main library for general authentication and credential operations:
+
+```
+Google::Auth::Error (module)
+  ├── Google::Auth::InitializationError (class)
+  └── Google::Auth::DetailedError (module)
+      ├── Google::Auth::CredentialsError (class)
+      ├── Google::Auth::AuthorizationError (class)
+      ├── Google::Auth::UnexpectedStatusError (class)
+      └── Google::Auth::ParseError (class)
+```
+
+### ID Token Errors
+
+These specialized errors are used specifically for ID token flow. They also include the `Google::Auth::Error` module, allowing them to be caught with the same error handling as the core authentication errors:
+
+```
+Google::Auth::Error (module)
+  ├── Google::Auth::IDTokens::KeySourceError (class)
+  └── Google::Auth::IDTokens::VerificationError (class)
+      ├── ExpiredTokenError (class)
+      ├── SignatureError (class)
+      ├── IssuerMismatchError (class)
+      ├── AudienceMismatchError (class)
+      └── AuthorizedPartyMismatchError (class)
+```
+
+### Error Module Types
+
+- **`Google::Auth::Error`**: Base module that all Google Auth errors include. Use this to catch any error from the library.
+
+- **`Google::Auth::DetailedError`**: Extends `Error` to include detailed information about the credential that caused the error, including the credential type and principal.
+
+## Core Authentication Error Classes
+
+- **`InitializationError`**: Raised during credential initialization when required parameters are missing or invalid.
+
+- **`CredentialsError`**: Generic error raised during authentication flows.
+
+- **`AuthorizationError`**: Raised when a remote server refuses to authorize the client. Inherits from `Signet::AuthorizationError`. Is being raised where `Signet::AuthorizationError` was raised previously.
+
+- **`UnexpectedStatusError`**: Raised when a server returns an unexpected HTTP status code. Inherits from `Signet::UnexpectedStatusError`. Is being raised where `Signet::UnexpectedStatusError` was raised previously.
+
+- **`ParseError`**: Raised when the client fails to parse a value from a response. Inherits from `Signet::ParseError`. Is being raised where `Signet::ParseError` was raised previously.
+
+## Detailed Error Information
+
+Errors that include the `DetailedError` module provide additional context about what went wrong:
+
+- **`credential_type_name`**: The class name of the credential that raised the error (e.g., `"Google::Auth::ServiceAccountCredentials"`)
+
+- **`principal`**: The identity associated with the credentials (e.g., an email address for service accounts, `:api_key` for API key credentials)
+
+### Example: Catching and Handling Core Errors
+
+```ruby
+begin
+  credentials = Google::Auth::ServiceAccountCredentials.make_creds(
+    json_key_io: File.open("your-key.json")
+  )
+  # Use credentials...
+rescue Google::Auth::InitializationError => e
+  puts "Failed to initialize credentials: #{e.message}"
+  # e.g., Missing required fields in the service account key file
+rescue Google::Auth::DetailedError => e
+  puts "Authorization failed: #{e.message}"
+  puts "Credential type: #{e.credential_type_name}"
+  puts "Principal: #{e.principal}"
+  # e.g., Invalid or revoked service account
+rescue Google::Auth::Error => e
+  puts "Unknown Google Auth error: #{e.message}"
+end
+```
+
+## Backwards compatibility
+
+Some classes in the Google Auth Library raise standard Ruby `ArgumentError` and `TypeError`. These errors are preserved for backward compatibility, however the new code will raise `Google::Auth::InitializationError` instead.
+
+## ID Token Verification
+
+The Google Auth Library includes functionality for verifying ID tokens through the `Google::Auth::IDTokens` namespace. These operations have their own specialized error classes that also include the `Google::Auth::Error` module, allowing them to be caught with the same error handling as other errors in the library.
+
+### ID Token Error Classes
+
+- **`KeySourceError`**: Raised when the library fails to obtain the keys needed to verify a token, typically from a JWKS (JSON Web Key Set) endpoint.
+
+- **`VerificationError`**: Base class for all errors related to token verification failures.
+
+- **`ExpiredTokenError`**: Raised when a token has expired according to its expiration time claim (`exp`).
+
+- **`SignatureError`**: Raised when a token's signature cannot be verified, indicating it might be tampered with or corrupted.
+
+- **`IssuerMismatchError`**: Raised when a token's issuer (`iss` claim) doesn't match the expected issuer.
+
+- **`AudienceMismatchError`**: Raised when a token's audience (`aud` claim) doesn't match the expected audience.
+
+- **`AuthorizedPartyMismatchError`**: Raised when a token's authorized party (`azp` claim) doesn't match the expected client ID.
+
+### Example: Handling ID Token Verification Errors
+
+```ruby
+require "googleauth/id_tokens"
+
+begin
+  # Verify the provided ID token
+  payload = Google::Auth::IDTokens.verify_oidc(
+    id_token,
+    audience: "expected-audience-12345.apps.googleusercontent.com"
+  )
+  
+  # Use the verified token payload
+  user_email = payload["email"]
+  
+rescue Google::Auth::IDTokens::ExpiredTokenError => e
+  puts "The token has expired. Please obtain a new one."
+
+rescue Google::Auth::IDTokens::SignatureError => e
+  puts "Invalid token signature."
+
+rescue Google::Auth::IDTokens::IssuerMismatchError => e
+  puts "Invalid token issuer."
+
+rescue Google::Auth::IDTokens::AudienceMismatchError => e
+  puts "This token is not intended for this application (invalid audience)."
+  
+rescue Google::Auth::IDTokens::AuthorizedPartyMismatchError => e
+  puts "Invalid token authorized party."
+
+rescue Google::Auth::IDTokens::VerificationError => e
+  puts "Token verification failed: #{e.message}"
+  # Generic verification error handling
+  
+rescue Google::Auth::IDTokens::KeySourceError => e
+  puts "Unable to retrieve verification keys: #{e.message}"
+  
+rescue Google::Auth::Error => e
+  puts "Unknown Google Auth error: #{e.message}"
+  # This will catch any Google Auth error
+end
+```

data/lib/googleauth/api_key.rb

@@ -85,6 +85,7 @@ module Google
       # @option options [String] :universe_domain
       #   The universe domain of the universe this API key
       #   belongs to (defaults to googleapis.com)
+      # @raise [ArgumentError] If the API key is nil or empty
       def initialize options = {}
         raise ArgumentError, "API key must be provided" if options[:api_key].nil? || options[:api_key].empty?
         @api_key = options[:api_key]
@@ -139,6 +140,14 @@ module Google
         a_hash
       end
 
+      # For credentials that are initialized with a token without a principal,
+      # the type of that token should be returned as a principal instead
+      # @private
+      # @return [Symbol] the token type in lieu of the principal
+      def principal
+        token_type
+      end
+
       protected
 
       # The token type should be :api_key

data/lib/googleauth/application_default.rb

@@ -14,6 +14,7 @@
 
 require "googleauth/compute_engine"
 require "googleauth/default_credentials"
+require "googleauth/errors"
 
 module Google
   # Module Auth provides classes that provide Google-specific authorization
@@ -50,12 +51,13 @@ module Google
     #       connection to use for token refresh requests.
     #     * `:connection` The connection to use to determine whether GCE
     #       metadata credentials are available.
+    # @raise [Google::Auth::InitializationError] If the credentials cannot be found
     def get_application_default scope = nil, options = {}
       creds = DefaultCredentials.from_env(scope, options) ||
               DefaultCredentials.from_well_known_path(scope, options) ||
               DefaultCredentials.from_system_default_path(scope, options)
       return creds unless creds.nil?
-      raise NOT_FOUND_ERROR unless GCECredentials.on_gce? options
+      raise InitializationError, NOT_FOUND_ERROR unless GCECredentials.on_gce? options
       GCECredentials.new options.merge(scope: scope)
     end
   end

data/lib/googleauth/base_client.rb

@@ -78,6 +78,11 @@ module Google
       # The logger used to log operations on this client, such as token refresh.
       attr_accessor :logger
 
+      # @private
+      def principal
+        raise NoMethodError, "principal not implemented"
+      end
+
       private
 
       def token_type

data/lib/googleauth/bearer_token.rb

@@ -13,6 +13,7 @@
 # limitations under the License.
 
 require "googleauth/base_client"
+require "googleauth/errors"
 
 module Google
   module Auth
@@ -80,6 +81,7 @@ module Google
       #   If `expires_at` is `nil`, it is treated as "token never expires".
       # @option options [String] :universe_domain The universe domain of the universe
       #   this token is for (defaults to googleapis.com)
+      # @raise [ArgumentError] If the bearer token is nil or empty
       def initialize options = {}
         raise ArgumentError, "Bearer token must be provided" if options[:token].nil? || options[:token].empty?
         @token = options[:token]
@@ -119,6 +121,14 @@ module Google
         )
       end
 
+      # For credentials that are initialized with a token without a principal,
+      # the type of that token should be returned as a principal instead
+      # @private
+      # @return [Symbol] the token type in lieu of the principal
+      def principal
+        token_type
+      end
+
       protected
 
       ##
@@ -129,10 +139,14 @@ module Google
       #
       # @param [Hash] _options Options for fetching a new token (not used).
       # @return [nil] Always returns nil.
-      # @raise [StandardError] If the token is expired.
+      # @raise [Google::Auth::CredentialsError] If the token is expired.
       def fetch_access_token! _options = {}
         if @expires_at && Time.now >= @expires_at
-          raise "Bearer token has expired."
+          raise CredentialsError.with_details(
+            "Bearer token has expired.",
+            credential_type_name: self.class.name,
+            principal: principal
+          )
         end
 
         nil

data/lib/googleauth/client_id.rb

@@ -14,6 +14,7 @@
 
 require "multi_json"
 require "googleauth/credentials_loader"
+require "googleauth/errors"
 
 module Google
   module Auth
@@ -62,10 +63,11 @@ module Google
       # @note Direct instantiation is discouraged to avoid embedding IDs
       #       and secrets in source. See {#from_file} to load from
       #       `client_secrets.json` files.
+      # @raise [Google::Auth::InitializationError] If id or secret is nil
       #
       def initialize id, secret
-        raise "Client id can not be nil" if id.nil?
-        raise "Client secret can not be nil" if secret.nil?
+        raise InitializationError, "Client id can not be nil" if id.nil?
+        raise InitializationError, "Client secret can not be nil" if secret.nil?
         @id = id
         @secret = secret
       end
@@ -77,9 +79,10 @@ module Google
       # @param [String, File] file
       #  Path of file to read from
       # @return [Google::Auth::ClientID]
+      # @raise [Google::Auth::InitializationError] If file is nil
       #
       def self.from_file file
-        raise "File can not be nil." if file.nil?
+        raise InitializationError, "File can not be nil." if file.nil?
         File.open file.to_s do |f|
           json = f.read
           config = MultiJson.load json
@@ -94,11 +97,12 @@ module Google
       # @param [hash] config
       #  Parsed contents of the JSON file
       # @return [Google::Auth::ClientID]
+      # @raise [Google::Auth::InitializationError] If config is nil or missing required elements
       #
       def self.from_hash config
-        raise "Hash can not be nil." if config.nil?
+        raise InitializationError, "Hash can not be nil." if config.nil?
         raw_detail = config[INSTALLED_APP] || config[WEB_APP]
-        raise MISSING_TOP_LEVEL_ELEMENT_ERROR if raw_detail.nil?
+        raise InitializationError, MISSING_TOP_LEVEL_ELEMENT_ERROR if raw_detail.nil?
         ClientId.new raw_detail[CLIENT_ID], raw_detail[CLIENT_SECRET]
       end
     end

data/lib/googleauth/compute_engine.rb

@@ -13,6 +13,7 @@
 # limitations under the License.
 
 require "google-cloud-env"
+require "googleauth/errors"
 require "googleauth/signet"
 
 module Google
@@ -126,31 +127,25 @@ module Google
 
       # Overrides the super class method to change how access tokens are
       # fetched.
+      #
+      # @param [Hash] _options Options for token fetch (not used)
+      # @return [Hash] The token data hash
+      # @raise [Google::Auth::UnexpectedStatusError] On unexpected HTTP status codes
+      # @raise [Google::Auth::AuthorizationError] If metadata server is unavailable or returns error
       def fetch_access_token _options = {}
-        query, entry =
-          if token_type == :id_token
-            [{ "audience" => target_audience, "format" => "full" }, "service-accounts/default/identity"]
-          else
-            [{}, "service-accounts/default/token"]
-          end
-        query[:scopes] = Array(scope).join "," if scope
+        query, entry = build_metadata_request_params
         begin
           log_fetch_query
           resp = Google::Cloud.env.lookup_metadata_response "instance", entry, query: query
           log_fetch_resp resp
-          case resp.status
-          when 200
-            build_token_hash resp.body, resp.headers["content-type"], resp.retrieval_monotonic_time
-          when 403, 500
-            raise Signet::UnexpectedStatusError, "Unexpected error code #{resp.status} #{UNEXPECTED_ERROR_SUFFIX}"
-          when 404
-            raise Signet::AuthorizationError, NO_METADATA_SERVER_ERROR
-          else
-            raise Signet::AuthorizationError, "Unexpected error code #{resp.status} #{UNEXPECTED_ERROR_SUFFIX}"
-          end
+          handle_metadata_response resp
         rescue Google::Cloud::Env::MetadataServerNotResponding => e
           log_fetch_err e
-          raise Signet::AuthorizationError, e.message
+          raise AuthorizationError.with_details(
+            e.message,
+            credential_type_name: self.class.name,
+            principal: principal
+          )
         end
       end
 
@@ -175,8 +170,47 @@ module Google
         self
       end
 
+      # Returns the principal identifier for GCE credentials
+      # @private
+      # @return [Symbol] :gce to represent Google Compute Engine identity
+      def principal
+        :gce_metadata
+      end
+
       private
 
+      # @private
+      # Builds query parameters and endpoint for metadata request
+      # @return [Array] The query parameters and endpoint path
+      def build_metadata_request_params
+        query, entry =
+          if token_type == :id_token
+            [{ "audience" => target_audience, "format" => "full" }, "service-accounts/default/identity"]
+          else
+            [{}, "service-accounts/default/token"]
+          end
+        query[:scopes] = Array(scope).join "," if scope
+        [query, entry]
+      end
+
+      # @private
+      # Handles the response from the metadata server
+      # @param [Google::Cloud::Env::MetadataResponse] resp The metadata server response
+      # @return [Hash] The token hash on success
+      # @raise [Google::Auth::UnexpectedStatusError, Google::Auth::AuthorizationError] On error
+      def handle_metadata_response resp
+        case resp.status
+        when 200
+          build_token_hash resp.body, resp.headers["content-type"], resp.retrieval_monotonic_time
+        when 403, 500
+          raise Signet::UnexpectedStatusError, "Unexpected error code #{resp.status} #{UNEXPECTED_ERROR_SUFFIX}"
+        when 404
+          raise Signet::AuthorizationError, NO_METADATA_SERVER_ERROR
+        else
+          raise Signet::AuthorizationError, "Unexpected error code #{resp.status} #{UNEXPECTED_ERROR_SUFFIX}"
+        end
+      end
+
       def log_fetch_query
         if token_type == :id_token
           logger&.info do
@@ -213,6 +247,18 @@ module Google
         end
       end
 
+      # Constructs a token hash from the metadata server response
+      #
+      # @private
+      # @param [String] body The response body from the metadata server
+      # @param [String] content_type The content type of the response
+      # @param [Float] retrieval_time The monotonic time when the response was retrieved
+      #
+      # @return [Hash] A hash containing:
+      #   - access_token/id_token: The actual token depending on what was requested
+      #   - token_type: The type of token (usually "Bearer")
+      #   - expires_in: Seconds until token expiration (adjusted for freshness)
+      #   - universe_domain: The universe domain for the token (if not overridden)
       def build_token_hash body, content_type, retrieval_time
         hash =
           if ["text/html", "application/text"].include? content_type