fix(image): map <token> credentials to IdentityToken in Pull (#151)

The Docker credential store convention uses "<token>" as the username
to indicate the password field contains an identity/OAuth token rather
than a literal password (see docker/cli credentials/native_store.go).

When credentialsFn returns "<token>" as the username, map the password
to AuthConfig.IdentityToken instead of AuthConfig.Password. This
matches how the Docker CLI handles token credentials and ensures the
daemon receives a properly structured auth config.

Without this fix, the token is sent as a basic auth password, which
causes containerd's transfer service to fail with 401 Unauthorized
when authenticating against Docker Hub's token endpoint.

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: robmry

image/pull.go

@@ -87,10 +87,22 @@ func Pull(ctx context.Context, imageName string, opts ...PullOption) error {
 		pullOpts.client.Logger().Warn("failed to parse image reference, ServerAddress will be empty", "image", imageName, "error", err)
 	}
 
-	authConfig := registry.AuthConfig{
-		Username:      username,
-		Password:      password,
-		ServerAddress: imgRef.Registry,
+	// The Docker credential store convention uses "<token>" as the username
+	// to indicate the password is an identity/OAuth token, not a literal
+	// password. Map this to the IdentityToken field so the daemon handles
+	// it correctly (see docker/cli credentials/native_store.go).
+	var authConfig registry.AuthConfig
+	if username == "<token>" {
+		authConfig = registry.AuthConfig{
+			IdentityToken: password,
+			ServerAddress: imgRef.Registry,
+		}
+	} else {
+		authConfig = registry.AuthConfig{
+			Username:      username,
+			Password:      password,
+			ServerAddress: imgRef.Registry,
+		}
 	}
 
 	pullOpts.pullOptions.RegistryAuth, err = authconfig.Encode(authConfig)

image/pull_unit_test.go

@@ -42,6 +42,34 @@ func TestPullRegistryAuth(t *testing.T) {
 	require.Equal(t, "myregistry.example.com", decoded.ServerAddress)
 }
 
+func TestPullRegistryAuth_TokenUsername(t *testing.T) {
+	mockCli := &errMockCli{}
+	sdk, err := sdkclient.New(context.TODO(), sdkclient.WithDockerAPI(mockCli))
+	require.NoError(t, err)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 1*time.Second)
+	defer cancel()
+
+	imageName := "docker/sandbox-templates:shell-docker"
+	err = Pull(ctx, imageName,
+		WithPullOptions(dockerclient.ImagePullOptions{}),
+		WithCredentialsFn(func(_ string) (string, string, error) {
+			return "<token>", "my-oauth-token", nil
+		}),
+		WithPullClient(sdk),
+	)
+	require.NoError(t, err)
+
+	// When username is "<token>", the token should be mapped to IdentityToken
+	// (not Username/Password), matching the Docker CLI credential store convention.
+	decoded, err := authconfig.Decode(mockCli.lastPullOptions.RegistryAuth)
+	require.NoError(t, err)
+	require.Empty(t, decoded.Username, "Username should be empty for token auth")
+	require.Empty(t, decoded.Password, "Password should be empty for token auth")
+	require.Equal(t, "my-oauth-token", decoded.IdentityToken)
+	require.Equal(t, "docker.io", decoded.ServerAddress)
+}
+
 func TestPull(t *testing.T) {
 	defaultPullOpts := []PullOption{WithPullOptions(dockerclient.ImagePullOptions{})}