googleapis · nnicolee · Jul 21, 2026 · Jul 21, 2026 · Jul 21, 2026 · Jul 21, 2026
@@ -48,13 +48,16 @@
 import java.util.Collection;
 import java.util.Date;
 import java.util.Objects;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 /**
  * OAuth2 credentials representing the built-in service account for Google App Engine. You should
  * only use this class if you are running on AppEngine and are using urlfetch.
  *
  * <p>Fetches access tokens from the App Identity service.
  */
+@NullMarked
 public class AppEngineCredentials extends GoogleCredentials implements ServiceAccountSigner {
 
   private static final long serialVersionUID = -2627708355455064660L;
@@ -122,7 +125,7 @@ public String toString() {
   }
 
   @Override
-  public boolean equals(Object obj) {
+  public boolean equals(@Nullable Object obj) {
     if (!(obj instanceof AppEngineCredentials)) {
       return false;
     }

@@ -93,5 +93,9 @@
        <artifactId>error_prone_annotations</artifactId>
        <scope>compile</scope>
     </dependency>
+    <dependency>
+      <groupId>org.jspecify</groupId>
+      <artifactId>jspecify</artifactId>
+    </dependency>
   </dependencies>
 </project>
@@ -78,6 +78,8 @@
 import java.util.Date;
 import java.util.List;
 import java.util.concurrent.ExecutionException;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 /**
  * A factory for generating downscoped access tokens using a client-side approach.
@@ -136,6 +138,7 @@
  * token, allowing for automatic token refreshes by providing a {@link
  * OAuth2CredentialsWithRefresh.OAuth2RefreshHandler}.
  */
+@NullMarked
 public class ClientSideCredentialAccessBoundaryFactory {
   static final Duration DEFAULT_REFRESH_MARGIN = Duration.ofMinutes(45);
   static final Duration DEFAULT_MINIMUM_TOKEN_LIFETIME = Duration.ofMinutes(30);
@@ -144,9 +147,9 @@ public class ClientSideCredentialAccessBoundaryFactory {
   private final String tokenExchangeEndpoint;
   private final Duration minimumTokenLifetime;
   private final Duration refreshMargin;
-  private RefreshTask refreshTask;
+  private @Nullable RefreshTask refreshTask;
   private final Object refreshLock = new byte[0];
-  private volatile IntermediateCredentials intermediateCredentials = null;
+  private volatile @Nullable IntermediateCredentials intermediateCredentials = null;
   private final Clock clock;
   private final CelCompiler celCompiler;
 

@@ -60,6 +60,10 @@
       <groupId>com.google.crypto.tink</groupId>
       <artifactId>tink</artifactId>
     </dependency>
+    <dependency>
+      <groupId>org.jspecify</groupId>
+      <artifactId>jspecify</artifactId>
+    </dependency>
 
     <dependency>
       <groupId>junit</groupId>

@@ -1,5 +1,8 @@
 java_library(
     name = "credentials",
     srcs = glob(["java/**/*.java"]),
+    deps = [
+        "@org_jspecify_jspecify//jar",
+    ],
     visibility = ["//visibility:public"],
 )
@@ -35,6 +35,7 @@
 import java.util.Collections;
 import java.util.List;
 import java.util.Map;
+import org.jspecify.annotations.NullMarked;
 
 /**
  * Credentials class for calling Google APIs using an API key.
@@ -49,6 +50,7 @@
  * Credentials credentials = ApiKeyCredentials.create("your api key");
  * </code></pre>
  */
+@NullMarked
 public class ApiKeyCredentials extends Credentials {
   static final String API_KEY_HEADER_KEY = "x-goog-api-key";
   private final String apiKey;

@@ -31,6 +31,8 @@
 
 package com.google.auth;
 
+import org.jspecify.annotations.NullMarked;
+
 /**
  * Defines the different types of credentials that can be used for metrics.
  *
@@ -44,6 +46,7 @@
  *
  * @see #getLabel()
  */
+@NullMarked
 public enum CredentialTypeForMetrics {
   USER_CREDENTIALS("u"),
   SERVICE_ACCOUNT_CREDENTIALS_AT("sa"),

@@ -37,8 +37,11 @@
 import java.util.List;
 import java.util.Map;
 import java.util.concurrent.Executor;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 /** Represents an abstract authorized identity instance. */
+@NullMarked
 public abstract class Credentials implements Serializable {
 
   private static final long serialVersionUID = 808575179767517313L;
@@ -161,7 +164,8 @@ protected final void blockingGetToCallback(URI uri, RequestMetadataCallback call
    *     implement {@link Retryable} and {@code isRetryable()} will return true if the operation may
    *     be retried.
    */
-  public abstract Map<String, List<String>> getRequestMetadata(URI uri) throws IOException;
+  public abstract Map<String, List<String>> getRequestMetadata(@Nullable URI uri)
+      throws IOException;
 
   /**
    * Whether the credentials have metadata entries that should be added to each request.

@@ -33,12 +33,14 @@
 
 import java.util.List;
 import java.util.Map;
+import org.jspecify.annotations.NullMarked;
 
 /**
  * The callback that receives the result of the asynchronous {@link
  * Credentials#getRequestMetadata(java.net.URI, java.util.concurrent.Executor,
  * RequestMetadataCallback)}. Exactly one method should be called.
  */
+@NullMarked
 public interface RequestMetadataCallback {
   /**
    * Called when metadata is successfully produced.

@@ -31,7 +31,10 @@
 
 package com.google.auth;
 
+import org.jspecify.annotations.NullMarked;
+
 // an interface to identify retryable errors
+@NullMarked
 public interface Retryable {
   /**
    * A flag indicating whether the error is retryable

@@ -32,11 +32,14 @@
 package com.google.auth;
 
 import java.util.Objects;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 /**
  * Interface for a service account signer. A signer for a service account is capable of signing
  * bytes using the private key associated with its service account.
  */
+@NullMarked
 public interface ServiceAccountSigner {
 
   class SigningException extends RuntimeException {
@@ -48,7 +51,7 @@ public SigningException(String message, Exception cause) {
     }
 
     @Override
-    public boolean equals(Object obj) {
+    public boolean equals(@Nullable Object obj) {
       if (obj == this) {
         return true;
       }

@@ -52,6 +52,10 @@
   </build>
 
   <dependencies>
+    <dependency>
+      <groupId>org.jspecify</groupId>
+      <artifactId>jspecify</artifactId>
+    </dependency>
     <dependency>
       <groupId>org.junit.jupiter</groupId>
       <artifactId>junit-jupiter-api</artifactId>

@@ -14,6 +14,7 @@ java_library(
         "@com_google_auto_value_auto_value_annotations//jar",
         "@com_google_auto_value_auto_value//jar",
         "@org_slf4j_slf4j_api//jar",
+        "@org_jspecify_jspecify//jar",
     ],
     plugins = ["@com_google_api_gax_java//:auto_value_plugin"],
     visibility = ["//visibility:public"],

@@ -31,7 +31,10 @@
 
 package com.google.auth.http;
 
+import org.jspecify.annotations.NullMarked;
+
 /** Constants used for auth in http */
+@NullMarked
 public class AuthHttpConstants {
   /** HTTP "Bearer" authentication scheme */
   public static final String BEARER = "Bearer";

@@ -47,8 +47,10 @@
 import java.util.logging.Level;
 import java.util.logging.Logger;
 import java.util.regex.Pattern;
+import org.jspecify.annotations.NullMarked;
 
 /** A wrapper for using Credentials with the Google API Client Libraries for Java with Http. */
+@NullMarked
 public class HttpCredentialsAdapter
     implements HttpRequestInitializer, HttpUnsuccessfulResponseHandler {
 

@@ -32,13 +32,15 @@
 package com.google.auth.http;
 
 import com.google.api.client.http.HttpTransport;
+import org.jspecify.annotations.NullMarked;
 
 /**
  * A base interface for all {@link HttpTransport} factories.
  *
  * <p>Implementation must provide a public no-arg constructor. Loading of a factory implementation
  * is done via {@link java.util.ServiceLoader}.
  */
+@NullMarked
 public interface HttpTransportFactory {
 
   /**

@@ -31,7 +31,10 @@
 
 package com.google.auth.http;
 
+import org.jspecify.annotations.NullMarked;
+
 /** Internal constants used for auth in http */
+@NullMarked
 class InternalAuthHttpConstants {
   static final String BEARER_PREFIX = AuthHttpConstants.BEARER + " ";
 }
@@ -31,12 +31,14 @@
 package com.google.auth.mtls;
 
 import java.io.IOException;
+import org.jspecify.annotations.NullMarked;
 
 /**
  * This exception is thrown by certificate providers in the Google auth library when the certificate
  * source is unavailable. This means that the transport layer should move on to the next certificate
  * source provider type.
  */
+@NullMarked
 public class CertificateSourceUnavailableException extends IOException {
 
   /**

@@ -34,6 +34,7 @@
 import com.google.api.client.util.Key;
 import com.google.common.collect.ImmutableList;
 import java.util.List;
+import org.jspecify.annotations.NullMarked;
 
 /**
  * Data class representing context_aware_metadata.json file. This is meant for internal Google Cloud
@@ -43,6 +44,7 @@
  * the Gax library. The Gax library version of ContextAwareMetadataJson will be marked as deprecated
  * in the future.
  */
+@NullMarked
 public class ContextAwareMetadataJson extends GenericJson {
   /** Cert provider command */
   @Key("cert_provider_command")

@@ -32,7 +32,9 @@
 
 import com.google.api.core.InternalApi;
 import java.io.IOException;
+import org.jspecify.annotations.NullMarked;
 
+@NullMarked
 @InternalApi
 public class DefaultMtlsProviderFactory {
 

@@ -37,6 +37,7 @@
 import java.security.GeneralSecurityException;
 import java.security.KeyStore;
 import java.util.Objects;
+import org.jspecify.annotations.NullMarked;
 
 /**
  * An HttpTransportFactory that creates {@link NetHttpTransport} instances configured for mTLS
@@ -46,6 +47,7 @@
  * <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.
  */
+@NullMarked
 @InternalApi
 public class MtlsHttpTransportFactory implements HttpTransportFactory {
   private final KeyStore mtlsKeyStore;

@@ -32,6 +32,7 @@
 
 import java.io.IOException;
 import java.security.KeyStore;
+import org.jspecify.annotations.NullMarked;
 
 /**
  * MtlsProvider is used by the Gax library for configuring mutual TLS in the HTTP and GRPC transport
@@ -41,6 +42,7 @@
  * Gax library. The Gax library version of MtlsProvider will be marked as deprecated. See
  * https://github.com/googleapis/google-auth-library-java/issues/1758
  */
+@NullMarked
 public interface MtlsProvider {
   /**
    * Returns a mutual TLS key store.

@@ -39,12 +39,14 @@
 import java.io.IOException;
 import java.io.InputStream;
 import java.util.Locale;
+import org.jspecify.annotations.NullMarked;
 
 /**
  * Utility class for mTLS related operations.
  *
  * <p>For internal use only.
  */
+@NullMarked
 @InternalApi
 public class MtlsUtils {
   static final String CERTIFICATE_CONFIGURATION_ENV_VARIABLE = "GOOGLE_API_CERTIFICATE_CONFIG";

@@ -44,6 +44,7 @@
 import java.security.KeyStore;
 import java.util.List;
 import java.util.concurrent.TimeUnit;
+import org.jspecify.annotations.NullMarked;
 
 /**
  * This class implements {@link MtlsProvider} for the Google Auth library transport layer via {@link
@@ -59,6 +60,7 @@
  * <p>Additionally, this implementation will replace the existing "MtlsProvider" in the Gax library.
  * The Gax library version of MtlsProvider will be marked as deprecated.
  */
+@NullMarked
 @InternalApi
 public class SecureConnectProvider implements MtlsProvider {
   interface ProcessProvider {

@@ -40,7 +40,9 @@
 import java.io.InputStream;
 import java.nio.charset.StandardCharsets;
 import java.util.Map;
+import org.jspecify.annotations.NullMarked;
 
+@NullMarked
 class WorkloadCertificateConfiguration {
 
   private String certPath;

@@ -42,11 +42,14 @@
 import java.io.InputStream;
 import java.io.SequenceInputStream;
 import java.security.KeyStore;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 /**
  * This class implements {@link MtlsProvider} for the Google Auth library transport layer via {@link
  * WorkloadCertificateConfiguration}.
  */
+@NullMarked
 @InternalApi
 public class X509Provider implements MtlsProvider {
   private final EnvironmentProvider envProvider;
@@ -77,7 +80,7 @@ public X509Provider(
    *
    * @param certConfigPathOverride the path to read the certificate configuration from.
    */
-  public X509Provider(String certConfigPathOverride) {
+  public X509Provider(@Nullable String certConfigPathOverride) {
     this(
         SystemEnvironmentProvider.getInstance(),
         SystemPropertyProvider.getInstance(),