cloud.google.com/go/auth v0.24.1: Options3LO

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify cloud.google.com/go/auth.Options3LO in pkg:golang/cloud.google.com/go/auth@v0.24.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/cloud.google.com/go/auth@v0.24.1
Demonstrate these symbols/APIs:
  - cloud.google.com/go/auth.Options3LO

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:265c534ac21ee668ec9ae55fd280f4e36924102f941bbe36b777e861d8e0af6d","contract":["Options3LO validation fails when options pointer is nil","Options3LO validation fails when ClientID is missing","Options3LO validation fails when ClientSecret is missing without AuthHandlerOpts","Options3LO validation fails when AuthURL is missing","Options3LO validation fails when TokenURL is missing","Options3LO validation fails when AuthStyle is unknown","Options3LO validation fails when RefreshToken is missing without AuthHandlerOpts","Options3LO with RefreshToken and StyleInHeader retrieves token with Basic auth","Options3LO with StyleInParams sends client credentials in request body","Options3LO with URLParams passes custom query parameters in token request","Options3LO with AuthHandlerOpts and PKCEOpts supports authorization code exchange"],"goal":"verify cloud.google.com/go/auth.Options3LO in pkg:golang/cloud.google.com/go/auth@v0.24.1","kind":"HOW","packages":["pkg:golang/cloud.google.com/go/auth@v0.24.1"],"schemaVersion":1,"symbols":["cloud.google.com/go/auth.Options3LO"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/cloud.google.com/go/auth@v0.24.1"],"schemaVersion":1,"subject":"pkg:golang/cloud.google.com/go/auth@v0.24.1","symbols":["cloud.google.com/go/auth.Options3LO"],"verifierAdapter":"golang@1"}

module sample

go 1.26.6

require cloud.google.com/go/auth v0.24.1

require (
	cloud.google.com/go/compute/metadata v0.9.0 // indirect
	github.com/googleapis/gax-go/v2 v2.26.2 // indirect
	golang.org/x/sys v0.47.0 // indirect
)

cloud.google.com/go/auth v0.24.1 h1:NTmd2iJb4DsGIav0KiqFMYI88nMshA2wnFMBatRmoCs=
cloud.google.com/go/auth v0.24.1/go.mod h1:1dmBXa9xfBvBr39ZnDUDkaaA91ccq9CcqENDgJA4d7c=
cloud.google.com/go/compute/metadata v0.9.0 h1:pDUj4QMoPejqq20dK0Pg2N4yG9zIkYGdBtwLoEkH9Zs=
cloud.google.com/go/compute/metadata v0.9.0/go.mod h1:E0bWwX5wTnLPedCKqk3pJmVgCBSM6qQI1yTBdEb3C10=
github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
github.com/felixge/httpsnoop v1.0.4 h1:NFTV2Zj1bL4mc9sqWACXbQFVBBg2W3GPvqp8/ESS2Wg=
github.com/felixge/httpsnoop v1.0.4/go.mod h1:m8KPJKqk1gH5J9DgRY2ASl2lWCfGKXixSwevea8zH2U=
github.com/go-logr/logr v1.4.4 h1:tG4xh9yMsRCAiodLVTxyrkzSZ9+o0L1Kg/+cPVcbP/8=
github.com/go-logr/logr v1.4.4/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
github.com/google/s2a-go v0.1.9 h1:LGD7gtMgezd8a/Xak7mEWL0PjoTQFvpRudN895yqKW0=
github.com/google/s2a-go v0.1.9/go.mod h1:YA0Ei2ZQL3acow2O62kdp9UlnvMmU7kA6Eutn0dXayM=
github.com/googleapis/enterprise-certificate-proxy v0.3.17 h1:73NfMHdiqo9JFU9+7a5ExpVa10/R29pXfZIaW559nrg=
github.com/googleapis/enterprise-certificate-proxy v0.3.17/go.mod h1:rSEsBUemEBZEexP2y6jPp16LUmUbjmSbcPMQizR0o4k=
github.com/googleapis/gax-go/v2 v2.26.2 h1:ydkmNXxj7bEmmeK5AihkKnWxyOyBR9TDebvp5L5izk8=
github.com/googleapis/gax-go/v2 v2.26.2/go.mod h1:sMKqnMesnKH+3wiRJROcttA+cJoZoGbZl1vDQ8XYtGk=
go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.67.0 h1:OyrsyzuttWTSur2qN/Lm0m2a8yqyIjUVBZcxFPuXq2o=
go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.67.0/go.mod h1:C2NGBr+kAB4bk3xtMXfZ94gqFDtg/GkI7e9zqGh5Beg=
go.opentelemetry.io/otel v1.45.0 h1:pdrWmLHofpubmArBv1LgFSv1Z0Ie/ppdZzu+kUN5EeU=
go.opentelemetry.io/otel v1.45.0/go.mod h1:XZxIqPapzEYnhNSScF5DIqXhm/rYi0FzCe2XddAwZfQ=
go.opentelemetry.io/otel/metric v1.45.0 h1:7Eg1uH7CJ5cXv9is6tnBe1FI6rj1nwUdbFypRm3br/M=
go.opentelemetry.io/otel/metric v1.45.0/go.mod h1:HAPbm1nd3p1PmFH7v2dR+6BjXxw+Lq4a2+pndMAm08s=
go.opentelemetry.io/otel/trace v1.45.0 h1:l/mP6Uv7oNO7/TblbhpbgMidxhq1uO/rPsikOyVhxag=
go.opentelemetry.io/otel/trace v1.45.0/go.mod h1:qoJJA2xNMnxRrdISU/kLtfUH2wNeQbiv+jhs/CxI8bc=
golang.org/x/crypto v0.55.0 h1:+KWHjbgOaAQ66dh/YlkZKHlz9ZUlq61AFirAR9ntP8M=
golang.org/x/crypto v0.55.0/go.mod h1:uq0V9dE/fzQuJtbnL+2EhWOE63vo164FY8xqEnV9xis=
golang.org/x/net v0.58.0 h1:ynWG7rqYi4ccpTEuPZ2QGWHktVEM9DMCj9yzDE0Q7To=
golang.org/x/net v0.58.0/go.mod h1:YwCddHnFlT7eLQqVprV19OnhLGtc5xOKgE0RyqgfWAU=
golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
golang.org/x/text v0.41.0 h1:vz/seA0lnX87Othu2f/0L24RcgrXD9/YFTSuGjj3rH8=
golang.org/x/text v0.41.0/go.mod h1:jvf1O8ajNzZqhSrQBPbutR/EB83Cc0CFrezNQIwbb5M=
google.golang.org/api v0.288.0 h1:glhO/J88obKP5I269W3hB73dvBKrjU56ZfmNlNXpgTU=
google.golang.org/api v0.288.0/go.mod h1:lM2kYRzYUCBY91P9h6VF1PYmvhxii3O5hji37qRvIcY=
google.golang.org/genproto v0.0.0-20260715232425-e75dac1f907d h1:C9v1o0/4quuhOAfmRXA2j+we0PqZIp8traLdeogF3Ms=
google.golang.org/genproto/googleapis/rpc v0.0.0-20260715232425-e75dac1f907d h1:Jkpk39hlTZOIp3RbfvNX9R8Hv+Sw0X89nlU/xFOErsc=
google.golang.org/genproto/googleapis/rpc v0.0.0-20260715232425-e75dac1f907d/go.mod h1:4Hqkh8ycfw05ld/3BWL7rJOSfebL2Q+DVDeRgYgxUU8=
google.golang.org/grpc v1.83.2 h1:EManeRomTObA0BU7I8vXgg/78uE5MJ9M8B39EX2WscU=
google.golang.org/grpc v1.83.2/go.mod h1:YPI1hK3kDked6iHvgX3tR0y+nX/qpMFKhPgFsokw1S8=
google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"net/http"
	"net/http/httptest"
	"net/url"
	"time"

	"cloud.google.com/go/auth"
)

func main() {
	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		w.Header().Set("Content-Type", "application/json")
		_ = json.NewEncoder(w).Encode(map[string]any{
			"access_token":  "mock-access-token",
			"token_type":    "Bearer",
			"refresh_token": "mock-refresh-token",
			"expires_in":    3600,
		})
	}))
	defer server.Close()

	opts := &auth.Options3LO{
		ClientID:     "mock-client-id",
		ClientSecret: "mock-client-secret",
		AuthURL:      server.URL + "/auth",
		TokenURL:     server.URL + "/token",
		AuthStyle:    auth.StyleInHeader,
		RefreshToken: "mock-refresh-token",
		RedirectURL:  "http://localhost:8080/callback",
		Scopes:       []string{"https://example.com/auth/read"},
		URLParams:    url.Values{"prompt": {"consent"}},
		Client:       server.Client(),
	}

	tp, err := auth.New3LOTokenProvider(opts)
	if err != nil {
		panic(err)
	}

	tok, err := tp.Token(context.Background())
	if err != nil {
		panic(err)
	}

	fmt.Printf("Options3LO token retrieved: %s (type: %s, expiry: %s)\n", tok.Value, tok.Type, tok.Expiry.Format(time.RFC3339))
}

{
  "schemaVersion": 1,
  "goal": "verify cloud.google.com/go/auth.Options3LO in pkg:golang/cloud.google.com/go/auth@v0.24.1",
  "kind": "HOW",
  "packages": [
    "pkg:golang/cloud.google.com/go/auth@v0.24.1"
  ],
  "symbols": [
    "cloud.google.com/go/auth.Options3LO"
  ]
}

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"net/http"
	"net/http/httptest"
	"net/url"
	"os"
	"strings"

	"cloud.google.com/go/auth"
)

func main() {
	if err := runTests(); err != nil {
		fmt.Fprintf(os.Stderr, "Contract test failed: %v\n", err)
		os.Exit(1)
	}
	fmt.Println("All contract tests passed successfully.")
}

func runTests() error {
	ctx := context.Background()

	baseOpts := func() *auth.Options3LO {
		return &auth.Options3LO{
			ClientID:     "mock-client-id",
			ClientSecret: "mock-client-secret",
			AuthURL:      "http://localhost/auth",
			TokenURL:     "http://localhost/token",
			AuthStyle:    auth.StyleInHeader,
			RefreshToken: "mock-refresh-token",
		}
	}

	// 1. Options3LO validation fails when options pointer is nil
	{
		_, err := auth.New3LOTokenProvider(nil)
		if err == nil || !strings.Contains(err.Error(), "options must be provided") {
			return fmt.Errorf("test 1: expected options must be provided error, got: %v", err)
		}
	}

	// 2. Options3LO validation fails when ClientID is missing
	{
		opts := baseOpts()
		opts.ClientID = ""
		_, err := auth.New3LOTokenProvider(opts)
		if err == nil || !strings.Contains(err.Error(), "client ID must be provided") {
			return fmt.Errorf("test 2: expected client ID error, got: %v", err)
		}
	}

	// 3. Options3LO validation fails when ClientSecret is missing without AuthHandlerOpts
	{
		opts := baseOpts()
		opts.ClientSecret = ""
		_, err := auth.New3LOTokenProvider(opts)
		if err == nil || !strings.Contains(err.Error(), "client secret must be provided") {
			return fmt.Errorf("test 3: expected client secret error, got: %v", err)
		}
	}

	// 4. Options3LO validation fails when AuthURL is missing
	{
		opts := baseOpts()
		opts.AuthURL = ""
		_, err := auth.New3LOTokenProvider(opts)
		if err == nil || !strings.Contains(err.Error(), "auth URL must be provided") {
			return fmt.Errorf("test 4: expected auth URL error, got: %v", err)
		}
	}

	// 5. Options3LO validation fails when TokenURL is missing
	{
		opts := baseOpts()
		opts.TokenURL = ""
		_, err := auth.New3LOTokenProvider(opts)
		if err == nil || !strings.Contains(err.Error(), "token URL must be provided") {
			return fmt.Errorf("test 5: expected token URL error, got: %v", err)
		}
	}

	// 6. Options3LO validation fails when AuthStyle is unknown
	{
		opts := baseOpts()
		opts.AuthStyle = auth.StyleUnknown
		_, err := auth.New3LOTokenProvider(opts)
		if err == nil || !strings.Contains(err.Error(), "auth style must be provided") {
			return fmt.Errorf("test 6: expected auth style error, got: %v", err)
		}
	}

	// 7. Options3LO validation fails when RefreshToken is missing without AuthHandlerOpts
	{
		opts := baseOpts()
		opts.RefreshToken = ""
		_, err := auth.New3LOTokenProvider(opts)
		if err == nil || !strings.Contains(err.Error(), "refresh token must be provided") {
			return fmt.Errorf("test 7: expected refresh token error, got: %v", err)
		}
	}

	// 8. Options3LO with RefreshToken and StyleInHeader retrieves token with Basic auth
	{
		var authHeader string
		var grantType string
		var refreshTokenVal string

		server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			authHeader = r.Header.Get("Authorization")
			_ = r.ParseForm()
			grantType = r.Form.Get("grant_type")
			refreshTokenVal = r.Form.Get("refresh_token")

			w.Header().Set("Content-Type", "application/json")
			_ = json.NewEncoder(w).Encode(map[string]any{
				"access_token":  "access-tok-header",
				"token_type":    "Bearer",
				"refresh_token": "new-refresh-token",
				"expires_in":    3600,
			})
		}))
		defer server.Close()

		opts := &auth.Options3LO{
			ClientID:     "my-client",
			ClientSecret: "my-secret",
			AuthURL:      server.URL + "/auth",
			TokenURL:     server.URL + "/token",
			AuthStyle:    auth.StyleInHeader,
			RefreshToken: "mock-refresh",
			Client:       server.Client(),
		}

		tp, err := auth.New3LOTokenProvider(opts)
		if err != nil {
			return fmt.Errorf("test 8: New3LOTokenProvider error: %w", err)
		}

		tok, err := tp.Token(ctx)
		if err != nil {
			return fmt.Errorf("test 8: Token() error: %w", err)
		}
		if tok.Value != "access-tok-header" {
			return fmt.Errorf("test 8: expected access-tok-header, got %q", tok.Value)
		}
		if !strings.HasPrefix(authHeader, "Basic ") {
			return fmt.Errorf("test 8: expected Basic authorization header, got %q", authHeader)
		}
		if grantType != "refresh_token" || refreshTokenVal != "mock-refresh" {
			return fmt.Errorf("test 8: unexpected form params: grant_type=%q, refresh_token=%q", grantType, refreshTokenVal)
		}
	}

	// 9. Options3LO with StyleInParams sends client credentials in request body
	{
		var formClientID, formClientSecret string

		server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			_ = r.ParseForm()
			formClientID = r.Form.Get("client_id")
			formClientSecret = r.Form.Get("client_secret")

			w.Header().Set("Content-Type", "application/json")
			_ = json.NewEncoder(w).Encode(map[string]any{
				"access_token": "access-tok-params",
				"token_type":   "Bearer",
				"expires_in":   3600,
			})
		}))
		defer server.Close()

		opts := &auth.Options3LO{
			ClientID:     "param-client-id",
			ClientSecret: "param-client-secret",
			AuthURL:      server.URL + "/auth",
			TokenURL:     server.URL + "/token",
			AuthStyle:    auth.StyleInParams,
			RefreshToken: "mock-refresh",
			Client:       server.Client(),
		}

		tp, err := auth.New3LOTokenProvider(opts)
		if err != nil {
			return fmt.Errorf("test 9: New3LOTokenProvider error: %w", err)
		}

		tok, err := tp.Token(ctx)
		if err != nil {
			return fmt.Errorf("test 9: Token() error: %w", err)
		}
		if tok.Value != "access-tok-params" {
			return fmt.Errorf("test 9: expected access-tok-params, got %q", tok.Value)
		}
		if formClientID != "param-client-id" || formClientSecret != "param-client-secret" {
			return fmt.Errorf("test 9: unexpected form client credentials: id=%q secret=%q", formClientID, formClientSecret)
		}
	}

	// 10. Options3LO with URLParams passes custom query parameters in token request
	{
		var customParamVal string

		server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			_ = r.ParseForm()
			customParamVal = r.Form.Get("custom_extra_param")

			w.Header().Set("Content-Type", "application/json")
			_ = json.NewEncoder(w).Encode(map[string]any{
				"access_token": "access-tok-custom",
				"token_type":   "Bearer",
				"expires_in":   3600,
			})
		}))
		defer server.Close()

		opts := &auth.Options3LO{
			ClientID:     "custom-client",
			ClientSecret: "custom-secret",
			AuthURL:      server.URL + "/auth",
			TokenURL:     server.URL + "/token",
			AuthStyle:    auth.StyleInParams,
			RefreshToken: "mock-refresh",
			URLParams:    url.Values{"custom_extra_param": {"extra_value"}},
			Client:       server.Client(),
		}

		tp, err := auth.New3LOTokenProvider(opts)
		if err != nil {
			return fmt.Errorf("test 10: New3LOTokenProvider error: %w", err)
		}

		tok, err := tp.Token(ctx)
		if err != nil {
			return fmt.Errorf("test 10: Token() error: %w", err)
		}
		if tok.Value != "access-tok-custom" {
			return fmt.Errorf("test 10: unexpected token %q", tok.Value)
		}
		if customParamVal != "extra_value" {
			return fmt.Errorf("test 10: expected extra_value, got %q", customParamVal)
		}
	}

	// 11. Options3LO with AuthHandlerOpts and PKCEOpts supports authorization code exchange
	{
		var receivedCodeVerifier string
		var receivedGrantType string

		server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			_ = r.ParseForm()
			receivedCodeVerifier = r.Form.Get("code_verifier")
			receivedGrantType = r.Form.Get("grant_type")

			w.Header().Set("Content-Type", "application/json")
			_ = json.NewEncoder(w).Encode(map[string]any{
				"access_token": "access-tok-pkce",
				"token_type":   "Bearer",
				"expires_in":   3600,
			})
		}))
		defer server.Close()

		opts := &auth.Options3LO{
			ClientID:  "pkce-client-id",
			AuthURL:   server.URL + "/auth",
			TokenURL:  server.URL + "/token",
			AuthStyle: auth.StyleInParams,
			Client:    server.Client(),
			AuthHandlerOpts: &auth.AuthorizationHandlerOptions{
				State: "pkce-state-xyz",
				PKCEOpts: &auth.PKCEOptions{
					Challenge:       "mock-challenge-val",
					ChallengeMethod: "S256",
					Verifier:        "mock-verifier-val",
				},
				Handler: func(authCodeURL string) (string, string, error) {
					parsed, err := url.Parse(authCodeURL)
					if err != nil {
						return "", "", err
					}
					if parsed.Query().Get("code_challenge") != "mock-challenge-val" {
						return "", "", fmt.Errorf("missing or wrong code_challenge: %s", authCodeURL)
					}
					if parsed.Query().Get("code_challenge_method") != "S256" {
						return "", "", fmt.Errorf("missing or wrong code_challenge_method: %s", authCodeURL)
					}
					return "mock-auth-code-123", parsed.Query().Get("state"), nil
				},
			},
		}

		tp, err := auth.New3LOTokenProvider(opts)
		if err != nil {
			return fmt.Errorf("test 11: New3LOTokenProvider error: %w", err)
		}

		tok, err := tp.Token(ctx)
		if err != nil {
			return fmt.Errorf("test 11: Token() error: %w", err)
		}
		if tok.Value != "access-tok-pkce" {
			return fmt.Errorf("test 11: unexpected token %q", tok.Value)
		}
		if receivedGrantType != "authorization_code" {
			return fmt.Errorf("test 11: expected authorization_code, got %q", receivedGrantType)
		}
		if receivedCodeVerifier != "mock-verifier-val" {
			return fmt.Errorf("test 11: expected verifier mock-verifier-val, got %q", receivedCodeVerifier)
		}
	}

	return nil
}