feat(oauth2): PKCE for device-code + configurable opt-out + refresh-backed bearer propagation

[stephane-segning]

Why

Two bugs surfaced bringing up a Keycloak device_code provider distributed via .well-known/opencode:

1. Device-code login 400s under PKCE enforcement. The device-code flow never sent PKCE, so a Keycloak client with Proof Key for Code Exchange Code Challenge Method set rejected the device-authorization request with invalid_request: Missing parameter: code_challenge_method. (authorization_code already did PKCE; device_code was the gap.)

2. @vymalo/opencode-models-info 401s fetching meta.modelsInfoUrl. Config-time bearer propagation read the raw cached token behind a fixed 30s expiry skew. On a first interactive login against a short-lived realm, the just-minted token already fell inside that window, so options.headers.Authorization was never stamped and models-info fetched the OAuth2-protected metadata endpoint with no token → models_info_fetch_failed_no_cache (HTTP 401).

What changed

PKCE

• Both interactive flows (authorization_code + device_code) send PKCE by default and replay the code_verifier on the token exchange/poll.
• New pkce?: boolean server option (default true), parsed from both config shapes, as an opt-out for non-compliant IdPs that reject the extra parameters. Compliant servers ignore PKCE, so it stays on unless explicitly disabled.

Bearer propagation

• propagateCachedBearer now goes through a refresh-only ensure (ensureAccessToken(id, { interactive: false })): valid tokens pass through, near-expiry ones are transparently refreshed, and anything that would need a fresh browser/device-code prompt is skipped (oauth2_bearer_propagation_skipped_no_token) rather than blocking startup. Removed the dead skew constant/helper.
• ensureAccessToken gained an interactive param so config-time propagation never triggers a second login.

Docs

• New docs/well-known.md — how .well-known/opencode distributes a provider + plugin setup: the auth/config blocks, the echo plugin-managed placeholder-key pattern, where config and tokens actually live (re-fetched from the server each launch; only a pointer in auth.json; the OAuth token in the plugin cache), the CLI, gotchas, and how to serve your own.
• architecture.md (config step 6 rewrite + PKCE section + new log event), models-info.md (TTL/no-cache/seeding answer — cache is already 1-day TTL by default), troubleshooting.md (two symptom-keyed entries), oauth2 README (pkce row).

Tests

+4 (159 total passing): device-code PKCE opt-out; config pkce default/false/reject; and a regression test proving a near-expiry token is refreshed during propagation so the header carries the fresh token.

Build, typecheck, lint, and format all clean.

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces PKCE support by default for interactive OAuth2 flows (authorization_code and device_code) with an opt-out configuration, and updates bearer token propagation to use a refresh-only token retrieval mechanism instead of a raw cache read, preventing downstream 401 errors. It also adds extensive documentation on configuration distribution and troubleshooting. Feedback suggests adding a debug log when a retrieved token is empty to improve observability, and executing bearer propagation in parallel using Promise.all to prevent sequential network requests from delaying startup.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.