fix(claude): authenticate gateway model cache refresh

[Ingwannu]

Summary

• authenticate the Claude gateway-model cache refresh when the proxy uses a non-loopback bind
• send only the dedicated x-opencodex-api-key admission header
• prefer OPENCODEX_API_AUTH_TOKEN, then fall back to the first usable configured API key
• pass already-loaded config through both Claude launch and macOS system-environment paths

Scope

The default loopback listener remains unchanged and still works without a token. This fixes the 401/stale cache path only for configurations whose data plane requires admission.

Validation

• bun test tests/claude-gateway-cache.test.ts (5 passed)
• bun run typecheck
• bun run privacy:scan
• git diff --check

Fixes #1713

Summary by CodeRabbit

• Bug Fixes

  • Improved gateway model cache refresh reliability across configured environments.
  • Ensured model discovery uses the appropriate admission key, including environment credentials, service-token files, and configured-key fallback.
  • Added support for custom cache locations and refresh timeouts.
  • Improved compatibility by sending admission credentials through the expected request header.

• Tests

  • Expanded coverage for credential precedence, custom settings, environment overrides, and request authentication behavior.

[github-actions]

✅ Deterministic PR hygiene checks passed.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: a1f479c2-d838-4ea0-8d6a-1d23c99ffc50

📥 Commits

Reviewing files that changed from the base of the PR and between cded875 and a9024c9.

📒 Files selected for processing (2)

• src/claude/gateway-cache.ts
• tests/claude-gateway-cache.test.ts

---

📝 Walkthrough

Walkthrough

The gateway model cache refresh now accepts an options object, authenticates /v1/models requests with an admission key, supports configurable timeout and cache directory values, and receives configuration from Claude command paths. Tests cover environment-token, service-token-file, and configured-key authentication.

Changes

Gateway cache authentication

Layer / File(s)	Summary
Refresh options and authenticated request src/claude/gateway-cache.ts	Adds GatewayModelCacheRefreshOptions. The refresh request resolves a token from environment variables, service-token files, or configured API keys, sends x-opencodex-api-key, and uses configurable timeout and cache directory values.
Configuration wiring and validation src/cli/claude.ts, src/server/system-env.ts, tests/claude-gateway-cache.test.ts	Claude refresh call sites pass admission configuration. Tests verify trimmed environment tokens, configured-key fallback, service-token-file precedence, and omission of the authorization header.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• lidge-jun/opencodex#496: Both changes modify API admission authentication headers.
• lidge-jun/opencodex#1360: Both changes modify Claude proxy admission handling.

Suggested labels: review-ready

Suggested reviewers: wibias, lidge-jun

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the main change: authenticating Claude gateway model cache refresh requests.
Linked Issues check	✅ Passed	The changes address #1713 by adding the admission key, preserving fallback behavior, and passing configuration through all refresh paths.
Out of Scope Changes check	✅ Passed	All production and test changes support gateway cache authentication and the linked issue objectives; no unrelated scope is evident.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch ingw/fix-claude-gateway-cache-auth-1713

---

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.}