[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, provider.stsPath flips to the new path and the CLI side is a one-line change. No CLI release is needed in the interim — v1 is single-host and unaffected, and v2 staging deployments can stay pinned until the move completes.

Stands up a shareable auth library at the repo root (auth/...) and migrates the CLI's auth wiring onto it. Also 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.

• auth/ library (new + reorganised): deviceflow (RFC 8628), sts (RFC 8693), tokens (TokenSet + JWT claim parsing), tokenstore (pluggable persistence + Keyring impl), and the new tokenmanager (orchestration: cache, JWT-aud shortcut, exchange dispatch). The library is provider-agnostic — every endpoint, identifier, and default value comes from Config. No env-var reads, no globals, no implicit URLs. Ready to share with other internal CLIs.
• 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 and entire search go 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 7 callers thread ctx. Search now defaults serviceURL to api.BaseURL() (was hardcoded entire.io) and normalizes path-bearing URLs to scheme+host before token resolution.
• 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.

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. Store.GetToken was over-permissive in the opposite direction (any error → fallback, masking real keyring failures); now also gated on ErrMalformed.
• tokenmanager.runExchange was silently dropping req.Resource — sts.ExchangeRequest.Resource (RFC 8693 §2.1) was never sent to the AS. Fixed and tested.
• 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).

Test plan

• mise run fmt && mise run lint clean
• go test ./auth/... — all pass
• go test ./cmd/entire/cli/auth/... ./cmd/entire/cli/api/... — all pass
• Tested end-to-end against the partial.to staging deployment — entire login, entire trail list, entire search all working through the device flow → STS exchange → resource-scoped bearer chain
• go test ./cmd/entire/cli/... — only the two pre-existing failures (TestGroupCommitsByDay_SortsNewestFirst, TestExplainCmd_PositionalArgConflictsWithFlags) remain, unchanged from main

Notes for reviewers

• The branch picks up earlier commits already merged on prior PRs (the auth/sts package, RFC 8628 §3.5 error_description support, the v1/v2 provider switch, etc.). Easiest review path is by commit — the meaningful new work starts at c492a54b1:
  • c492a54b1 — split-host + tokenmanager (largest commit)
  • d9322bc2a — STS path on provider, STSPath optional
  • ead027cf9 — search routing
  • 16746fd66 — round-1 review fixes (legacy fallback bug, doc rot, v2 path coverage, empty-bearer guard)
  • 5173d30fc — round-2 review fixes (DeleteCoreToken ordering, additional coverage, deprecation tags)
  • f33b79dfc — codex review fixes (Audience-gates-aud-shortcut, Resource on STS, search URL normalization)
  • d8ccd264a — test isolation against provider env
• Deferred to a follow-up PR (separate, focused refactor): constructor parity for auth/deviceflow.Client + auth/sts.Client, moving tokenmanager.Config.Now/Exchange off the public Config to test-only seams, TokenRequest.Resource → ResourceURL rename, tokens.ParseClaims value-return, typed-error replacement of descriptionFromSentinel, expose tokenstore.Keyring.Service() as a getter.

🤖 Generated with Claude Code

---

Note

High Risk
High risk because it rewires core authentication/token storage and introduces RFC 8693 token exchange plus new base-URL routing, which can cause login failures or 401s across CLI commands if misconfigured.

Overview
Adds a new shareable auth/ Go library implementing OAuth device flow (RFC 8628), token exchange (RFC 8693), token persistence, and a tokenmanager that caches resource-scoped bearers and short-circuits when exchange isn’t needed.

Updates the CLI to support split auth/data origins via ENTIRE_AUTH_BASE_URL and provider-version routing via ENTIRE_AUTH_PROVIDER_VERSION, moving authenticated calls (e.g. NewAuthenticatedAPIClient, search, dispatch) to resolve per-resource tokens through the manager rather than reading the keyring directly.

Refactors keyring storage to JSON-encoded token bundles with explicit ErrMalformed handling and legacy bare-string fallback, routes auth-token management endpoints to the auth host, and tightens request safety (reject empty bearer, enforce secure URL checks for both auth and data hosts).

^{Reviewed by Cursor Bugbot for commit 9c2b070. 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.}