xds bootstrap: enable using JWT Call Credentials (part 2 for A97)

credentials/jwt/doc.go

@@ -0,0 +1,50 @@
+/*
+ *
+ * Copyright 2025 gRPC authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+// Package jwt implements JWT token file-based call credentials.
+//
+// This package provides support for A97 JWT Call Credentials, allowing gRPC
+// clients to authenticate using JWT tokens read from files. While originally
+// designed for xDS environments, these credentials are general-purpose.
+//
+// The credentials can be used directly in gRPC clients or configured via xDS.
+//
+// # Token Requirements
+//
+// JWT tokens must:
+//   - Be valid, well-formed JWT tokens with header, payload, and signature
+//   - Include an "exp" (expiration) claim
+//   - Be readable from the specified file path
+//
+// # Considerations
+//
+// - Tokens are cached until expiration to avoid excessive file I/O
+// - Transport security is required (RequireTransportSecurity returns true)
+// - Errors in reading tokens or parsing JWTs will result in RPC UNAVAILALBE or
+// UNAUTHENTICATED errors. The errors are cached and retried with exponential
+// backoff.
+//
+// This implementation is originally intended for use in service mesh
+// environments like Istio where JWT tokens are provisioned and rotated by the
+// infrastructure.
+//
+// # Experimental
+//
+// Notice: All APIs in this package are experimental and may be removed in a
+// later release.
+package jwt

credentials/jwt/example_test.go

@@ -0,0 +1,58 @@
+/*
+ *
+ * Copyright 2025 gRPC authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+package jwt_test
+
+import (
+	"context"
+	"log"
+	"time"
+
+	"google.golang.org/grpc"
+	"google.golang.org/grpc/credentials/jwt"
+)
+
+// ExampleNewTokenFileCallCredentials demonstrates how to create and use JWT
+// token file call credentials for authentication.
+func ExampleNewTokenFileCallCredentials() {
+	// Create JWT call credentials that read tokens from a file
+	creds, err := jwt.NewTokenFileCallCredentials(
+		"/path/to/jwt.token", // Path to JWT token file
+	)
+	if err != nil {
+		log.Fatalf("Failed to create JWT credentials: %v", err)
+	}
+
+	// Use the credentials when creating a gRPC connection
+	conn, err := grpc.NewClient(
+		"service.example.com:443",
+		grpc.WithPerRPCCredentials(creds),
+		// ... other dial options
+	)
+	if err != nil {
+		log.Fatalf("Failed to connect: %v", err)
+	}
+	defer conn.Close()
+
+	// Use the connection for RPC calls
+	// The JWT token will be automatically included in the authorization header
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+	// ... make RPC calls using ctx and conn
+	_ = ctx
+}

credentials/jwt/jwt_file_reader.go

@@ -0,0 +1,103 @@
+/*
+ *
+ * Copyright 2025 gRPC authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+package jwt
+
+import (
+	"encoding/base64"
+	"encoding/json"
+	"fmt"
+	"os"
+	"strings"
+	"time"
+)
+
+// jwtClaims represents the JWT claims structure for extracting expiration time.
+type jwtClaims struct {
+	Exp int64 `json:"exp"`
+}
+
+// jWTFileReader handles reading and parsing JWT tokens from files.
+type jWTFileReader struct {
+	tokenFilePath string
+}
+
+// newJWTFileReader creates a new JWTFileReader for the specified file path.
+func newJWTFileReader(tokenFilePath string) *jWTFileReader {
+	return &jWTFileReader{
+		tokenFilePath: tokenFilePath,
+	}
+}
+
+// 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) {
+	tokenBytes, err := os.ReadFile(r.tokenFilePath)
+	if err != nil {
+		return "", time.Time{}, fmt.Errorf("failed to read token file %q: %v", r.tokenFilePath, err)
+	}
+
+	token := strings.TrimSpace(string(tokenBytes))
+	if token == "" {
+		return "", time.Time{}, fmt.Errorf("token file %q is empty", r.tokenFilePath)
+	}
+
+	exp, err := r.extractExpiration(token)
+	if err != nil {
+		return "", time.Time{}, fmt.Errorf("failed to parse JWT from token file %q: %v", r.tokenFilePath, err)
+	}
+
+	return token, exp, nil
+}
+
+// extractExpiration parses the JWT token to extract the expiration time.
+func (r *jWTFileReader) extractExpiration(token string) (time.Time, error) {
+	parts := strings.Split(token, ".")
+	if len(parts) != 3 {
+		return time.Time{}, fmt.Errorf("invalid JWT format: 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)
+	if err != nil {
+		return time.Time{}, fmt.Errorf("failed to decode JWT payload: %v", err)
+	}
+
+	var claims jwtClaims
+	if err := json.Unmarshal(payloadBytes, &claims); err != nil {
+		return time.Time{}, fmt.Errorf("failed to unmarshal JWT claims: %v", err)
+	}
+
+	if claims.Exp == 0 {
+		return time.Time{}, fmt.Errorf("JWT token has no expiration claim")
+	}
+
+	expTime := time.Unix(claims.Exp, 0)
+
+	// Check if token is already expired.
+	if expTime.Before(time.Now()) {
+		return time.Time{}, fmt.Errorf("JWT token is expired")
+	}
+
+	return expTime, nil
+}

credentials/jwt/jwt_file_reader_test.go

@@ -0,0 +1,180 @@
+/*
+ *
+ * Copyright 2025 gRPC authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+package jwt
+
+import (
+	"encoding/base64"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestJWTFileReader_ReadToken_FileErrors(t *testing.T) {
+	tests := []struct {
+		name            string
+		setupFile       func(string) error
+		wantErrContains string
+	}{
+		{
+			name: "nonexistent file",
+			setupFile: func(_ string) error {
+				return nil // Don't create the file
+			},
+			wantErrContains: "failed to read token file",
+		},
+		{
+			name: "empty file",
+			setupFile: func(path string) error {
+				return os.WriteFile(path, []byte(""), 0600)
+			},
+			wantErrContains: "token file",
+		},
+		{
+			name: "file with whitespace only",
+			setupFile: func(path string) error {
+				return os.WriteFile(path, []byte("   \n\t  "), 0600)
+			},
+			wantErrContains: "token file",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			tempDir := t.TempDir()
+			tokenFile := filepath.Join(tempDir, "token")
+			if err := tt.setupFile(tokenFile); err != nil {
+				t.Fatalf("Failed to setup test file: %v", err)
+			}
+
+			reader := newJWTFileReader(tokenFile)
+			_, _, err := reader.ReadToken()
+			if err == nil {
+				t.Fatal("ReadToken() expected error, got nil")
+			}
+
+			if !strings.Contains(err.Error(), tt.wantErrContains) {
+				t.Fatalf("ReadToken() error = %v, want error containing %q", err, tt.wantErrContains)
+			}
+		})
+	}
+}
+
+func TestJWTFileReader_ReadToken_InvalidJWT(t *testing.T) {
+	now := time.Now().Truncate(time.Second)
+	tests := []struct {
+		name            string
+		tokenContent    string
+		wantErrContains string
+	}{
+		{
+			name:            "valid token without expiration",
+			tokenContent:    createTestJWT(t, "", time.Time{}),
+			wantErrContains: "JWT token has no expiration claim",
+		},
+		{
+			name:            "expired token",
+			tokenContent:    createTestJWT(t, "", now.Add(-time.Hour)),
+			wantErrContains: "JWT token is expired",
+		},
+		{
+			name:            "malformed JWT - not enough parts",
+			tokenContent:    "invalid.jwt",
+			wantErrContains: "invalid JWT format: expected 3 parts, got 2",
+		},
+		{
+			name:            "malformed JWT - invalid base64",
+			tokenContent:    "header.invalid_base64!@#.signature",
+			wantErrContains: "failed to decode JWT payload",
+		},
+		{
+			name:            "malformed JWT - invalid JSON",
+			tokenContent:    createInvalidJSONJWT(t),
+			wantErrContains: "failed to unmarshal JWT claims",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			tokenFile := writeTempFile(t, "token", tt.tokenContent)
+
+			reader := newJWTFileReader(tokenFile)
+			_, _, err := reader.ReadToken()
+			if err == nil {
+				t.Fatal("ReadToken() expected error, got nil")
+			}
+
+			if !strings.Contains(err.Error(), tt.wantErrContains) {
+				t.Fatalf("ReadToken() error = %v, want error containing %q", err, tt.wantErrContains)
+			}
+		})
+	}
+}
+
+func TestJWTFileReader_ReadToken_ValidToken(t *testing.T) {
+	now := time.Now().Truncate(time.Second)
+	tokenExp := now.Add(time.Hour)
+	token := createTestJWT(t, "https://example.com", tokenExp)
+	tokenFile := writeTempFile(t, "token", token)
+
+	reader := newJWTFileReader(tokenFile)
+	readToken, expiry, err := reader.ReadToken()
+	if err != nil {
+		t.Fatalf("ReadToken() unexpected error: %v", err)
+	}
+
+	if readToken != token {
+		t.Errorf("ReadToken() token = %q, want %q", readToken, token)
+	}
+
+	if !expiry.Equal(tokenExp) {
+		t.Errorf("ReadToken() expiry = %v, want %v", expiry, tokenExp)
+	}
+}
+
+// createInvalidJSONJWT creates a JWT with invalid JSON in the payload.
+func createInvalidJSONJWT(t *testing.T) string {
+	t.Helper()
+
+	header := map[string]any{
+		"typ": "JWT",
+		"alg": "HS256",
+	}
+
+	headerBytes, err := json.Marshal(header)
+	if err != nil {
+		t.Fatalf("Failed to marshal header: %v", err)
+	}
+
+	headerB64 := base64.URLEncoding.EncodeToString(headerBytes)
+	headerB64 = strings.TrimRight(headerB64, "=")
+
+	// Create invalid JSON payload
+	invalidJSON := "invalid json content"
+	payloadB64 := base64.URLEncoding.EncodeToString([]byte(invalidJSON))
+	payloadB64 = strings.TrimRight(payloadB64, "=")
+
+	signature := base64.URLEncoding.EncodeToString([]byte("fake_signature"))
+	signature = strings.TrimRight(signature, "=")
+
+	return fmt.Sprintf("%s.%s.%s", headerB64, payloadB64, signature)
+}