Skip to content

fix(claude): isolate native passthrough credentials #1536

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lidge-jun merged 2 commits into from
Aug 12, 2026
Merged

fix(claude): isolate native passthrough credentials #1536

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9083f52
fix(claude): isolate native passthrough credentials
luvs01 Aug 12, 2026
884e7fe
fix(server): align Anthropic listener policy
luvs01 Aug 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 10 additions & 6 deletions docs-site/src/content/docs/guides/claude-code.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -156,12 +156,16 @@ caching and billing identity stay fully native, and routed models keep working i
via the picker aliases.

**Header handling:** hop-by-hop headers plus `host`, `content-length`, `accept-encoding`,
`x-opencodex-api-key`, and `origin` are stripped before forwarding. All other headers (including
`anthropic-beta` and `anthropic-version`) pass through.

The passthrough fires when **all four** conditions are met: `nativePassthrough` is not `false`;
the model begins with `claude` or `anthropic`; the bearer or `x-api-key` starts with `sk-ant-`;
and alias/model-map resolution returns the same model unchanged. This also means the
`x-opencodex-api-key`, and `origin` are always stripped before forwarding. On a non-loopback bind,
native passthrough also requires a valid proxy credential in `x-opencodex-api-key`; `Authorization`
and `x-api-key` then belong only to Anthropic. A proxy admission secret found in either provider
header is removed, while a genuine provider credential in the other header is preserved. Ambiguous
comma-joined credential headers are not forwarded.

The passthrough fires when all of these conditions are met: `nativePassthrough` is not `false`;
the model begins with `claude` or `anthropic`; the bearer token or `x-api-key` starts with `sk-ant-`;
alias/model-map resolution returns the same model unchanged; and, on a non-loopback bind, the
dedicated proxy admission header is valid. This also means the
"claude.ai connectors are disabled" warning no longer appears with `ocx claude`.

Disable with `claudeCode.nativePassthrough: false`; point elsewhere with
Expand Down
16 changes: 10 additions & 6 deletions docs-site/src/content/docs/ja/guides/claude-code.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,12 +50,16 @@ ocx claude
ネイティブ状態で維持され、同じセッションでピッカーエイリアスを使ってルーティングモデルも引き続き使えます。

**ヘッダー処理:** hop-by-hop ヘッダーと `host`、`content-length`、`accept-encoding`、
`x-opencodex-api-key`、`origin` は転送前に削除します。それ以外のヘッダー(`anthropic-beta`、
`anthropic-version` を含む)はそのまま転送します。

次の 4 つの条件を**すべて**満たすとパススルーが動作します。`nativePassthrough` が `false` でなく、
モデル名が `claude` または `anthropic` で始まり、bearer または `x-api-key` が `sk-ant-` で
始まり、エイリアス/モデルマップ解決結果が変更されていない同じモデルであること。そのため `ocx claude` を
`x-opencodex-api-key`、`origin` は常に転送前に削除します。非ループバック bind のネイティブ
パススルーでは、有効なプロキシ認証情報を `x-opencodex-api-key` でも要求し、
`Authorization` と `x-api-key` は Anthropic 専用になります。いずれかの provider ヘッダーに
プロキシ admission secret があれば削除し、もう一方の実際の provider 認証情報は維持します。
カンマで結合された曖昧な認証ヘッダーは転送しません。

次の条件を**すべて**満たすとパススルーが動作します。`nativePassthrough` が `false` でなく、
モデル名が `claude` または `anthropic` で始まり、bearer トークンまたは `x-api-key` が `sk-ant-` で
始まり、エイリアス/モデルマップ解決結果が変更されていない同じモデルであり、非ループバック bind
では専用プロキシ admission ヘッダーも有効であること。そのため `ocx claude` を
使うとき "claude.ai connectors are disabled" 警告ももう表示されません。

`claudeCode.nativePassthrough: false` でオフにでき、`claudeCode.anthropicBaseUrl` で別のアドレスを
Expand Down
8 changes: 7 additions & 1 deletion docs-site/src/content/docs/ja/reference/configuration/server.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,10 +50,16 @@ x-opencodex-api-key: your-secret-token
| `/v1/responses` |受け入れられません | **必須** |受け入れられません |
| `/v1/chat/completions` |受け入れられません | **必須** |受け入れられません |
| `/v1/messages` |受け入れられました |受け入れられました |受け入れられました |
| `/v1/messages/count_tokens` |受け入れられました |受け入れられました |受け入れられました |
| `/v1/models` |受け入れられました |受け入れられました |受け入れられました |

応答とチャット完了では、Codex Direct パススルーの可能性のために `Authorization` を予約しているため、そこでは専用のアドミッション ヘッダーのみが受け入れられます。ダッシュボードで生成された `apiKeys` は、起動後に環境トークンを置き換える可能性があります。候補は一定時間内に比較されます。

@coderabbitai coderabbitai Bot Aug 12, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔒 Security & Privacy | 🟡 Minor | ⚡ Quick win

Preserve the constant-time comparison guarantee.

Line 56 says 候補は一定時間内に比較されます. This describes a time window, not constant-time comparison. The English source states that candidate credentials are compared in constant time. Use Japanese wording such as 候補値は定数時間で比較されます.

Proposed wording 
-候補は一定時間内に比較されます。
+候補値は定数時間で比較されます。

Based on the English source in docs-site/src/content/docs/reference/configuration/server.md Lines 60-62, the intended property is constant-time comparison. As per path instructions: “Check that user-facing docs stay in sync with actual CLI/API behavior and that translated locale pages (ja, ko, ru, zh-cn) are not left contradicting the English source.”

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
応答とチャット完了では、Codex Direct パススルーの可能性のために `Authorization` を予約しているため、そこでは専用のアドミッション ヘッダーのみが受け入れられます。ダッシュボードで生成された `apiKeys` は、起動後に環境トークンを置き換える可能性があります。候補は一定時間内に比較されます。
応答とチャット完了では、Codex Direct パススルーの可能性のために `Authorization` を予約しているため、そこでは専用のアドミッション ヘッダーのみが受け入れられます。ダッシュボードで生成された `apiKeys` は、起動後に環境トークンを置き換える可能性があります。候補値は定数時間で比較されます。
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs-site/src/content/docs/ja/reference/configuration/server.md` at line 56,
Update the Japanese sentence in the configuration documentation so it states
that candidate values are compared in constant time, using wording equivalent
to「候補値は定数時間で比較されます」. Keep the surrounding explanation unchanged and align it
with the English source’s constant-time comparison guarantee.

Source: Path instructions


Messages と `count_tokens` はルーティングクライアントとの互換性のために 3 つの admission 形式を引き続き受け入れます。
ただし非ループバック bind のネイティブ Anthropic パススルーでは、プロキシ admission は
`x-opencodex-api-key` のみを使い、`Authorization` と `x-api-key` は Anthropic 認証情報用に
予約されます。これら provider ヘッダー内のプロキシ admission secret は転送前に削除されます。

:::caution[LAN露出]
`0.0.0.0` バインドは、プロキシと構成されたプロバイダーの LAN へのアクセスを公開します。強力なトークンを持つ信頼できるネットワークでのみ使用してください。
:::
Expand Down Expand Up @@ -84,7 +90,7 @@ ssh -L 20100:localhost:10100 -L 1455:localhost:1455 you@remote

## Claude Code (`claudeCode`)

これらの設定は、`/v1/messages`、`ocx claude` ランチャー、および Claude ダッシュボード ページを制御します。
これらの設定は、`/v1/messages`、`/v1/messages/count_tokens`、`ocx claude` ランチャー、および Claude ダッシュボード ページを制御します。

|キー |タイプ |デフォルト |説明 |
| --- | --- | --- | --- |
Expand Down
9 changes: 7 additions & 2 deletions docs-site/src/content/docs/ja/reference/proxy-formats.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -123,11 +123,16 @@ WebSocket が無効になっている場合、アップグレード試行では

- ネイティブ パススルーはクロード コード設定で無効になっていません。
- 要求されたモデルは `claude` または `anthropic` で始まります。
- リクエストにはネイティブ Anthropic Bearer または `x-api-key` 資格情報が含まれます。そして
- リクエストにはネイティブ Anthropic Bearer または `x-api-key` 資格情報が含まれます。
- 非ループバック listener では、有効なプロキシ admission を `x-opencodex-api-key` だけで送ります。そして
- 構成されたエイリアスまたはモデル マップが、ルーティングされたターゲットのモデル ID を主張しません。

適格なリクエストは Anthropic 方言で転送されるため、ネイティブ ベータ ヘッダー、思考署名、およびサブスクリプション ID がエンドツーエンドで残ります。それ以外の場合は、応答が往復してかかります。

専用 admission ヘッダーは転送されません。`Authorization` または `x-api-key` にあるプロキシ
admission secret も削除され、別の実際の Anthropic 認証情報は維持されます。カンマで結合された
曖昧な認証ヘッダーは fail closed します。

`POST /v1/messages/count_tokens` は、同じモデルの解像度とパススルーの決定に従います。ネイティブ適格なリクエストは、Anthropic のカウント エンドポイントに転送されます。他のリクエストは、システム コンテンツ、メッセージ、ツールに対してローカルに文書化された見積もりを使用し、次を返します。

```json
Expand Down Expand Up @@ -213,4 +218,4 @@ Anthropic オリジンの失敗は Anthropic のエラー エンベロープで

プロキシは、本物のバックエンド暗号文を不透明なものとして扱います。構造的に有効な暗号文はバイト単位で保存されます。opencodex は暗号文を復号したり、その内容を変換したり、別のプロバイダー用に再暗号化したりしません。

一部のエージェント フックはこれまで、プレーンテキストの制御テキストを `encrypted_content` スロットに配置していました。互換性を確保するために、プロキシは、構造的に有効な Fernet の実行を変更せずに保持しながら、プレーンテキストをテキスト部分に分割します。 `agent_message` が修復中にすべての暗号化された部分を失った場合、それは通常のユーザー メッセージになります。現在の v2 タスクが完全に暗号化されたままであるが、選択したルーティングされたターゲットがネイティブ ChatGPT 暗号文を読み取ることができない場合、opencodex は読み取り不能なバイトをそのプロバイダーに送信する代わりに `unreadable_encrypted_agent_task` で失敗します。ワーカー タスクに関するクライアントの動作については、[サブエージェントサーフェス](/guides/sub-agent-surface/) を参照してください。
一部のエージェント フックはこれまで、プレーンテキストの制御テキストを `encrypted_content` スロットに配置していました。互換性を確保するために、プロキシは、構造的に有効な Fernet の実行を変更せずに保持しながら、プレーンテキストをテキスト部分に分割します。 `agent_message` が修復中にすべての暗号化された部分を失った場合、それは通常のユーザー メッセージになります。現在の v2 タスクが完全に暗号化されたままであるが、選択したルーティングされたターゲットがネイティブ ChatGPT 暗号文を読み取ることができない場合、opencodex は読み取り不能なバイトをそのプロバイダーに送信する代わりに `unreadable_encrypted_agent_task` で失敗します。ワーカー タスクに関するクライアントの動作については、[サブエージェントサーフェス](/guides/sub-agent-surface/) を参照してください。
16 changes: 10 additions & 6 deletions docs-site/src/content/docs/ko/guides/claude-code.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,12 +75,16 @@ macOS의 자동 연결(`claudeCode.systemEnv`)도 같은 방식으로 판단하
네이티브 상태로 유지되고, 같은 세션에서 선택기 별칭을 써서 라우팅 모델도 계속 사용할 수 있어요.

**헤더 처리:** hop-by-hop 헤더와 `host`, `content-length`, `accept-encoding`,
`x-opencodex-api-key`, `origin`은 전달 전에 제거해요. 그 밖의 헤더(`anthropic-beta`,
`anthropic-version` 포함)는 그대로 전달해요.

다음 네 조건을 **모두** 충족하면 패스스루가 작동해요. `nativePassthrough`가 `false`가 아니고,
모델 이름이 `claude` 또는 `anthropic`으로 시작하며, bearer 또는 `x-api-key`가 `sk-ant-`로
시작하고, 별칭/모델 맵 해석 결과가 변경되지 않은 같은 모델이어야 해요. 그래서 `ocx claude`를
`x-opencodex-api-key`, `origin`은 항상 전달 전에 제거해요. 비루프백 바인드의 네이티브 패스스루는
유효한 프록시 자격 증명을 `x-opencodex-api-key`로도 요구하고, 이때 `Authorization`과
`x-api-key`는 Anthropic 전용이에요. 두 provider 헤더 중 프록시 admission secret이 있으면
제거하고, 다른 헤더의 실제 provider 자격 증명은 유지해요. 쉼표로 결합된 모호한 자격 증명
헤더는 전달하지 않아요.

다음 조건을 **모두** 충족하면 패스스루가 작동해요. `nativePassthrough`가 `false`가 아니고,
모델 이름이 `claude` 또는 `anthropic`으로 시작하며, bearer 토큰 또는 `x-api-key`가 `sk-ant-`로
시작하고, 별칭/모델 맵 해석 결과가 변경되지 않은 같은 모델이며, 비루프백 바인드에서는 전용
Comment thread
luvs01 marked this conversation as resolved.
프록시 admission 헤더도 유효해야 해요. 그래서 `ocx claude`를
사용할 때 "claude.ai connectors are disabled" 경고도 더 이상 나타나지 않아요.

`claudeCode.nativePassthrough: false`로 끌 수 있고, `claudeCode.anthropicBaseUrl`로 다른 주소를
Expand Down
8 changes: 7 additions & 1 deletion docs-site/src/content/docs/ko/reference/configuration/server.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,10 +50,16 @@ x-opencodex-api-key: your-secret-token
| `/v1/responses` | 허용되지 않음 | **필수** | 허용되지 않음 |
| `/v1/chat/completions` | 허용되지 않음 | **필수** | 허용되지 않음 |
| `/v1/messages` | 허용됨 | 허용됨 | 허용됨 |
| `/v1/messages/count_tokens` | 허용됨 | 허용됨 | 허용됨 |
| `/v1/models` | 허용됨 | 허용됨 | 허용됨 |

Responses와 Chat Completions는 `Authorization`을 향후 Codex Direct 패스스루 용도로 예약해 두므로, 여기서는 전용 admission 헤더만 허용됩니다. 대시보드에서 생성한 `apiKeys`는 시작 후 환경 토큰을 대체할 수 있으며, 후보 값은 상수 시간으로 비교합니다.

Messages와 `count_tokens`는 라우팅 클라이언트 호환성을 위해 세 admission 형식을 계속 허용합니다. 하지만 비루프백
바인드의 네이티브 Anthropic 패스스루는 프록시 admission을 `x-opencodex-api-key`로만 받고,
`Authorization`과 `x-api-key`를 Anthropic 자격 증명용으로 예약합니다. 이 provider 헤더에 들어간
프록시 admission secret은 upstream 전달 전에 제거됩니다.

:::caution[LAN exposure]
`0.0.0.0` 바인드는 프록시와 설정된 provider 접근을 LAN에 노출합니다. 신뢰할 수 있는 네트워크에서 강한 토큰과 함께만 사용합니다.
:::
Expand Down Expand Up @@ -84,7 +90,7 @@ ssh -L 20100:localhost:10100 -L 1455:localhost:1455 you@remote

## Claude Code (`claudeCode`)

이 설정은 `/v1/messages`, `ocx claude` 실행기, 그리고 Claude 대시보드 페이지를 제어합니다.
이 설정은 `/v1/messages`, `/v1/messages/count_tokens`, `ocx claude` 실행기, 그리고 Claude 대시보드 페이지를 제어합니다.

| 키 | 형식 | 기본값 | 설명 |
| --- | --- | --- | --- |
Expand Down
7 changes: 6 additions & 1 deletion docs-site/src/content/docs/ko/reference/proxy-formats.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -153,11 +153,16 @@ Responses로 변환되어 일반적으로 라우팅된 뒤, Anthropic JSON 또
- Claude Code 설정에서 native passthrough가 비활성화되어 있지 않습니다.
- 요청한 모델이 `claude` 또는 `anthropic`으로 시작합니다.
- 요청에 네이티브 Anthropic bearer 또는 `x-api-key` 자격 증명이 들어 있습니다.
- 비루프백 listener에서는 `x-opencodex-api-key`에만 유효한 프록시 admission이 들어 있습니다.
- 설정된 alias 또는 model map이 해당 model id를 라우팅 대상으로 점유하고 있지 않습니다.

적합한 요청은 Anthropic 방언으로 전달되므로 네이티브 beta 헤더, thinking 서명, 구독 식별 정보가 끝까지
유지됩니다. 그렇지 않으면 Responses 왕복을 탑니다.

전용 admission 헤더는 upstream으로 전달되지 않습니다. `Authorization` 또는 `x-api-key`에서
프록시 admission secret이 발견되어도 제거하며, 별도의 실제 Anthropic 자격 증명은 유지합니다.
쉼표로 결합된 모호한 자격 증명 헤더는 전달하지 않고 fail closed합니다.

`POST /v1/messages/count_tokens`도 같은 model resolution과 passthrough 판단을 따릅니다. 네이티브로 적합한
요청은 Anthropic의 count endpoint로 전달됩니다. 그 외 요청은 system content, messages, tools에 대한 로컬
문서화 추정치를 사용하고 다음을 반환합니다.
Expand Down Expand Up @@ -265,4 +270,4 @@ OpenAI 스타일 `origin_rejected` body가 아니라 403 `permission_error`입
작업이 실제로 암호화된 상태이고 선택된 라우팅 대상이 네이티브 ChatGPT 암호문을 읽을 수 없다면,
opencodex는 읽을 수 없는 바이트를 프로바이더에 보내는 대신 `unreadable_encrypted_agent_task`로
실패합니다. worker task와 관련된 클라이언트 동작은 [서브에이전트 표면](/guides/sub-agent-surface/)을
참조하세요.
참조하세요.
8 changes: 7 additions & 1 deletion docs-site/src/content/docs/reference/configuration/server.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,12 +54,18 @@ x-opencodex-api-key: your-secret-token
| `/v1/responses` | not accepted | **required** | not accepted |
| `/v1/chat/completions` | not accepted | **required** | not accepted |
| `/v1/messages` | accepted | accepted | accepted |
| `/v1/messages/count_tokens` | accepted | accepted | accepted |
| `/v1/models` | accepted | accepted | accepted |

Responses and Chat Completions reserve `Authorization` for possible Codex Direct passthrough, so only
the dedicated admission header is accepted there. Dashboard-generated `apiKeys` may replace the
environment token after startup; candidates are compared in constant time.

Messages and `count_tokens` keep accepting all three admission forms for routed-client compatibility. Native
Anthropic passthrough is stricter on a non-loopback bind: proxy admission must use
`x-opencodex-api-key`, while `Authorization` and `x-api-key` are reserved for Anthropic credentials.
Any proxy admission secret placed in those provider headers is removed before forwarding.

:::caution[LAN exposure]
A `0.0.0.0` bind exposes the proxy and configured provider access to the LAN. Use it only on trusted
networks with a strong token.
Expand Down Expand Up @@ -145,7 +151,7 @@ with `POST /api/storage/cleanup-policy/run`.

## Claude Code (`claudeCode`)

These settings govern `/v1/messages`, the `ocx claude` launcher, and the Claude dashboard page.
These settings govern `/v1/messages`, `/v1/messages/count_tokens`, the `ocx claude` launcher, and the Claude dashboard page.

| Key | Type | Default | Description |
| --- | --- | --- | --- |
Expand Down
8 changes: 7 additions & 1 deletion docs-site/src/content/docs/reference/proxy-formats.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -172,13 +172,19 @@ Native Anthropic passthrough is eligible only when all of these are true:

- native passthrough has not been disabled in Claude Code configuration;
- the requested model begins with `claude` or `anthropic`;
- the request carries a native Anthropic bearer or `x-api-key` credential; and
- the request carries a native Anthropic bearer or `x-api-key` credential;
- on a non-loopback listener, the request also carries valid proxy admission only in
`x-opencodex-api-key`; and
- no configured alias or model map claims that model id for a routed target.

An eligible request is forwarded in the Anthropic dialect so native beta headers, thinking
signatures, and subscription identity remain end to end. Otherwise it takes the Responses
round-trip.

The dedicated admission header is never forwarded. Proxy admission secrets found in
`Authorization` or `x-api-key` are also removed; a separate genuine Anthropic credential is
preserved. Ambiguous comma-joined credential headers fail closed instead of being forwarded.

`POST /v1/messages/count_tokens` follows the same model resolution and passthrough decision. A
native-eligible request is forwarded to Anthropic's count endpoint. Other requests use the local
documented estimate over system content, messages, and tools and return:
Expand Down
Loading
Loading