Merge PR oras-project#1038: feat!: remove ForceAttemptOAuth2 add SetLegacyMode to auth client

Signed-off-by: Terry Howe <terrylhowe@gmail.com>

Author: TerryHowe

CLAUDE.md

@@ -0,0 +1,74 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+ORAS Go is a Go library for managing OCI (Open Container Initiative) artifacts, providing unified APIs for pushing, pulling, and managing artifacts across OCI-compliant registries, local file systems, and in-memory stores. It's compliant with the OCI Image Format Specification and OCI Distribution Specification.
+
+## Development Commands
+
+### Testing
+```bash
+make test           # Run tests with race detection and coverage
+go test ./...       # Run all tests without coverage
+go test ./content   # Run tests for specific package
+```
+
+### Building and Validation
+```bash
+make check-encoding # Check for CRLF line endings
+make fix-encoding   # Fix CRLF line endings
+make vendor         # Update vendor directory
+make clean          # Clean ignored files
+```
+
+### Coverage
+```bash
+make covhtml        # Open coverage report in browser (requires prior test run)
+```
+
+## Code Architecture
+
+### Core Package Structure
+
+- **Root package (`oras`)** - Main APIs for copying, packing, and content operations
+- **`content/`** - Content management and storage interfaces
+  - `content/file/` - File-based content storage
+  - `content/memory/` - In-memory content storage  
+  - `content/oci/` - OCI layout storage
+- **`registry/`** - Registry interfaces and operations
+  - `registry/remote/` - Remote registry client implementations
+  - `registry/remote/auth/` - Authentication handling
+  - `registry/remote/credentials/` - Credential management
+- **`internal/`** - Internal packages not part of the public API
+  - `internal/cas/` - Content-addressable storage utilities
+  - `internal/syncutil/` - Synchronization utilities
+  - `internal/platform/` - Platform-specific utilities
+
+### Key Concepts
+
+- **Targets** - Abstractions for different storage backends (registry, file system, memory)
+- **Content Stores** - Manage content storage and retrieval with content-addressable storage
+- **Descriptors** - OCI descriptors that identify and describe content
+- **Copy Operations** - Core functionality for copying artifacts between different targets
+- **Graph Operations** - Handle dependencies between artifacts and their manifests
+
+### Testing Patterns
+
+Tests follow Go conventions with `*_test.go` files. The codebase includes:
+- Unit tests for individual packages
+- Example tests demonstrating API usage
+- Integration-style tests for end-to-end operations
+
+### Go Version Support
+
+The project supports the two latest Go versions (currently 1.23 and 1.24) following Go's security policy. The minimum Go version is specified in `go.mod`.
+
+## Key Files for Understanding
+
+- `content.go` - Core content operations and interfaces
+- `copy.go` - Primary copy functionality between targets  
+- `pack.go` - Artifact packing operations
+- `registry/registry.go` - Registry interface definitions
+- `registry/remote/repository.go` - Remote repository implementation

registry/remote/auth/client.go

@@ -99,13 +99,25 @@ type Client struct {
 	// Reference: https://distribution.github.io/distribution/spec/auth/oauth/#getting-a-token
 	ClientID string
 
-	// ForceAttemptOAuth2 controls whether to follow OAuth2 with password grant
-	// instead the distribution spec when authenticating using username and
-	// password.
+	// legacyMode controls whether to use the legacy distribution spec
+	// instead of OAuth2 with password grant when authenticating using
+	// username and password.
+	// Default is false (OAuth2 is used).
+	//
+	// When legacyMode is true, the client uses the legacy distribution spec for
+	// authentication. If the registry says it supports bearer authentication,
+	// basic authentication will be performed unless there are no credentials
+	// or a refresh token is provided. This is the approach used in oras-go
+	// v1 and v2.
+	//
+	// When legacyMode is false (default), the client uses OAuth2 with password
+	// grant.  If the registry says it supports bearer authentication, bearer
+	// authentication will be performed.
+	//
 	// References:
 	// - https://distribution.github.io/distribution/spec/auth/jwt/
 	// - https://distribution.github.io/distribution/spec/auth/oauth/
-	ForceAttemptOAuth2 bool
+	legacyMode bool
 }
 
 // client returns an HTTP client used to access the remote registry.
@@ -150,6 +162,27 @@ func (c *Client) SetUserAgent(userAgent string) {
 	c.Header.Set(headerUserAgent, userAgent)
 }
 
+// SetLegacyMode sets whether to use legacy distribution spec authentication
+// instead of OAuth2 with password grant when authenticating using username
+// and password.
+//
+// When legacy is true, the client uses the legacy distribution spec for
+// authentication. If the registry says it supports bearer authentication,
+// basic authentication will be performed unless there are no credentials
+// or a refresh token is provided. This is the approach used in oras-go
+// v1 and v2.
+//
+// When legacy is false (default), the client uses OAuth2 with password
+// grant.  If the registry says it supports bearer authentication, bearer
+// authentication will be performed.
+//
+// References:
+//   - https://distribution.github.io/distribution/spec/auth/jwt/
+//   - https://distribution.github.io/distribution/spec/auth/oauth/
+func (c *Client) SetLegacyMode(legacy bool) {
+	c.legacyMode = legacy
+}
+
 // Do sends the request to the remote server, attempting to resolve
 // authentication if 'Authorization' header is not set.
 //
@@ -288,7 +321,7 @@ func (c *Client) fetchBearerToken(ctx context.Context, registry, realm, service
 	if cred.AccessToken != "" {
 		return cred.AccessToken, nil
 	}
-	if cred == credentials.EmptyCredential || (cred.RefreshToken == "" && !c.ForceAttemptOAuth2) {
+	if cred == credentials.EmptyCredential || (cred.RefreshToken == "" && c.legacyMode) {
 		return c.fetchDistributionToken(ctx, realm, service, scopes, cred.Username, cred.Password)
 	}
 	return c.fetchOAuth2Token(ctx, realm, service, scopes, cred)

registry/remote/auth/client_test.go

@@ -726,6 +726,7 @@ func TestClient_Do_Bearer_Auth(t *testing.T) {
 			}, nil
 		},
 	}
+	client.SetLegacyMode(true)
 
 	// first request
 	req, err := http.NewRequest(http.MethodGet, ts.URL, nil)
@@ -853,6 +854,7 @@ func TestClient_Do_Bearer_Auth_Cached(t *testing.T) {
 		},
 		Cache: NewCache(),
 	}
+	client.SetLegacyMode(true)
 
 	// first request
 	ctx := WithScopes(context.Background(), scopes...)
@@ -995,6 +997,7 @@ func TestClient_Do_Bearer_Auth_Cached_PerHost(t *testing.T) {
 		}),
 		Cache: NewCache(),
 	}
+	client1.SetLegacyMode(true)
 
 	// set up server 2
 	username2 := "test_user2"
@@ -1065,6 +1068,7 @@ func TestClient_Do_Bearer_Auth_Cached_PerHost(t *testing.T) {
 		}),
 		Cache: NewCache(),
 	}
+	client2.SetLegacyMode(true)
 
 	ctx := context.Background()
 	ctx = WithScopesForHost(ctx, uri1.Host, scopes1...)
@@ -1312,7 +1316,6 @@ func TestClient_Do_Bearer_OAuth2_Password(t *testing.T) {
 				Password: password,
 			}, nil
 		},
-		ForceAttemptOAuth2: true,
 	}
 
 	// first request
@@ -1459,8 +1462,7 @@ func TestClient_Do_Bearer_OAuth2_Password_Cached(t *testing.T) {
 				Password: password,
 			}, nil
 		},
-		ForceAttemptOAuth2: true,
-		Cache:              NewCache(),
+		Cache: NewCache(),
 	}
 
 	// first request
@@ -1622,8 +1624,7 @@ func TestClient_Do_Bearer_OAuth2_Password_Cached_PerHost(t *testing.T) {
 			Username: username1,
 			Password: password1,
 		}),
-		ForceAttemptOAuth2: true,
-		Cache:              NewCache(),
+		Cache: NewCache(),
 	}
 	// set up server 2
 	username2 := "test_user2"
@@ -1712,8 +1713,7 @@ func TestClient_Do_Bearer_OAuth2_Password_Cached_PerHost(t *testing.T) {
 			Username: username2,
 			Password: password2,
 		}),
-		ForceAttemptOAuth2: true,
-		Cache:              NewCache(),
+		Cache: NewCache(),
 	}
 
 	ctx := context.Background()
@@ -2970,8 +2970,7 @@ func TestClient_Do_Scope_Hint_Mismatch(t *testing.T) {
 				Password: password,
 			}, nil
 		},
-		ForceAttemptOAuth2: true,
-		Cache:              NewCache(),
+		Cache: NewCache(),
 	}
 
 	// first request
@@ -3114,8 +3113,7 @@ func TestClient_Do_Scope_Hint_Mismatch_PerHost(t *testing.T) {
 			Username: username1,
 			Password: password1,
 		}),
-		ForceAttemptOAuth2: true,
-		Cache:              NewCache(),
+		Cache: NewCache(),
 	}
 
 	// set up server 1
@@ -3208,8 +3206,7 @@ func TestClient_Do_Scope_Hint_Mismatch_PerHost(t *testing.T) {
 			Username: username2,
 			Password: password2,
 		}),
-		ForceAttemptOAuth2: true,
-		Cache:              NewCache(),
+		Cache: NewCache(),
 	}
 
 	ctx := context.Background()
@@ -3350,6 +3347,7 @@ func TestClient_Do_Invalid_Credential_Basic(t *testing.T) {
 			}, nil
 		},
 	}
+	client.SetLegacyMode(true)
 
 	// request should fail
 	req, err := http.NewRequest(http.MethodGet, ts.URL, nil)
@@ -3435,6 +3433,7 @@ func TestClient_Do_Invalid_Credential_Bearer(t *testing.T) {
 			}, nil
 		},
 	}
+	client.SetLegacyMode(true)
 
 	// request should fail
 	req, err := http.NewRequest(http.MethodGet, ts.URL, nil)
@@ -3620,6 +3619,7 @@ func TestClient_Do_Scheme_Change(t *testing.T) {
 		},
 		Cache: NewCache(),
 	}
+	client.SetLegacyMode(true)
 
 	// request with bearer auth
 	req, err := http.NewRequest(http.MethodGet, ts.URL, nil)

registry/remote/auth/example_test.go

@@ -190,8 +190,6 @@ func ExampleClient_Do_clientConfigurations() {
 			Username: username,
 			Password: password,
 		}),
-		// ForceAttemptOAuth2 controls whether to follow OAuth2 with password grant.
-		ForceAttemptOAuth2: true,
 		// Cache caches credentials for accessing the remote registry.
 		Cache: NewCache(),
 	}

tools

@@ -0,0 +1 @@
+../bashed/tools