fix(auth): validate credential proxy payloads (Fixes #2197)

[acoliver]

TLDR

Validates credential-proxy response frames, operation payloads, requests, and provider-returned OAuth tokens with Zod before they become trusted values. Existing protocol errors, sandbox ordering, request correlation, and refresh-token isolation remain unchanged.

Dive Deeper

The proxy transport is framed JSON over Unix sockets or Windows named pipes. This change adds shared schemas for response envelopes, OAuth token data, sanitized tokens, bucket statistics, provider lists, bucket lists, and API-key responses. Client stores parse successful operation data and now reject malformed values with PROXY_PAYLOAD_ERROR instead of returning cast values or fabricated statistics.

Provider-side request schemas validate credential and OAuth fields before store, flow, or session use. Exchange, poll, and refresh results are parsed before persistence and cooldown mutation. Provider extension fields survive parsing and merging, while refresh_token stays host-side and is removed from proxy responses.

Behavioral coverage uses real framed clients and servers for malformed envelopes, wrong-typed request fields, token persistence, extension preservation, stable operation errors, sandbox behavior, and refresh cooldown handling.

Reviewer Test Plan

1. Run npm run test, npm run lint, npm run typecheck, npm run format:check, and npm run build.
2. Review proxy-socket-client.test.ts for malformed handshake, correlated-frame rejection, connection reset, and ignored uncorrelated frames.
3. Review the client store tests for valid and malformed token, list, stats, and API-key response data.
4. Review the provider proxy tests for wrong-typed request fields, refresh-token stripping, host refresh-token preservation, malformed provider token rejection before persistence, and extension-preserving exchange, poll, and refresh behavior.

Local results on macOS:

• Focused proxy and OAuth tests passed.
• Full npm run test, lint, typecheck, format check, and build passed.
• The changed-test audit found 2,015 normalized findings on both origin/main and this branch, with zero scanner errors and an empty diff.
• bun scripts/start.ts --profile-load stepfun-37 "write me a haiku and nothing else" reached the configured provider but exited 1 with HTTP 400: you have no active step plan subscription. This is an external account limitation.

Testing Matrix

	🍏	🪟	🐧
npm run	✅	❓	❓
npx	❓	❓	❓
Docker	❓	❓	❓
Podman	❓	-	-
Seatbelt	❓	-	-

Linked issues / bugs

Fixes #2197

Summary by CodeRabbit

• Bug Fixes
  • Improved validation of authentication requests, tokens, API keys, provider data, and bucket statistics.
  • Malformed proxy responses and invalid OAuth inputs are now rejected with consistent errors.
  • Prevented invalid or failed token exchanges and refreshes from being stored.
  • Preserved supported token extension fields while continuing to protect refresh tokens.
• Tests
  • Expanded coverage for malformed requests, responses, handshakes, tokens, and storage failures.
• Refactor
  • Standardized credential-proxy payload validation and publicly exposed related schemas.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: a2a047f7-5a9e-42c1-86ed-a710755a4893

📥 Commits

Reviewing files that changed from the base of the PR and between 3549572 and c9a1900.

⛔ Files ignored due to path filters (1)

• project-plans/issue-2197-proxy-payload-validation.md is excluded by !project-plans/**

📒 Files selected for processing (20)

• packages/auth/src/__tests__/token-sanitization.test.ts
• packages/auth/src/index.ts
• packages/auth/src/proxy/__tests__/proxy-provider-key-storage.test.ts
• packages/auth/src/proxy/__tests__/proxy-socket-client.test.ts
• packages/auth/src/proxy/__tests__/proxy-token-store.test.ts
• packages/auth/src/proxy/proxy-payload-schemas.ts
• packages/auth/src/proxy/proxy-provider-key-storage.ts
• packages/auth/src/proxy/proxy-socket-client.ts
• packages/auth/src/proxy/proxy-token-store.ts
• packages/auth/src/token-sanitization.ts
• packages/providers/src/auth/proxy/__tests__/credential-proxy-payload-validation.test.ts
• packages/providers/src/auth/proxy/__tests__/credential-proxy-server.test.ts
• packages/providers/src/auth/proxy/__tests__/oauth-exchange.spec.ts
• packages/providers/src/auth/proxy/__tests__/oauth-initiate.spec.ts
• packages/providers/src/auth/proxy/__tests__/oauth-poll.spec.ts
• packages/providers/src/auth/proxy/__tests__/refresh-coordinator.test.ts
• packages/providers/src/auth/proxy/credential-proxy-oauth-handler.ts
• packages/providers/src/auth/proxy/credential-proxy-server.ts
• packages/providers/src/auth/proxy/credential-request-validation.ts
• packages/providers/src/auth/proxy/refresh-coordinator.ts

Included review availability: Your plan provides up to 4 included reviews per hour; 1 remains after this review.

---

📝 Walkthrough

Walkthrough

The auth proxy now validates IPC and HTTP payloads with shared Zod schemas. Token sanitization preserves extension fields while removing refresh_token. Proxy clients, token stores, credential handlers, and refresh coordination parse boundary data before storage or response handling. Tests cover malformed payloads, frames, tokens, statistics, and persistence failures.

Changes

Validation contracts

Layer / File(s)	Summary
Shared payload and request schemas packages/auth/src/proxy/proxy-payload-schemas.ts, packages/auth/src/token-sanitization.ts, packages/providers/src/auth/proxy/credential-request-validation.ts, packages/auth/src/index.ts	Adds schemas for proxy envelopes, operation payloads, sanitized tokens, and credential requests. Exports the new schemas through the auth package API.

Socket frame validation

Layer / File(s)	Summary
Validated proxy socket responses packages/auth/src/proxy/proxy-socket-client.ts, packages/auth/src/proxy/__tests__/proxy-socket-client.test.ts	Parses handshake and response frames with ProxyResponseSchema. Requires non-empty correlation IDs. Tests malformed frames, reconnect behavior, and ignored uncorrelated frames.

Auth payload consumers

Layer / File(s)	Summary
Validated token and key-store responses packages/auth/src/proxy/proxy-token-store.ts, packages/auth/src/proxy/proxy-provider-key-storage.ts, packages/auth/src/proxy/__tests__/proxy-token-store.test.ts, packages/auth/src/proxy/__tests__/proxy-provider-key-storage.test.ts	Parses OAuth token, provider, bucket, bucket-statistics, API-key, and existence payloads. Tests malformed and valid response data.

Provider boundary parsing

Layer / File(s)	Summary
Credential proxy request and response handling packages/providers/src/auth/proxy/credential-proxy-server.ts, packages/providers/src/auth/proxy/credential-proxy-oauth-handler.ts, packages/providers/src/auth/proxy/refresh-coordinator.ts	Validates request fields and parses tokens and statistics before persistence or serialization. Refresh results now use a discriminated union with sanitized tokens.

Boundary regression coverage

Layer / File(s)	Summary
Malformed-input and persistence tests packages/auth/src/__tests__/token-sanitization.test.ts, packages/providers/src/auth/proxy/__tests__/*	Adds coverage for invalid request types, malformed tokens and statistics, refresh behavior, extension preservation, refresh-token fallback, and storage failures.

Estimated code review effort: 4 (Complex) | ~60 minutes

Merge Risk: ⚪ Minimal · up to c9a19

The change adds credential-proxy payload validation while preserving existing protocol, sandbox, correlation, and token-isolation behavior; no actionable merge-blocking risk remains after normal checks and review.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 16.67% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 6 functions across 20 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes satisfy issue #2197. They add schemas for proxy frames, tokens, sanitized tokens, statistics, lists, and API-key payloads; parse IPC and HTTP data; replace applicable casts; preserve proto…
Out of Scope Changes check	✅ Passed	The implementation and tests remain focused on credential-proxy payload validation, trust-boundary parsing, error preservation, token isolation, and related regression coverage. No unrelated changes a…
Title check	✅ Passed	The title clearly and concisely identifies the main change: validating credential proxy payloads. It also references the linked issue.
Description check	✅ Passed	The description covers the required TLDR, technical details, reviewer test plan, testing results, testing matrix, and linked issue. The testing matrix is incomplete for platforms and tools not tested,…

Full details: Linked Issues check

Explanation

The changes satisfy issue #2197. They add schemas for proxy frames, tokens, sanitized tokens, statistics, lists, and API-key payloads; parse IPC and HTTP data; replace applicable casts; preserve protocol and refresh-token behavior; and add broad malformed and valid payload tests.

Full details: Out of Scope Changes check

Explanation

The implementation and tests remain focused on credential-proxy payload validation, trust-boundary parsing, error preservation, token isolation, and related regression coverage. No unrelated changes are shown.

Full details: Description check

Explanation

The description covers the required TLDR, technical details, reviewer test plan, testing results, testing matrix, and linked issue. The testing matrix is incomplete for platforms and tools not tested, but the description is otherwise detailed and directly related to the changes.

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch issue2197

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Walkthrough

This PR changes 20 file(s).

• packages/auth/src/token-sanitization.ts: Replaces manual token sanitization with a Zod-validated schema. Introduces SanitizedOAuthTokenSchema using OAuthTokenSchema.passthrough().transform() to strip refresh_token while preserving provider-specific extension fields. sanitizeTokenForProxy now validates input via schema.parse() instead of plain destructuring, adding runtime payload validation for credential proxy flows.
• packages/providers/src/auth/proxy/credential-request-validation.ts: New file introducing Zod validation schemas for credential proxy API requests. Defines reusable required/optional string schemas and composes endpoint-specific schemas for provider selection, bucket-scoped operations, token saving, name lookup, OAuth initiation/exchange/session retrieval. Integrates SanitizedOAuthTokenSchema for save-token payloads, adding payload validation to the auth proxy layer.
• packages/providers/src/auth/proxy/__tests__/oauth-initiate.spec.ts: Added 3 test cases in oauth_initiate handler validating rejection of wrong-typed fields (provider as number, bucket as array, redirect_uri as object) with INVALID_REQUEST and 'Missing provider' error message.
• packages/auth/src/proxy/proxy-token-store.ts: Replaces unsafe as unknown as casts with schema-validated parsing in ProxyTokenStore. Each method now validates proxy responses through parseSuccessPayload using dedicated payload schemas (OAuthTokenDataSchema, ProvidersDataSchema, BucketsDataSchema, BucketStatsDataSchema), removing manual type assertions and ad-hoc property extraction. This ensures malformed proxy payloads throw validation errors instead of producing undefined or incorrectly typed values at runtime.
• packages/providers/src/auth/proxy/refresh-coordinator.ts: This change tightens the auth proxy refresh path by validating refreshed tokens against OAuthTokenDataSchema and explicitly sanitizing merged tokens before returning them. The RefreshResult type is refactored from a loose interface into a stricter discriminated union where token is required on 'ok' and typed as SanitizedOAuthToken. The refresh flow now parses the raw connection token, merges it, sanitizes the merged result for proxy use, and returns it via satisfies RefreshResult instead of a loose cast.
• packages/providers/src/auth/proxy/__tests__/oauth-poll.spec.ts: Three new test cases were added to the oauth_poll handler suite. They verify that malformed session_id payloads (wrong types) are rejected with INVALID_REQUEST for both oauth_poll and oauth_cancel, and that a token with a non-timestamp expiry is not persisted to the backing store.
• packages/auth/src/proxy/proxy-payload-schemas.ts: Adds narrowly scoped Zod schemas to validate credential-proxy payloads at the IPC trust boundary. Defines a passthrough response envelope schema, operation-specific success payload schemas for token/provider/bucket/API key operations, a stable proxy payload error helper, and a generic parseSuccessPayload function that throws on missing or malformed data. Addresses issue Validate auth proxy payloads at IPC and HTTP boundaries (Follow-up to #2159) #2197 by ensuring proxy responses are validated before use.
• packages/auth/src/__tests__/token-sanitization.test.ts: Adds a new test case verifying that sanitizeTokenForProxy rejects malformed tokens at the proxy boundary. The test constructs an OAuthToken with a non-string access_token using Reflect.set and asserts the function throws an error matching /access_token/, strengthening input validation coverage.
• packages/auth/src/proxy/proxy-socket-client.ts: Replaced local ProxyResponse type and ad-hoc type guard with schema-based validation using ProxyResponseSchema.safeParse. Removed isProxyResponseFrame and introduced internal parseResponseFrame returning ProxyResponse | null. Updated handshake and request resolution to use parsed frames, rejecting malformed responses. Tightened request ID validation in resolvePendingRequest to reject empty strings. Re-exported ProxyResponse type from proxy-payload-schemas.
• packages/auth/src/proxy/proxy-provider-key-storage.ts: Updated ProxyProviderKeyStorage to validate proxy responses using typed payload schemas instead of casting response.data directly. getKey, listKeys, and hasKey now parse through ApiKeyDataSchema, ApiKeysDataSchema, and HasApiKeyDataSchema respectively via parseSuccessPayload, adding runtime validation for credential proxy payloads.
• packages/auth/src/proxy/__tests__/proxy-token-store.test.ts: Added comprehensive ProxyTokenStore validation tests covering valid OAuth tokens with provider extensions, malformed/wrong-typed token and bucket-stats payloads, non-string provider/bucket lists, and scalar wrappers. Updated existing bucket-stats test to assert real server data instead of fabricated zeros.
• project-plans/issue-2197-proxy-payload-validation.md: Added a project plan for validating credential-proxy payloads at IPC boundaries. The document defines six acceptance criteria (AC1-AC6) for response envelope validation, client payload parsing, inbound request validation, sanitized outbound tokens, and compatibility. It outlines a four-phase test-first implementation approach and includes a detailed review finding ledger with 26 findings classified as Blocker-Fix, In-scope-Fix, Reject, or Defer.
• packages/providers/src/auth/proxy/credential-proxy-server.ts: Replaces ad-hoc payload extraction with schema validation across credential proxy handlers. Adds imports for Request validation schemas and auth data schemas, uses safeParse for provider/bucket/name/token payloads, parses existing tokens and bucket stats through schemas, and returns the result of sendOk instead of discarding it. Early-error paths now return undefined consistently. This hardens request handling and type safety in the proxy server.
• packages/providers/src/auth/proxy/credential-proxy-oauth-handler.ts: Replaces manual type casts and presence checks in CredentialProxyOAuthHandler with schema validation. Introduces request schemas for OAuth initiate, exchange, session, and provider-bucket payloads, plus OAuthTokenDataSchema for token validation. Handlers now parse incoming payloads through safeParse, returning structured INVALID_REQUEST errors. Token responses are validated and sanitized before storage and relay, removing unsafe casts. This tightens input validation and ensures only well-formed credential proxy payloads and token data are accepted.
• packages/auth/src/proxy/__tests__/proxy-provider-key-storage.test.ts: Adds three regression tests for ProxyProviderKeyStorage payload validation: getKey rejects non-string key data, listKeys rejects arrays containing non-string entries, and hasKey rejects non-boolean exists fields, all throwing PROXY_PAYLOAD_ERROR.
• packages/providers/src/auth/proxy/__tests__/oauth-exchange.spec.ts: Adds test coverage for OAuth exchange validation: ensures extension-preserving parsed tokens are persisted while raw boundary objects are not, rejects wrong-typed session_id and code inputs with specific error messages, prevents storage of malformed tokens, and maps token store failures to EXCHANGE_FAILED without persisting. Also extends the in-memory token store with a saveError hook to simulate host storage failures.
• packages/providers/src/auth/proxy/__tests__/refresh-coordinator.test.ts: Added two test cases for RefreshCoordinator: one verifying provider-specific extension fields are preserved in stored merged tokens and sanitized responses during refresh, and another ensuring malformed tokens from refreshFn do not trigger cooldown timers. Added import for advanceTimersByTimeAsync to support timer advancement in tests.
• packages/providers/src/auth/proxy/__tests__/credential-proxy-payload-validation.test.ts: New test suite validating CredentialProxyServer payload handling. Covers wrong-typed and malformed inputs for get_token, save_token, remove_token, list_buckets, get_api_key, has_api_key, get_bucket_stats, and refresh_token. Verifies INVALID_REQUEST for invalid types, malformed token rejection without storage mutation, valid token storage preserving refresh_token and extension fields, and malformed outbound data returning INTERNAL_ERROR.
• packages/auth/src/proxy/__tests__/proxy-socket-client.test.ts: Adds regression tests for ProxySocketClient handshake validation and correlated request envelope handling. Covers malformed handshake responses, missing fields, null data, and wrong-typed error/retryAfter/code fields. Also tests malformed correlated request rejection with connection recovery and ignoring malformed responses without usable correlation IDs.
• packages/auth/src/index.ts: Exports proxy payload validation schemas and token sanitization utilities from the auth package entry point, enabling consumers to validate credential proxy payloads and sanitize OAuth tokens.

Changes

Layer	File(s)	Summary
auth	packages/auth/src/token-sanitization.ts, packages/auth/src/proxy/proxy-token-store.ts, packages/auth/src/proxy/proxy-payload-schemas.ts, packages/auth/src/proxy/proxy-socket-client.ts, packages/auth/src/proxy/proxy-provider-key-storage.ts, packages/auth/src/index.ts	Hardens auth proxy boundary by adding Zod-validated payload schemas, token sanitization, and replacing unsafe casts in token/key stores and socket client.
providers	packages/providers/src/auth/proxy/credential-request-validation.ts, packages/providers/src/auth/proxy/credential-proxy-server.ts, packages/providers/src/auth/proxy/credential-proxy-oauth-handler.ts, packages/providers/src/auth/proxy/refresh-coordinator.ts	Adds request/response validation and sanitized token handling to credential proxy server, OAuth handlers, and refresh coordination.
tests	packages/providers/src/auth/proxy/tests/oauth-initiate.spec.ts, packages/providers/src/auth/proxy/tests/oauth-poll.spec.ts, packages/providers/src/auth/proxy/tests/oauth-exchange.spec.ts, packages/providers/src/auth/proxy/tests/refresh-coordinator.test.ts, packages/providers/src/auth/proxy/tests/credential-proxy-payload-validation.test.ts, packages/auth/src/tests/token-sanitization.test.ts, packages/auth/src/proxy/tests/proxy-token-store.test.ts, packages/auth/src/proxy/tests/proxy-provider-key-storage.test.ts, packages/auth/src/proxy/tests/proxy-socket-client.test.ts	Covers malformed/wrong-typed proxy payloads, sanitization failures, and schema validation behavior across auth/proxy and providers/proxy flows.
docs	project-plans/issue-2197-proxy-payload-validation.md	Documents acceptance criteria and phased implementation plan for credential-proxy payload validation.

Magnitude

🎯 3 (L)
1578 additions, 166 deletions, 20 changed files across 2 packages, 1 acceptance criterion

Related

No related items found.

Pre-merge Checks

Check	Status	Note
Title	✅	Clear, descriptive, and includes the issue fix reference.
Description	✅	Includes all expected sections: TLDR, Dive Deeper, Reviewer Test Plan, Testing Matrix, and Linked issues / bugs.
Linked Issues	✅	Actual changes introduce Zod schemas at proxy boundaries, remove unsafe casts, add behavioral tests, and preserve existing protocol behavior, matching the linked issue acceptance criteria.
Out of Scope	—	Testing matrix shows mostly unknown results for Windows/Linux and non-npm runtimes; the local smoke test hit an external subscription limitation rather than a code issue.

---

Walkthrough generated by LLxprt PR Review. Planner issue: #2256

[github-actions]

OpenCodeReview — automatic reviews suspended

Automatic OCR reviews are suspended for this PR after 2 of 2 automatic reviews.

To get more reviews you can:

• Check the box below to re-enable automatic reviews (resets the counter), or

• Comment /review, /ocr, or /open-code-review to request a single review on demand.

• Re-enable automatic reviews

---

OpenCodeReview — PR #3371

• Reviewed head SHA: 21947e5479d2ff49146ced85cbf7f77d64d6b973
• Merge base: ece3d796efbd71de65269411202d6615df9a2849
• Range: full from ece3d796efbd71de65269411202d6615df9a2849
• Range fallback: checkpoint-missing
• Scope: selected 20 file(s), +1570/-166; cumulative 20 file(s), +1570/-166
• Tokens: 2296361 total (1996705 input, 299656 output, 1445376 cache)
• OCR version: open-code-review v1.8.4 (e78474478) linux/amd64 built at: 2026-08-01T03:27:37Z https://github.com/alibaba/open-code-review
• Phase: review
• Exit code: 0
• Run: https://github.com/vybestack/llxprt-code/actions/runs/33037903944
• 7 finding(s) (5 posted inline).
• Artifacts: ocr-review-output contains raw JSON, stdout, stderr, preview, phase, and exit-code diagnostics.

Inline overflow (exceeds inline comment cap)

• packages/providers/src/auth/proxy/credential-proxy-server.ts: [maintainability/medium] > Inconsistent return statements on sendOk calls. Most handlers now return this.sendOk(...) to propagate the result and prevent fall-through, but handleListProviders (line 850) and handleListApiKeys (line 928) still call this.sendOk(...) without returning. This violates the pattern established in the same diff and risks executing subsequent code if these handlers are extended in the future.

Findings without a resolvable position

• packages/auth/src/proxy/proxy-payload-schemas.ts: [bug/medium] > In handlePoll, the session is marked as used before pollFn actually succeeds. That means a failed poll or thrown error consumes the device-code session, and later retries will be rejected by getPollableSession as already used. Move session.used = true to after the provider poll succeeds.
• WARNING: Changed-file coverage 5/19 preview files covered is below the 90% threshold.

[acoliver]

Review feedback classification

I recorded every OCR and CodeRabbit item in the plan ledger.

• In-scope-Fix: The second host refresh-token preservation test duplicated an existing stronger case. Commit 21947e547 removes the duplicate. The remaining test verifies the new access token is stored, the host refresh token remains, and the caller refresh token is rejected.
• Reject: sendRefreshResult receives only the SanitizedOAuthToken success variant from RefreshCoordinator. The coordinator parses the provider result, merges it host-side, then validates the sanitized output with SanitizedOAuthTokenSchema. Existing refresh tests prove the returned token omits refresh_token. Sanitizing again at socket serialization would duplicate the boundary parse.
• Reject: The two identical INVALID_REQUEST reports conflict with the issue's error-message compatibility requirement. Wrong-typed fields are rejected before store access while the existing operation-specific text remains unchanged.
• Reject: Scalar bucket-stats data violates the response envelope, so the required result is Malformed response for request <id> plus connection reset. PROXY_PAYLOAD_ERROR applies when a valid envelope contains malformed operation data.
• Reject: The docstring metric is not a repository requirement, and adding comments solely for that external threshold conflicts with the repository's comment guidance.
• Reject: credential-store-factory.ts was audited and is byte-identical to origin/main; it contains no applicable untrusted proxy-payload cast.
• Reject: OCR preview coverage and its file-read failure are tool execution metadata, not code findings. The OCR workflow passed, and CodeRabbit reviewed all eligible files with no actionable comments.

Follow-up verification passed: 45 focused server tests, npm run format:check, git diff --check, and a 2,722-file test-audit scan with zero scanner errors. The normalized 2,015 findings remain identical to the saved origin/main baseline.

[acoliver]

Second OCR feedback classification

Commit 27f0955d2 records every item from the OCR review of 21947e547 in the plan ledger.

• Reject: handleSaveToken must not hide corrupted stored credentials. TokenStore.getToken returns OAuthToken | null, so undefined violates its interface. Falling back after a parse failure would silently discard the host refresh token and weaken the storage boundary.
• Reject: The exact malformed-handshake and malformed-correlated-response strings are accepted compatibility requirements. Their tests intentionally enforce those messages and the correlated-frame reset behavior.
• Reject: The field-specific INVALID_REQUEST proposal repeats earlier findings. Wrong-typed fields are rejected before store access while existing operation-level error text remains unchanged.
• Reject: OAuthExchangeRequestSchema does not regress the missing-code message. The handler inspects Zod issue paths, returns Missing code when a valid session ID accompanies a missing or invalid code, and returns Missing session_id when that field is invalid. Existing socket tests cover missing code.
• Reject: A malformed provider refresh result cannot become input to another refresh attempt. Parsing occurs before persistence and cooldown mutation, and the established non-auth retry path reuses the last stored token. Updating it from untrusted provider data would bypass the boundary being added here.
• Reject: The final sendOk calls in handleListProviders and handleListApiKeys are terminal statements, and sendOk returns void. Adding return would not change control flow.
• Reject: handlePoll assigns session.used only after pollForToken resolves. Its placement before local parse and persistence matches origin/main and prevents reuse of a one-shot provider result after later local processing fails.
• Reject: The changed-file preview coverage warning repeats review-tool execution metadata. It is not a code finding.

No production or test change was warranted. The branch remains clean and conflict-free against current origin/main; git merge-tree --write-tree origin/main HEAD succeeded after the ledger commit.