chore: Enhance Javadoc, comments, and test robustness for certificate source.

Author: nbayati

oauth2_http/java/com/google/auth/mtls/MtlsHttpTransportFactory.java

@@ -41,6 +41,9 @@
  * An HttpTransportFactory that creates {@link NetHttpTransport} instances configured for mTLS
  * (mutual TLS) using a specific {@link KeyStore} containing the client's certificate and private
  * key.
+ *
+ * <p><b>Warning:</b> This class is considered internal and is not intended for direct use by
+ * library consumers. Its API and behavior may change without notice.
  */
 public class MtlsHttpTransportFactory implements HttpTransportFactory {
   private final KeyStore mtlsKeyStore;

oauth2_http/java/com/google/auth/mtls/X509Provider.java

@@ -122,15 +122,14 @@ public KeyStore getKeyStore() throws IOException {
     if (loadedConfig == null) {
       loadedConfig = getWorkloadCertificateConfiguration();
     }
-    WorkloadCertificateConfiguration workloadCertConfig = loadedConfig;
 
     InputStream certStream = null;
     InputStream privateKeyStream = null;
     SequenceInputStream certAndPrivateKeyStream = null;
     try {
       // Read the certificate and private key file paths into separate streams.
-      File certFile = new File(workloadCertConfig.getCertPath());
-      File privateKeyFile = new File(workloadCertConfig.getPrivateKeyPath());
+      File certFile = new File(loadedConfig.getCertPath());
+      File privateKeyFile = new File(loadedConfig.getPrivateKeyPath());
       certStream = createInputStream(certFile);
       privateKeyStream = createInputStream(privateKeyFile);
 

oauth2_http/java/com/google/auth/oauth2/CertificateIdentityPoolSubjectTokenSupplier.java

@@ -79,7 +79,8 @@ private static X509Certificate loadLeafCertificate(String path)
   @VisibleForTesting
   static X509Certificate parseCertificate(byte[] certData) throws CertificateException {
     if (certData == null || certData.length == 0) {
-      throw new IllegalArgumentException("Invalid certificate data: empty or null input");
+      throw new IllegalArgumentException(
+          "Invalid certificate data: Certificate file is empty or null.");
     }
 
     try {
@@ -98,6 +99,17 @@ private static String encodeCert(X509Certificate certificate)
     return Base64.getEncoder().encodeToString(certificate.getEncoded());
   }
 
+  /**
+   * Retrieves the X509 subject token. This method loads the leaf certificate specified by the
+   * {@code credentialSource.credentialLocation}. The subject token is constructed as a JSON array
+   * containing the base64-encoded (DER format) leaf certificate. This JSON array serves as the
+   * subject token for mTLS authentication.
+   *
+   * @param context The external account supplier context. This parameter is currently not used in
+   *     this implementation.
+   * @return The JSON string representation of the base64-encoded leaf certificate in a JSON array.
+   * @throws IOException If an I/O error occurs while reading the certificate file.
+   */
   @Override
   public String getSubjectToken(ExternalAccountSupplierContext context) throws IOException {
     try {

oauth2_http/javatests/com/google/auth/oauth2/CertificateIdentityPoolSubjectTokenSupplierTest.java

@@ -108,7 +108,8 @@ public void parseCertificate_emptyData_throwsIllegalArgumentException() {
         assertThrows(
             IllegalArgumentException.class,
             () -> CertificateIdentityPoolSubjectTokenSupplier.parseCertificate(new byte[0]));
-    assertEquals("Invalid certificate data: empty or null input", exception.getMessage());
+    assertEquals(
+        "Invalid certificate data: Certificate file is empty or null.", exception.getMessage());
   }
 
   @Test
@@ -117,7 +118,8 @@ public void parseCertificate_nullData_throwsIllegalArgumentException() {
         assertThrows(
             IllegalArgumentException.class,
             () -> CertificateIdentityPoolSubjectTokenSupplier.parseCertificate(null));
-    assertEquals("Invalid certificate data: empty or null input", exception.getMessage());
+    assertEquals(
+        "Invalid certificate data: Certificate file is empty or null.", exception.getMessage());
   }
 
   @Test

oauth2_http/javatests/com/google/auth/oauth2/IdentityPoolCredentialsTest.java

@@ -1112,7 +1112,8 @@ public void build_withDefaultCertificate_throwsOnTransportInitFailure() {
   @Test
   public void build_withCustomProvider_throwsOnGetKeyStore()
       throws IOException, KeyStoreException, CertificateException, NoSuchAlgorithmException {
-    // Setup a custom provider configured to throw during getKeyStore().
+    // Simulate a scenario where the X509Provider fails to load the KeyStore, typically due to an
+    // IOException when reading the certificate or private key files.
     KeyStore keyStore = KeyStore.getInstance("JKS");
     keyStore.load(null, null);
     TestX509Provider x509Provider = new TestX509Provider(keyStore, "/path/to/certificate.json");
@@ -1121,19 +1122,28 @@ public void build_withCustomProvider_throwsOnGetKeyStore()
     Map<String, Object> certificateMap = new HashMap<>();
     certificateMap.put("certificate_config_location", "/path/to/certificate.json");
 
-    // Expect RuntimeException from the custom provider during build.
+    // Expect RuntimeException because the constructor wraps the IOException.
     RuntimeException exception =
         assertThrows(
             RuntimeException.class,
             () -> createCredentialsWithCertificate(x509Provider, certificateMap));
 
-    assertEquals("Exception on get keystore", exception.getMessage());
+    // Verify the cause is the expected IOException from the mock.
+    assertNotNull(exception.getCause());
+    assertTrue(exception.getCause() instanceof IOException);
+    assertEquals("Simulated IOException on get keystore", exception.getCause().getMessage());
+
+    // Verify the wrapper exception message
+    assertEquals(
+        "Failed to initialize IdentityPoolCredentials from certificate source due to an I/O error.",
+        exception.getMessage());
   }
 
   @Test
   public void build_withCustomProvider_throwsOnGetCertificatePath()
       throws IOException, KeyStoreException, CertificateException, NoSuchAlgorithmException {
-    // Setup a custom provider configured to throw during getCertificatePath().
+    // Simulate a scenario where the X509Provider cannot access or read the certificate
+    // configuration file needed to determine the certificate path, resulting in an IOException.
     KeyStore keyStore = KeyStore.getInstance("JKS");
     keyStore.load(null, null);
     TestX509Provider x509Provider = new TestX509Provider(keyStore, "/path/to/certificate.json");
@@ -1142,13 +1152,21 @@ public void build_withCustomProvider_throwsOnGetCertificatePath()
     Map<String, Object> certificateMap = new HashMap<>();
     certificateMap.put("certificate_config_location", "/path/to/certificate.json");
 
-    // Expect RuntimeException from the custom provider during build.
+    // Expect RuntimeException because the constructor wraps the IOException.
     RuntimeException exception =
         assertThrows(
             RuntimeException.class,
             () -> createCredentialsWithCertificate(x509Provider, certificateMap));
 
-    assertEquals("Exception on get certificate path", exception.getMessage());
+    // Verify the cause is the expected IOException from the mock.
+    assertNotNull(exception.getCause());
+    assertTrue(exception.getCause() instanceof IOException);
+    assertEquals("Simulated IOException on certificate path", exception.getCause().getMessage());
+
+    // Verify the wrapper exception message
+    assertEquals(
+        "Failed to initialize IdentityPoolCredentials from certificate source due to an I/O error.",
+        exception.getMessage());
   }
 
   private void createCredentialsWithCertificate(
@@ -1261,17 +1279,17 @@ private static class TestX509Provider extends X509Provider {
     }
 
     @Override
-    public KeyStore getKeyStore() {
+    public KeyStore getKeyStore() throws IOException {
       if (shouldThrowOnGetKeyStore) {
-        throw new RuntimeException("Exception on get keystore");
+        throw new IOException("Simulated IOException on get keystore");
       }
       return keyStore;
     }
 
     @Override
-    public String getCertificatePath() {
+    public String getCertificatePath() throws IOException {
       if (shouldThrowOnGetCertificatePath) {
-        throw new RuntimeException("Exception on get certificate path");
+        throw new IOException("Simulated IOException on certificate path");
       }
       return certificatePath;
     }

oauth2_http/testresources/x509_leaf_certificate.pem

@@ -0,0 +1,19 @@
+-----BEGIN CERTIFICATE-----
+MIIDIzCCAgugAwIBAgIJAMfISuBQ5m+5MA0GCSqGSIb3DQEBBQUAMBUxEzARBgNV
+BAMTCnVuaXQtdGVzdHMwHhcNMTExMjA2MTYyNjAyWhcNMjExMjAzMTYyNjAyWjAV
+MRMwEQYDVQQDEwp1bml0LXRlc3RzMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB
+CgKCAQEA4ej0p7bQ7L/r4rVGUz9RN4VQWoej1Bg1mYWIDYslvKrk1gpj7wZgkdmM
+7oVK2OfgrSj/FCTkInKPqaCR0gD7K80q+mLBrN3PUkDrJQZpvRZIff3/xmVU1Wer
+uQLFJjnFb2dqu0s/FY/2kWiJtBCakXvXEOb7zfbINuayL+MSsCGSdVYsSliS5qQp
+gyDap+8b5fpXZVJkq92hrcNtbkg7hCYUJczt8n9hcCTJCfUpApvaFQ18pe+zpyl4
++WzkP66I28hniMQyUlA1hBiskT7qiouq0m8IOodhv2fagSZKjOTTU2xkSBc//fy3
+ZpsL7WqgsZS7Q+0VRK8gKfqkxg5OYQIDAQABo3YwdDAdBgNVHQ4EFgQU2RQ8yO+O
+gN8oVW2SW7RLrfYd9jEwRQYDVR0jBD4wPIAU2RQ8yO+OgN8oVW2SW7RLrfYd9jGh
+GaQXMBUxEzARBgNVBAMTCnVuaXQtdGVzdHOCCQDHyErgUOZvuTAMBgNVHRMEBTAD
+AQH/MA0GCSqGSIb3DQEBBQUAA4IBAQBRv+M/6+FiVu7KXNjFI5pSN17OcW5QUtPr
+odJMlWrJBtynn/TA1oJlYu3yV5clc/71Vr/AxuX5xGP+IXL32YDF9lTUJXG/uUGk
++JETpKmQviPbRsvzYhz4pf6ZIOZMc3/GIcNq92ECbseGO+yAgyWUVKMmZM0HqXC9
+ovNslqe0M8C1sLm1zAR5z/h/litE7/8O2ietija3Q/qtl2TOXJdCA6sgjJX2WUql
+ybrC55ct18NKf3qhpcEkGQvFU40rVYApJpi98DiZPYFdx1oBDp/f4uZ3ojpxRVFT
+cDwcJLfNRCPUhormsY7fDS9xSyThiHsW9mjJYdcaKQkwYZ0F11yB
+-----END CERTIFICATE-----