Plan: loopback authorization-code login (default) + --device fallback

Phase 0 — Confirm backend facts (blocking)

The entire-core prior art and the CLI talk to different hosts, so don't assume its paths transfer:

Action: pull the auth host's /.well-known/openid-configuration and verify the client registration. Everything below assumes: authorize endpoint on the auth host, PKCE S256, loopback any-port redirect allowed.

Phase 1 — New authcode package in auth-go

Files (mirror deviceflow/):

• authcode/authcode.go — client + flow
• authcode/testseams.go — SetNowForTest per-Client atomic.Pointer clock (copy deviceflow's pattern verbatim)
• authcode/authcode_test.go — httptest-driven

Client struct (mirror deviceflow.Client):

• Transport http.RoundTripper, BaseURL, ClientID, Scope, UserAgent
• AuthorizePath string, TokenPath string
• RequestTimeout time.Duration, AllowInsecureHTTP bool, nowOverride atomic.Pointer[...]
• New(c *Client) (*Client, error) validating required fields.

Public API — recommend a decomposed shape so the CLI keeps control of browser-open and user messaging (the CLI already owns openBrowser/TTY logic):

// Step 1: generate PKCE+state, bind loopback listener, build authorize URL.
func (c *Client) StartCallbackServer(ctx context.Context) (*AuthSession, error)

type AuthSession struct {
    AuthorizationURL string        // open this in the browser
    RedirectURI      string        // http://127.0.0.1:<port>/callback
    // unexported: verifier, state, listener, resultCh
}

// Step 2: block until the browser hits the loopback callback (or ctx/timeout).
func (s *AuthSession) Wait(ctx context.Context) (code string, issuer string, err error)

// Step 3: exchange code+verifier at the token endpoint.
func (c *Client) Exchange(ctx context.Context, s *AuthSession, code string) (*tokens.TokenSet, error)

func (s *AuthSession) Close() error   // shut down listener

Rationale: a one-shot Login(ctx, openFn) is tempting but couples the lib to browser-opening and progress output. Decomposed mirrors how deviceflow splits StartDeviceAuth/PollDeviceAuth and keeps the lib I/O-free except the loopback server. Return the RFC 9207 issuer from Wait so the CLI can route the exchange cross-region.

Port the entire-core internals (client/clilogin/loopback.go), adapting to auth-go conventions:

• PKCE: newPKCEPair() — 48 random bytes → verifier, base64.RawURLEncoding(SHA256(verifier)) → challenge, method S256.
• State: 24 random bytes base64url.
• Listener: net.ListenConfig{}.Listen(ctx, "tcp", "127.0.0.1:0"), callback path /callback, redirect http://127.0.0.1:<port>/callback.
• Authorize URL: response_type=code, client_id, redirect_uri, scope ( add cli offline_access — entire-core omitted scope; the CLI needs the refresh token, matching the device-flow client), state, code_challenge, code_challenge_method=S256.
• Callback handler: validate state (400 on mismatch, don't kill flow), handle error param, require non-empty code, capture iss, write success HTML, signal buffered channel.
• Success HTML constant ("You're signed in, close this tab").
• Exchange: POST TokenPath, grant_type=authorization_code + code/redirect_uri/code_verifier/client_id. (loopback.go:278–346) — but parse into *tokens.TokenSet and reuse oauthhttp helpers instead of hand-rolling (entire-core hand-rolled because it predates auth-go).
• Timeout: context.WithTimeout default ~5 min; graceful Shutdown.`

Reuse internal/oauthhttp (importable — same module):

• HTTPClient(transport), ResolveURL(base, path, allowInsecure) for both authorize + token URLs (also gives the absolute-path/redirect-attack defense for free).
• ReadAndDecodeJSON (token response), ReadOAuthError + SanitizeDescription (error bodies), ExpiresInDuration (clamp expires_in → TokenSet.ExpiresAt).
• ValidateOriginURL/IsLoopbackHost for the BaseURL/loopback enforcement (HTTPS-required unless AllowInsecureHTTP + loopback — identical posture to deviceflow).

Error sentinels (deviceflow style): ErrStateMismatch, ErrCallbackMissingCode, ErrAuthorizationDenied (maps error=access_denied), ErrListenerClosed, ErrTimeout.

Conventions: Go 1.26.4, errors.New sentinels, //nolint:wrapcheck on oauthhttp pass-throughs, parallel-safe per-Client clock, httptest servers with AllowInsecureHTTP=true. Add a doc.go blurb and a CHANGELOG.md``## Unreleased → ### Added entry. Also flip README's non-goals — it currently lists "PKCE / authorization code flow" as out of scope (README:203).

Release: tag auth-go (e.g. v0.5.0), since this is additive. The CLI consumes via a go.mod bump.

Phase 2 — Wire into the CLI's auth package

• Provider config (cmd/entire/cli/auth/provider.go): add AuthorizePath to Provider; populate v1 (/oauth/authorize?) and v2 (from discovery doc, likely /authorize). Confirmed in Phase 0.

• auth.Client (cmd/entire/cli/auth/client.go): hold an *authcode.Client alongside the existing *deviceflow.Client, built with the same issuer/scope/transport/AllowInsecureHTTP logic (including the isLoopbackHTTP(issuer) auto-permit). Add shim methods:

• StartBrowserAuth(ctx) (*BrowserAuthSession, error)

  • WaitForCallback(ctx, session) (code, issuer, error)
  • ExchangeCode(ctx, session, code) (access, refresh string, error) — returns the same (access, refresh) pair shape runLogin already persists. Keep types aliased/wrapped so login.go stays decoupled from auth-go directly, exactly like DeviceAuthStart/DeviceAuthPoll today.

Phase 3 — entire login command surface (cmd/entire/cli/login.go)

• Add var useDevice bool + cmd.Flags().BoolVar(&useDevice, "device", false, "Use device-code flow (verify a code in your browser) instead of the default browser redirect"). Keep it visible (unlike --insecure-http-auth).

• RunEbranches:

• useDevice → existing runLogin (device flow), unchanged.

  • else → new runBrowserLogin.

• `runBrowserLogin(ctx, outW, errW, client, openURL):

1. session := client.StartBrowserAuth(ctx) (binds loopback, builds URL).
2. If interactive.CanPromptInteractively(): print "Opening your browser to sign in…", openURL(ctx, session.AuthorizationURL); on open failure, print the URL for manual paste (the loopback server is already listening — same-host browser still works).
3. code, issuer := client.WaitForCallback(ctx, session) with a spinner/"Waiting for sign-in…" message.
4. access, refresh := client.ExchangeCode(ctx, session, code).
5. Reuse the existing tail of runLogin verbatim: validateReceivedToken (use issuer if returned, else client.BaseURL()), store.SaveToken, auth.RecordLoginContext(access, refresh, true), "Login complete." Extract that tail into a shared persistLogin(...) helper so both flows share it.

• Headless / non-interactive auto-fallback (recommended): when !interactive.CanPromptInteractively() (CI, SSH without /dev/tty, piped), the loopback browser flow can't work — auto-fall back to the device flow and print a one-line note ("No interactive terminal; using device-code flow"). This avoids forcing users to remember --device on remote boxes. Flag this as a UX decision; the alternative is to hard-error and tell them to pass --device.
• requireSecureBaseURL / --insecure-http-auth unchanged — already covers the auth host the authorize+token calls hit.

Phase 4 — Tests

auth-go (authcode_test.go): httptest server implementing /authorize-style redirect + /oauth/token. Cover: happy path (PKCE verifier echoed → token), state mismatch rejected, error=access_denied param, missing code, token-endpoint OAuth error, timeout via canceled ctx, refresh token plumbed into TokenSet. Mirror deviceflow_test.go structure + SetNowForTest.

CLI unit (login_test.go): add a browserAuthClient interface + fake; test runBrowserLogin success, open-browser-fails fallback path, ctx-cancel, and validateReceivedToken still gates the issuer. Test the --device flag routes to runLogin. Test the headless auto-fallback decision.

CLI integration (integration_test/login_test.go): extend the mock server (currently device-only) with the authorize-redirect + authorization_code token branch. The test harness must (a) read the printed authorize URL, (b) extract redirect_uri, (c) GET the loopback callback with a valid code + matching state, (d) assert Login complete. This replaces the device-flow /approve POST with a loopback callback GET. Keep the device-flow integration tests too (now exercised via --device).

Vogon/E2E:entire login isn't in the agent E2E path, so no Vogon changes expected — verify no canary references the device prompt wording.

Phase 5 — Docs

• CLAUDE.md/command-layout docs: note login now defaults to browser redirect, --device for the old flow.
• auth-go CHANGELOG.md + README non-goals (Phase 1).
• Any --help long-text on the login command.

Key risks / footguns

• Backend path/registration mismatch (Phase 0) — the single thing that can invalidate the whole plan. Confirm before coding.
• Scope: entire-core's loopback omits scope; you must send cli offline_access or you lose the refresh token and silent refresh breaks.
• Don't hand-roll the token exchange like entire-core did — route it through oauthhttp so error/HTML/expiry handling matches the rest of auth-go.
• Cross-region iss: the CLI is split-host/multi-region; if the AS returns iss, the exchange must target it (entire-core does this). Ignoring it could break multi-region logins.
• Loopback reachability: the callback hits 127.0.0.1 on the CLI host — useless over plain SSH. The headless auto-fallback to device flow is what keeps remote logins working.