credentials: implement file-based JWT Call Credentials (part 1 for A97)

credentials/jwt/jwt_file_reader.go

@@ -38,14 +38,15 @@ type jwtClaims struct {
 	Exp int64 `json:"exp"`
 }
 
-// jWTFileReader handles reading and parsing JWT tokens from files.
-type jWTFileReader struct {
+// jwtFileReader handles reading and parsing JWT tokens from files.
+// It is safe to call methods on this type concurrently as no state is stored.
+type jwtFileReader struct {
 	tokenFilePath string
 }
 
 // readToken reads and parses a JWT token from the configured file.
 // Returns the token string, expiration time, and any error encountered.
-func (r *jWTFileReader) readToken() (string, time.Time, error) {
+func (r *jwtFileReader) readToken() (string, time.Time, error) {
 	tokenBytes, err := os.ReadFile(r.tokenFilePath)
 	if err != nil {
 		return "", time.Time{}, fmt.Errorf("%v: %w", err, errTokenFileAccess)
@@ -58,44 +59,39 @@ func (r *jWTFileReader) readToken() (string, time.Time, error) {
 
 	exp, err := r.extractExpiration(token)
 	if err != nil {
-		return "", time.Time{}, fmt.Errorf("%q: %w", r.tokenFilePath, err)
+		return "", time.Time{}, fmt.Errorf("token file %q: %v: %w", r.tokenFilePath, err, errJWTValidation)
 	}
 
 	return token, exp, nil
 }
 
 // extractExpiration parses the JWT token to extract the expiration time.
-func (r *jWTFileReader) extractExpiration(token string) (time.Time, error) {
+func (r *jwtFileReader) extractExpiration(token string) (time.Time, error) {
 	parts := strings.Split(token, ".")
 	if len(parts) != 3 {
-		return time.Time{}, fmt.Errorf("expected 3 parts, got %d: %w", len(parts), errJWTValidation)
+		return time.Time{}, fmt.Errorf("expected 3 parts, got %d", len(parts))
 	}
 
 	payload := parts[1]
-	// Add padding if necessary for base64 decoding.
-	if m := len(payload) % 4; m != 0 {
-		payload += strings.Repeat("=", 4-m)
-	}
-
-	payloadBytes, err := base64.URLEncoding.DecodeString(payload)
+	payloadBytes, err := base64.RawURLEncoding.DecodeString(payload)
 	if err != nil {
-		return time.Time{}, fmt.Errorf("decode error: %v: %w", err, errJWTValidation)
+		return time.Time{}, fmt.Errorf("decode error: %v", err)
 	}
 
 	var claims jwtClaims
 	if err := json.Unmarshal(payloadBytes, &claims); err != nil {
-		return time.Time{}, fmt.Errorf("unmarshal error: %v: %w", err, errJWTValidation)
+		return time.Time{}, fmt.Errorf("unmarshal error: %v", err)
 	}
 
 	if claims.Exp == 0 {
-		return time.Time{}, fmt.Errorf("no expiration claims: %w", errJWTValidation)
+		return time.Time{}, fmt.Errorf("no expiration claims")
 	}
 
 	expTime := time.Unix(claims.Exp, 0)
 
 	// Check if token is already expired.
 	if expTime.Before(time.Now()) {
-		return time.Time{}, fmt.Errorf("expired token: %w", errJWTValidation)
+		return time.Time{}, fmt.Errorf("expired token")
 	}
 
 	return expTime, nil

credentials/jwt/jwt_file_reader_test.go

@@ -26,14 +26,8 @@ import (
 	"strings"
 	"testing"
 	"time"
-
-	"google.golang.org/grpc/internal/grpctest"
 )
 
-func TestJWTFileReader(t *testing.T) {
-	grpctest.RunSubTests(t, s{})
-}
-
 func (s) TestJWTFileReader_ReadToken_FileErrors(t *testing.T) {
 	tests := []struct {
 		name     string
@@ -70,7 +64,7 @@ func (s) TestJWTFileReader_ReadToken_FileErrors(t *testing.T) {
 				tokenFile = writeTempFile(t, "token", tt.contents)
 			}
 
-			reader := jWTFileReader{tokenFilePath: tokenFile}
+			reader := jwtFileReader{tokenFilePath: tokenFile}
 			if _, _, err := reader.readToken(); err == nil {
 				t.Fatal("ReadToken() expected error, got nil")
 			} else if !errors.Is(err, tt.wantErr) {
@@ -118,7 +112,7 @@ func (s) TestJWTFileReader_ReadToken_InvalidJWT(t *testing.T) {
 		t.Run(tt.name, func(t *testing.T) {
 			tokenFile := writeTempFile(t, "token", tt.tokenContent)
 
-			reader := jWTFileReader{tokenFilePath: tokenFile}
+			reader := jwtFileReader{tokenFilePath: tokenFile}
 			if _, _, err := reader.readToken(); err == nil {
 				t.Fatal("ReadToken() expected error, got nil")
 			} else if !errors.Is(err, tt.wantErr) {
@@ -134,7 +128,7 @@ func (s) TestJWTFileReader_ReadToken_ValidToken(t *testing.T) {
 	token := createTestJWT(t, tokenExp)
 	tokenFile := writeTempFile(t, "token", token)
 
-	reader := jWTFileReader{tokenFilePath: tokenFile}
+	reader := jwtFileReader{tokenFilePath: tokenFile}
 	readToken, expiry, err := reader.readToken()
 	if err != nil {
 		t.Fatalf("ReadToken() unexpected error: %v", err)

credentials/jwt/jwt_token_file_call_creds.go

@@ -16,7 +16,6 @@
  *
  */
 
-// Package jwt implements gRPC credentials using JWT tokens from files.
 package jwt
 
 import (
@@ -38,7 +37,7 @@ const preemptiveRefreshThreshold = time.Minute
 // tokens from a file.
 // This implementation follows the A97 JWT Call Credentials specification.
 type jwtTokenFileCallCreds struct {
-	fileReader      *jWTFileReader
+	fileReader      *jwtFileReader
 	backoffStrategy backoff.Strategy
 
 	// cached data protected by mu
@@ -59,7 +58,7 @@ func NewTokenFileCallCredentials(tokenFilePath string) (credentials.PerRPCCreden
 	}
 
 	creds := &jwtTokenFileCallCreds{
-		fileReader:      &jWTFileReader{tokenFilePath: tokenFilePath},
+		fileReader:      &jwtFileReader{tokenFilePath: tokenFilePath},
 		backoffStrategy: backoff.DefaultExponential,
 	}
 
@@ -77,21 +76,19 @@ func NewTokenFileCallCredentials(tokenFilePath string) (credentials.PerRPCCreden
 func (c *jwtTokenFileCallCreds) GetRequestMetadata(ctx context.Context, _ ...string) (map[string]string, error) {
 	ri, _ := credentials.RequestInfoFromContext(ctx)
 	if err := credentials.CheckSecurityLevel(ri.AuthInfo, credentials.PrivacyAndIntegrity); err != nil {
-		return nil, fmt.Errorf("cannot send secure credentials on an insecure connection: %w", err)
+		return nil, fmt.Errorf("cannot send secure credentials on an insecure connection: %v", err)
 	}
 
 	c.mu.Lock()
 	defer c.mu.Unlock()
 
 	if c.isTokenValidLocked() {
 		needsPreemptiveRefresh := time.Until(c.cachedExpiry) < preemptiveRefreshThreshold
-		if needsPreemptiveRefresh {
+		if needsPreemptiveRefresh && !c.pendingRefresh {
 			// Start refresh if not pending (handling the prior RPC may have
 			// just spawned a goroutine).
-			if !c.pendingRefresh {
-				c.pendingRefresh = true
-				go c.refreshToken()
-			}
+			c.pendingRefresh = true
+			go c.refreshToken()
 		}
 		return map[string]string{
 			"authorization": c.cachedAuthHeader,
@@ -137,19 +134,23 @@ func (c *jwtTokenFileCallCreds) isTokenValidLocked() bool {
 
 // refreshToken reads the token from file and updates the cached data.
 func (c *jwtTokenFileCallCreds) refreshToken() {
-	// Deliberately not locking c.mu here
+	// Deliberately not locking c.mu here. This way other RPCs can proceed
+	// while we read the token. This is per gRFC A97.
 	token, expiry, err := c.fileReader.readToken()
 
 	c.mu.Lock()
 	defer c.mu.Unlock()
 	c.updateCacheLocked(token, expiry, err)
-
 	c.pendingRefresh = false
 }
 
 // updateCacheLocked updates the cached token, expiry, and error state.
 // If an error is provided, it determines whether to set it as an UNAVAILABLE
 // or UNAUTHENTICATED error based on the error type.
+// NOTE: This method (and its callers) do not queue up a token refresh/retry if
+// the expiration is soon / an error was encountered. Instead, this is done when
+// handling RPCs. This is as per gRFC A97, which states that it is
+// undesirable to retry loading the token if the channel is idle.
 // Caller must hold c.mu lock.
 func (c *jwtTokenFileCallCreds) updateCacheLocked(token string, expiry time.Time, err error) {
 	if err != nil {
@@ -173,7 +174,7 @@ func (c *jwtTokenFileCallCreds) updateCacheLocked(token string, expiry time.Time
 	c.nextRetryTime = time.Time{}
 
 	c.cachedAuthHeader = "Bearer " + token
-	// Per RFC A97: consider token invalid if it expires within the next 30
+	// Per gRFC A97: consider token invalid if it expires within the next 30
 	// seconds to accommodate for clock skew and server processing time.
 	c.cachedExpiry = expiry.Add(-30 * time.Second)
 }