[COR-174] auth: shareable auth library + split-host config + RFC 8693 token exchange

[khaong]

https://entire.io/gh/entireio/cli/trails/327

Summary

Linear: COR-174

Note

STS endpoint will be moving soon. v2 currently exposes the RFC 8693 token-exchange endpoint at /api/authz/sts/token (encoded in provider.go's v2 surface). Server-side work is in flight to relocate it; once that lands, the new path moves into the auth-go repo's provider config in this CLI and the CLI side is a one-line bump.

Enables the partial.to staging deployment where the auth issuer (us.auth.partial.to) and the data API (partial.to) live on different origins by introducing per-resource RFC 8693 token exchange, then extracts the resulting library out of this repo into a standalone module so other internal CLIs can adopt the same pattern.

Library: now lives at github.com/entireio/auth-go (v0.1.0)

The auth/ directory in this repo is gone — its contents have been split out via git subtree split --prefix=auth into a standalone MIT-licensed Go module with preserved history. The CLI now imports github.com/entireio/auth-go/{deviceflow,sts,tokens,tokenstore,tokenmanager} instead of carrying them inline.

What that buys us:

• Shareable. Other internal CLIs can go get github.com/entireio/auth-go and reuse the same OAuth plumbing instead of reimplementing it. No vendoring, no copy-paste drift.
• No coupling. The library has zero references to github.com/entireio/cli — every endpoint, identifier, and default value is supplied by Config.
• Independent release cadence. Tightening the library's public API doesn't gate on a CLI release; the CLI bumps when it wants to pick up new tags.

Subpackages, all provider-agnostic:

Package	Role
deviceflow	RFC 8628 OAuth 2.0 Device Authorization Grant client
sts	RFC 8693 OAuth 2.0 Token Exchange client
tokens	TokenSet value type + unverified JWT claim parsing (rejects alg:none)
tokenstore	Persistence interface + Keyring reference impl
tokenmanager	Orchestration: cache, JWT-aud shortcut, exchange dispatch

CLI-side wiring

• Split-host config: new ENTIRE_AUTH_BASE_URL env var; AuthBaseURL() falls back to BaseURL() so single-host deployments are unchanged. Tokens are now keyed in the keyring by the auth issuer (the host that minted them). Auth-management commands (auth list/revoke/status/logout) routed to the auth host since their endpoints live there.
• NewAuthenticatedAPIClient routes through the manager. Data-API calls obtain a resource-audience bearer via RFC 8693 exchange when the core token's audience doesn't already match. All 8 callers thread ctx: activity, dispatch_wizard, recap, search, trail (×4 plus watch). Search additionally defaults serviceURL to api.BaseURL() and normalizes path-bearing URLs to scheme+host before token resolution.
• Dispatch joins the manager-routed path. entire dispatch was the last command sending the raw core token to the data API; mode_cloud now resolves through auth.TokenForResource like search/trail/recap.
• v2 client_id aligned to entire-cli (matched v1).
• Provider table carries stsPath per surface; v2's STS lives at /api/authz/sts/token. v1 is single-host, so its stsPath is empty and tokenmanager.Config.STSPath is optional — the same-host shortcut wins. Misconfigured split-host setups fail loudly via ErrNoSTSPath.

Security hardening (defense in depth)

Four findings landed in addition to the core split-host work, all on top of server-side validation:

1. Reject JWTs with alg:none — tokens.ParseClaims decodes the JWT header and refuses the RFC 7515 unsigned shape. Case-insensitive, trims whitespace. Even though the CLI's claim use is documented as routing-only, the unsigned shape would let a hostile AS bypass shape checks. New tokens.ErrUnsignedJWT sentinel + 5 regression test cases.
2. Enforce HTTPS on STS and device-flow endpoints. Both clients reject http:// BaseURLs unless AllowInsecureHTTP is set, which the CLI auto-permits only for loopback hosts (localhost, 127.0.0.1, ::1). Production never qualifies; local dev does. New ErrInsecureBaseURL sentinel on each.
3. Validate verification_uri before showing it to the user or opening it in a browser. Rejects: non-URL, non-HTTPS (loopback http only), embedded userinfo (user:pass@host eye-trick), and control characters. New ErrUnsafeVerificationURI sentinel + comprehensive tests on safe/unsafe shapes.
4. Validate received token in login.go before persisting. validateReceivedToken parses the JWT (if it is one), rejects alg:none, hard-rejects iss mismatch vs. the configured issuer, and rejects already-expired exp. Opaque (non-JWT) tokens are permitted — the AS may not issue JWTs at all.

Plus a defense soph added earlier in PR #1156: the keyring fallback rejects JSON-shaped values so corruption never ships as a Bearer header.

Other behaviour fixes surfaced during review

• Store.LoadTokens legacy bare-string fallback was unreachable — it only fired on ErrNotFound, but a pre-shim raw-token entry produced an unmarshal error. Added tokenstore.ErrMalformed so callers can distinguish "no entry" from "entry exists but malformed" and route the legacy path correctly.
• tokenmanager.runExchange was silently dropping req.Resource — sts.ExchangeRequest.Resource (RFC 8693 §2.1) was never sent to the AS.
• JWT-aud shortcut in tokenmanager.Token now gated on empty Audience so an explicit per-call Audience always forces an exchange (was silently downgraded if the core token's aud happened to include the resource).
• tokenmanager.DeleteCoreToken order swapped: keyring delete first, in-memory cache clear only on success — pre-emptive clear created a window where the CLI thought it was logged out but the keyring still held the token.
• api.bearerTransport rejects empty bearer at first request rather than putting Authorization: Bearer<space> on the wire (which produced confusing 401s).
• PollDeviceAuth shim now surfaces unknown OAuth error codes through DeviceAuthPoll.Error so login's polling loop fails fast on terminal rejections instead of retrying ~5×.
• tokenmanager cache key is now a struct map key instead of a delimiter-joined string — structurally collision-free.
• freezeClock in deviceflow/sts tests is no longer t.Parallel() (latent race against any future parallel test reading nowFunc).

Test plan

• mise run fmt && mise run lint clean.
• go test ./... — only the two pre-existing main failures (TestGroupCommitsByDay_SortsNewestFirst, TestExplainCmd_PositionalArgConflictsWithFlags, plus TestExplainCmd_SummaryTimeoutSecondsValidation from a recent main commit) remain.
• go test -race ./... — no new races.
• entireio/auth-go repo builds and tests pass standalone at the v0.1.0 tag.
• End-to-end against the partial.to staging deployment: entire login, entire trail list, entire search, entire dispatch all working through the device flow → STS exchange → resource-scoped bearer chain.

Notes for reviewers

• The branch is 21 commits ahead of main. Easiest review path is by commit. The meaningful new work starts at c492a54b1. Most-substantial commits:
  • c492a54b1 — split-host + tokenmanager (largest single change)
  • a9aeb9e6f — dispatch routing fix + the CLAUDE.md "Auth and token resolution" section + the auth-go README
  • dc7c003e4 — soph's review follow-ups (PR auth: review follow-ups (provider routing, URL normalization, expiry preflight, HTTP timeouts) #1156, already merged via merge commit)
  • 706a4a28e — defense-in-depth security hardening (the four findings above)
  • 8821a55ae — subtree extraction into entireio/auth-go; CLI imports rewritten, local auth/ deleted
• The extracted-library PRs (constructor parity for auth-go's deviceflow.Client / sts.Client, moving tokenmanager.Config.Now/Exchange off the public Config, renaming TokenRequest.Resource → ResourceURL, typed-error replacement of descriptionFromSentinel) now ship as auth-go v0.2.0 work, independent of this CLI PR.

🤖 Generated with Claude Code

---

Note

High Risk
High risk because it changes how the CLI resolves, stores, and uses bearer tokens (including new split-host routing and token exchange), affecting authentication and every authenticated API call path.

Overview
Enables split-host deployments by adding ENTIRE_AUTH_BASE_URL (auth issuer) alongside ENTIRE_API_BASE_URL (data API), updating token storage/lookups to key off the auth origin, and validating both origins for HTTPS.

Moves token resolution for data-API callers to auth.TokenForResource / cli.NewAuthenticatedAPIClient(ctx, ...), which can perform RFC 8693 token exchange and cache results; command flows like activity, search, dispatch, trail, recap, and completion paths are updated to thread context.Context and use resource-scoped bearers.

Refactors auth management endpoints to be provider-version routed via auth.CurrentProvider() and api.Client.WithAuthTokensPath, adds provider table + tests, replaces the in-repo device-flow client with an auth-go/deviceflow shim (including improved surfacing of OAuth error codes/descriptions), and adds defense-in-depth checks like rejecting empty bearer requests and validating login tokens (issuer/expiry/unsigned JWT).

^{Reviewed by Cursor Bugbot for commit 8821a55. Configure here.}

[Copilot]

Pull request overview

This PR introduces a provider-agnostic, shareable auth library (auth/…) and migrates the CLI to use it, enabling split-host deployments (separate auth issuer and data API origins) via RFC 8693 token exchange.

Changes:

• Added a new root-level auth library implementing RFC 8628 device flow, RFC 8693 token exchange, token persistence, JWT claim parsing, and a token manager with caching/exchange orchestration.
• Added split-host configuration (ENTIRE_AUTH_BASE_URL) and updated CLI auth/token storage and auth-management endpoints to route to the auth origin.
• Updated CLI API client creation and entire search to resolve resource-scoped tokens (including URL-origin normalization) and thread context.Context through authenticated client creation.

Reviewed changes

Copilot reviewed 40 out of 40 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
cmd/entire/cli/trail_cmd.go	Passes ctx into authenticated API client creation.
cmd/entire/cli/search/search.go	Clarifies GitHubToken field meaning for backwards compatibility.
cmd/entire/cli/search_cmd.go	Routes search via token manager; defaults service URL to api.BaseURL(); normalizes resource origin.
cmd/entire/cli/search_cmd_test.go	Adds coverage for search service URL → origin normalization.
cmd/entire/cli/recap.go	Passes ctx into authenticated API client creation.
cmd/entire/cli/logout.go	Routes logout revocation calls to auth base URL.
cmd/entire/cli/login.go	Uses legacy token save shim; surfaces RFC 8628 error_description on failures.
cmd/entire/cli/integration_test/login_test.go	Sets auth base URL + provider version for login integration tests.
cmd/entire/cli/dispatch_wizard.go	Passes ctx into authenticated API client creation.
cmd/entire/cli/auth/store.go	Wraps shared tokenstore.Keyring while preserving legacy bare-token fallback reads; keys tokens by auth issuer.
cmd/entire/cli/auth/store_test.go	Adds tests for legacy bare-string fallback behavior.
cmd/entire/cli/auth/provider.go	Introduces provider version switch (v1/v2) including per-provider STS path.
cmd/entire/cli/auth/provider_test.go	Tests provider selection and client wiring.
cmd/entire/cli/auth/exchange.go	Adds CLI shim over tokenmanager.Manager (singleton + test injection).
cmd/entire/cli/auth/exchange_test.go	Tests shim delegation and ErrNotLoggedIn aliasing.
cmd/entire/cli/auth/client.go	Replaces bespoke device-flow client logic with shared auth/deviceflow client + compatibility shim types.
cmd/entire/cli/auth/client_test.go	Removes tests for old JSON decoding helpers (now in shared oauthhttp helpers).
cmd/entire/cli/auth.go	Validates both API and auth origins for HTTPS; routes auth-management commands to auth base URL.
cmd/entire/cli/api/client.go	Adds NewClientWithBaseURL; fails early on empty bearer tokens at first request.
cmd/entire/cli/api/client_test.go	Adds test ensuring empty bearer tokens are rejected.
cmd/entire/cli/api/base_url.go	Adds ENTIRE_AUTH_BASE_URL and AuthBaseURL() fallback to BaseURL().
cmd/entire/cli/api/base_url_test.go	Adds tests for AuthBaseURL() fallback/override behavior.
cmd/entire/cli/api/auth_tokens.go	Routes auth-token endpoints by provider version; documents v1/v2 differences.
cmd/entire/cli/api/auth_tokens_test.go	Adds tests for provider-version routing and v2 path selection.
cmd/entire/cli/api_client.go	Reworks authenticated API client creation to use token manager + RFC 8693 exchange when needed.
cmd/entire/cli/activity_cmd.go	Passes ctx into authenticated API client creation.
auth/tokenstore/tokenstore.go	Defines persistence interface and sentinel errors (ErrNotFound, ErrMalformed).
auth/tokenstore/keyring.go	Implements keyring-backed tokenstore.Store with JSON TokenSet encoding and malformed-entry signaling.
auth/tokenstore/keyring_test.go	Adds tests for keyring round-trips and malformed-entry behavior.
auth/tokens/tokens.go	Introduces TokenSet + unverified JWT claims parsing helpers.
auth/tokens/tokens_test.go	Adds tests for expiry helpers and JWT claim parsing.
auth/tokenmanager/tokenmanager.go	Adds manager orchestration: core token lookup, same-host / aud shortcuts, RFC 8693 exchange, caching.
auth/tokenmanager/tokenmanager_test.go	Adds comprehensive tests for exchange dispatch, caching, shortcuts, and failure modes.
auth/sts/sts.go	Adds RFC 8693 token-exchange client.
auth/sts/sts_test.go	Adds tests for form construction, error surfacing, and expiry handling.
auth/internal/oauthhttp/jsonresp.go	Adds shared JSON response decoding with HTML/non-JSON detection.
auth/internal/oauthhttp/jsonresp_test.go	Tests strict/tolerant decoding and HTML detection behavior.
auth/doc.go	Documents the new auth library package structure and goals.
auth/deviceflow/deviceflow.go	Adds RFC 8628 device-flow client with sentinel error mapping and strict/tolerant decoding rules.
auth/deviceflow/deviceflow_test.go	Adds tests for device-flow success/error behaviors, including error_description handling.

[khaong]

bugbot run

[khaong]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 9c2b070. Configure here.}

[khaong]

bugbot run

[cursor]

Cursor Bugbot has reviewed your changes and found 4 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 8821a55. Configure here.}

[cursor]

Recap wraps STS exchange errors as keyring errors

Medium Severity

newRecapClient wraps all non-ErrNotLoggedIn errors from auth.TokenForResource as &keyringReadError{Cause: err}. Previously this was correct because auth.LookupCurrentToken only touched the keyring. Now auth.TokenForResource can also fail during RFC 8693 token exchange (STS network errors, protocol errors) or manager construction. The caller in runRecap matches errors.As(err, &keyringErr) and shows "Could not read your auth token from the system keyring … Check your OS keychain settings" — completely misleading for STS failures in split-host deployments.

Additional Locations (1)

• cmd/entire/cli/recap.go#L125-L137

 

^{Reviewed by Cursor Bugbot for commit 8821a55. Configure here.}

[cursor]

Issuer normalization strips full path, not just trailing slash

Low Severity

normalizeIssuer is documented as "trim trailing slashes" in issMatches, but it actually strips the entire Path, RawQuery, and Fragment from URLs. A JWT with iss: "https://issuer.example/different-tenant" would pass validation against expected issuer "https://issuer.example" because both normalize to the same origin. This weakens the defense-in-depth issuer mismatch check beyond its stated intent.

Additional Locations (1)

• cmd/entire/cli/login.go#L279-L280

 

^{Reviewed by Cursor Bugbot for commit 8821a55. Configure here.}

[cursor]

SetManagerForTest lacks mutex unlike SetProviderForTest

Low Severity

managerForTest is read and written without synchronization in both SetManagerForTest and defaultManager. The analogous providerForTest in provider.go properly uses providerTestMu for all accesses. This inconsistency means concurrent test goroutines calling defaultManager() while SetManagerForTest runs could hit a data race, even though current tests avoid it by being non-parallel.

Additional Locations (1)

• cmd/entire/cli/auth/exchange.go#L48-L52

 

^{Reviewed by Cursor Bugbot for commit 8821a55. Configure here.}

[cursor]

Dead lookupCurrentToken variable with misleading comment

Low Severity

lookupCurrentToken is declared and initialized but never called in production code — mode_cloud.go now uses lookupResourceToken exclusively. The comment claims "existing tests that swap lookupCurrentToken keep working because the default lookupResourceToken delegates to it," which is incorrect: auth.TokenForResource and auth.LookupCurrentToken are independent functions. Tests actually work because they set both variables. The misleading comment could cause future test authors to only set lookupCurrentToken, which would have no effect.

 

^{Reviewed by Cursor Bugbot for commit 8821a55. Configure here.}