fix(auth): refine JSpecify nullability for ServiceAccountCredentials and UserCredentials

google-auth-library-java/oauth2_http/java/com/google/auth/oauth2/GoogleCredentials.java

@@ -33,13 +33,13 @@
 
 import com.google.api.client.json.GenericJson;
 import com.google.api.client.json.JsonObjectParser;
-import com.google.api.client.util.Preconditions;
 import com.google.api.core.ObsoleteApi;
 import com.google.auth.Credentials;
 import com.google.auth.http.HttpTransportFactory;
 import com.google.common.annotations.VisibleForTesting;
 import com.google.common.base.MoreObjects;
 import com.google.common.base.MoreObjects.ToStringHelper;
+import com.google.common.base.Preconditions;
 import com.google.common.base.Strings;
 import com.google.common.collect.ImmutableList;
 import com.google.common.collect.ImmutableMap;
@@ -79,7 +79,7 @@
     COMPUTE_ENGINE_CREDENTIALS("Compute Engine Credentials", null);
 
     private final String credentialName;
-    @Nullable private final String fileType;
+    private final @Nullable String fileType;
 
     GoogleCredentialsInfo(String credentialName, @Nullable String fileType) {
       this.credentialName = credentialName;
@@ -97,17 +97,17 @@
 
   // The following package-private fields to provide additional info for errors message
   // Source of the credential (e.g. env var value or well know file location)
-  String source;
+  @Nullable String source;
   // User-friendly name of the Credential class
-  String name;
+  @Nullable String name;
   // Identity of the credential
   // Note: This field may contain data such as serviceAccountEmail which should not be serialized
-  transient String principal;
+  transient @Nullable String principal;
 
   private final String universeDomain;
   private final boolean isExplicitUniverseDomain;
 
-  protected final String quotaProjectId;
+  protected final @Nullable String quotaProjectId;
 
   private static final DefaultCredentialsProvider defaultCredentialsProvider =
       new DefaultCredentialsProvider();
@@ -216,7 +216,7 @@
    * <p>Regardless of the method used, it is always your responsibility to validate configurations
    * received from external sources.
    *
    * <p>See the {@see <a
    * href="https://cloud.google.com/docs/authentication/external/externally-sourced-credentials">documentation</a>}
    * for more details.
    *
@@ -230,7 +230,8 @@
    * @throws IOException if the credential cannot be created from the stream.
    */
   @ObsoleteApi(
-      "This method is obsolete because of a potential security risk. Use the credential specific load method instead")
+      "This method is obsolete because of a potential security risk. Use the credential specific"
+          + " load method instead")
   public static GoogleCredentials fromStream(InputStream credentialsStream) throws IOException {
     return fromStream(credentialsStream, OAuth2Utils.HTTP_TRANSPORT_FACTORY);
   }
@@ -282,7 +283,7 @@
    * <p>Regardless of the method used, it is always your responsibility to validate configurations
    * received from external sources.
    *
    * <p>See the {@see <a
    * href="https://cloud.google.com/docs/authentication/external/externally-sourced-credentials">documentation</a>}
    * for more details.
    *
@@ -296,7 +297,8 @@
    * @throws IOException if the credential cannot be created from the stream.
    */
   @ObsoleteApi(
-      "This method is obsolete because of a potential security risk. Use the credential specific load method instead")
+      "This method is obsolete because of a potential security risk. Use the credential specific"
+          + " load method instead")
   public static GoogleCredentials fromStream(
       InputStream credentialsStream, HttpTransportFactory transportFactory) throws IOException {
     Preconditions.checkNotNull(transportFactory);
@@ -389,7 +391,7 @@
    * @return a new map with quotaProjectId added if needed
    */
   static Map<String, List<String>> addQuotaProjectIdToRequestMetadata(
-      String quotaProjectId, Map<String, List<String>> requestMetadata) {
+      @Nullable String quotaProjectId, Map<String, List<String>> requestMetadata) {
     Preconditions.checkNotNull(requestMetadata);
     Map<String, List<String>> newRequestMetadata = new HashMap<>(requestMetadata);
     if (quotaProjectId != null && !requestMetadata.containsKey(QUOTA_PROJECT_ID_HEADER_KEY)) {
@@ -471,7 +473,7 @@
    * @param accessToken initial or temporary access token
    */
   @Deprecated
   protected GoogleCredentials(
       AccessToken accessToken, Duration refreshMargin, Duration expirationMargin) {
     this(
         (Builder)
@@ -527,7 +529,7 @@
   }
 
   @Override
-  public String getQuotaProjectId() {
+  public @Nullable String getQuotaProjectId() {
     return this.quotaProjectId;
   }
 
@@ -538,7 +540,7 @@
    *
    * @return the project id for a Credential type
    */
-  public String getProjectId() {
+  public @Nullable String getProjectId() {
     return null;
   }
 
@@ -653,8 +655,8 @@
   }
 
   public static class Builder extends OAuth2Credentials.Builder {
-    @Nullable protected String quotaProjectId;
-    @Nullable protected String universeDomain;
+    protected @Nullable String quotaProjectId;
+    protected @Nullable String universeDomain;
     @Nullable String source;
 
     protected Builder() {}
@@ -679,7 +681,7 @@
     }
 
     @CanIgnoreReturnValue
-    public Builder setQuotaProjectId(String quotaProjectId) {
+    public Builder setQuotaProjectId(@Nullable String quotaProjectId) {
       this.quotaProjectId = quotaProjectId;
       return this;
     }
@@ -689,22 +691,23 @@
       return this;
     }
 
-    public String getQuotaProjectId() {
+    public @Nullable String getQuotaProjectId() {
       return this.quotaProjectId;
     }
 
-    public String getUniverseDomain() {
+    public @Nullable String getUniverseDomain() {
       return this.universeDomain;
     }
 
-    Builder setSource(String source) {
+    @CanIgnoreReturnValue
+    Builder setSource(@Nullable String source) {
       this.source = source;
       return this;
     }
 
     @Override
     @CanIgnoreReturnValue
-    public Builder setAccessToken(AccessToken token) {
+    public Builder setAccessToken(@Nullable AccessToken token) {
       super.setAccessToken(token);
       return this;
     }

google-auth-library-java/oauth2_http/java/com/google/auth/oauth2/OAuth2Credentials.java

@@ -82,11 +82,11 @@
 
   // byte[] is serializable, so the lock variable can be final
   @VisibleForTesting final Object lock = new byte[0];
-  @Nullable private volatile OAuthValue value = null;
+  private volatile @Nullable OAuthValue value = null;
   @Nullable @VisibleForTesting transient RefreshTask refreshTask;
 
   // Change listeners are not serialized
-  private transient List<CredentialsChangedListener> changeListeners;
+  private transient @Nullable List<CredentialsChangedListener> changeListeners;
   // Until we expose this to the users it can remain transient and non-serializable
   transient Clock clock = Clock.SYSTEM;
 
@@ -115,7 +115,7 @@
   }
 
   protected OAuth2Credentials(
-      AccessToken accessToken, Duration refreshMargin, Duration expirationMargin) {
+      @Nullable AccessToken accessToken, Duration refreshMargin, Duration expirationMargin) {
     if (accessToken != null) {
       this.value = OAuthValue.create(accessToken, EMPTY_EXTRA_HEADERS);
     }
@@ -149,8 +149,7 @@
    *
    * @return The cached access token.
    */
-  @Nullable
-  public final AccessToken getAccessToken() {
+  public final @Nullable AccessToken getAccessToken() {
     OAuthValue localState = value;
     if (localState != null) {
       return localState.temporaryAccess;
@@ -369,7 +368,7 @@
    *     token. An instance with a new access token or a derived type that supports refreshing
    *     should be used instead.
    */
   public AccessToken refreshAccessToken() throws IOException {
     throw new IllegalStateException(
         "OAuth2Credentials instance does not support refreshing the"
             + " access token. An instance with a new access token should be used, or a derived type"
@@ -440,8 +439,7 @@
     return Objects.hashCode(value);
   }
 
-  @Nullable
-  protected Map<String, List<String>> getRequestMetadataInternal() {
+  protected @Nullable Map<String, List<String>> getRequestMetadataInternal() {
     OAuthValue localValue = value;
     if (localValue != null) {
       return localValue.requestMetadata;
@@ -711,7 +709,7 @@
 
   public static class Builder {
 
-    private AccessToken accessToken;
+    private @Nullable AccessToken accessToken;
     private Duration refreshMargin = DEFAULT_REFRESH_MARGIN;
     private Duration expirationMargin = DEFAULT_EXPIRATION_MARGIN;
 
@@ -724,7 +722,7 @@
     }
 
     @CanIgnoreReturnValue
-    public Builder setAccessToken(AccessToken token) {
+    public Builder setAccessToken(@Nullable AccessToken token) {
       this.accessToken = token;
       return this;
     }
@@ -749,7 +747,7 @@
       return expirationMargin;
     }
 
-    public AccessToken getAccessToken() {
+    public @Nullable AccessToken getAccessToken() {
       return accessToken;
     }
 

google-auth-library-java/oauth2_http/java/com/google/auth/oauth2/QuotaProjectIdProvider.java

@@ -32,12 +32,13 @@
 package com.google.auth.oauth2;
 
 import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 /** Interface for {@link GoogleCredentials} that return a quota project ID. */
 @NullMarked
 public interface QuotaProjectIdProvider {
   /**
    * @return the quota project ID used for quota and billing purposes
    */
-  String getQuotaProjectId();
+  @Nullable String getQuotaProjectId();
 }