cognito: a Cognito PKCE login flow for CLIs

[lei-wego]

Adds github.com/wego/pkg/cognito: the Cognito authorization-code-with-PKCE login a command-line tool uses to obtain a human operator's tokens, plus a cognito/storage subpackage that caches the token set in the OS keychain.

This is the CLI-side counterpart to http/jwt. That package verifies a token arriving at a service; this one obtains a token at a terminal. Nothing in the repo covered the second half before.

Extracted from the payments repo's pay-admin CLI (wego/payments#2300), where it was written against these constraints from the start, so the move needed no redesign — package rename and import paths only.

API

type Config struct {
    AuthorizeURL, TokenURL, ClientID, RedirectURI string
    Scopes, AllowedDomain, CallbackAddr           string
    IdentityProvider                              string             // optional: skip Cognito's IdP chooser
    OpenBrowser                                   func(string) error // nil => OS default
    NoBrowser                                     bool               // suppress the launch, report the URL instead
    PromptURL                                     func(string) error // receives the URL when NoBrowser is set
    HTTPClient                                    *http.Client       // nil => sane default
    Now                                           func() time.Time   // nil => time.Now
}

func Login(ctx context.Context, cfg Config) (*TokenSet, error)
func Refresh(ctx context.Context, cfg Config, refreshToken string) (*TokenSet, error)

type TokenSet struct{ AccessToken, IDToken, RefreshToken string; ExpiresAt time.Time }
func (t *TokenSet) IsExpired(now time.Time) bool
func (t *TokenSet) Email() (string, error)

// cognito/storage
type Store interface{ Load(ns string) (*cognito.TokenSet, error); Save(...) error; Delete(...) error }
func NewKeyring(service string) Store
func NewMemory() Store

Headless sign-in

NoBrowser suppresses the launch and hands the authorize URL to PromptURL instead, for a headless shell, a terminal on a remote host, or a caller that wants to surface the URL its own way. Everything else is unchanged: same PKCE challenge, same state, code still delivered to the loopback listener.

PromptURL is a func rather than a bool-plus-stdout so the library never writes to a stream the caller did not choose — it can print, render a QR code, or hand the URL to another process. Setting NoBrowser without it is refused at validation.

One limit is documented on the field rather than papered over: the redirect still lands on CallbackAddr, so a browser on a different machine than the CLI needs that port forwarded (ssh -L). Suppressing the launch does not move where the code is delivered.

Two properties worth preserving

• No package-level mutable state. Every dependency — clock, HTTP client, browser opener, identity provider — arrives through Config, so one process can hold several environments live at once. http/jwt keeps its JWKS URL and header in package globals and can therefore serve exactly one issuer; payments' bo-refunds plan records that as the reason a second issuer became cross-team work. This package deliberately does not repeat the shape.
• Stdlib-only OAuth (bar wego/pkg/strings). Hand-rolling the exchange keeps every wire parameter visible and auditable, which matters more here than the convenience an OAuth library buys.

Security-relevant behaviour

Verifier and state both come from crypto/rand; state is compared with subtle.ConstantTimeCompare and a blank value on either side is a non-match. The challenge is S256. The callback listener binds loopback only and is single-use; neither the code nor error_description is interpolated into the served HTML. Email() parses the id_token without verifying its signature — correct here because the token came from the token endpoint over TLS or the caller's own keychain, and it is documented as such — and it cannot panic on malformed input. No token, verifier, or state appears in any error string.

Kept as one module

Splitting storage into its own module would force cognito to be tagged before storage could require it, and every other module here requires tagged siblings with no replace. Import paths are identical either way, so the only cost is that an OAuth-only consumer also pulls go-keyring.

Testing

go test ./... — cognito 95.4%, cognito/storage 94.7%. The uncovered lines are the ones that touch the OS: the browser exec and the real keychain adapter, both behind unexported seams so the logic around them is covered. NewMemory carries the full Store contract tests so nothing pops a keychain prompt in CI.

After merge

Tag cognito/v0.1.0 via ./auto_version, then wego/payments#2300 drops its in-repo copy and requires the tag. sdc-cli has the same duplicated flow and can adopt it in a follow-up.

[yanyi-wego]

Review withdrawn.

Withdrawn because internal review context was posted to this public repository in error.