Skip to content

Commit 870f477

Browse files
committed
docs(providers): state the non-secret contract for custom headers
#1033 review blocker. The validator already rejects standard credential header names and points at apiKey/authMode, but nothing said so where a user would read it, and a code comment claimed header values 'may contain tokens' — which reads as sanction for exactly the use the validator refuses. Documents the contract in all five locales: --headers is non-secret request metadata; an arbitrary name like X-My-Token cannot be recognized by the validator, so the boundary is the user's to respect; and names the two concrete exposures (the JSON is argv, so it reaches shell history and the process list before any redaction runs, and header values persist in config.json in cleartext unlike API keys). The comment is corrected to say the entry is defensive rather than a supported credential channel.
1 parent 2640c44 commit 870f477

6 files changed

Lines changed: 90 additions & 2 deletions

File tree

‎docs-site/src/content/docs/ja/reference/cli/providers-accounts.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,23 @@ ocx models --provider anthropic --json
3535
ocx models live --provider ark --json
3636
```
3737

38+
:::caution[カスタムヘッダーは認証情報の経路ではありません]
39+
`--headers` は秘密ではないリクエストメタデータ用です — ルーティングヒント、テナントや
40+
プロジェクトのセレクター、トレース ID など。認証情報を入れる場所ではなく、バリデーターは
41+
標準的な認証ヘッダー名(`Authorization`、`X-Api-Key`、`Cookie` など)を
42+
`apiKey` / `authMode` を使うよう案内して拒否します。
43+
44+
ただし `X-My-Token` のような任意の名前までは判別できないため、その境界は利用者が守る
45+
必要があります。理由は 2 つです。
46+
47+
- JSON はコマンドライン引数なので、秘密を入れるとシェル履歴とプロセス一覧に残ります。
48+
CLI が何かを伏せるより先に、同じマシンの別プロセスが読み取れます。
49+
- ヘッダー値は `config.json` に平文で保存されます。専用の保存・マスキング経路を持つ
50+
API キーとは異なります。
51+
52+
秘密にあたる値は `--api-key` か OAuth ログインを使ってください。
53+
:::
54+
3855
## 認証
3956

4057
### `ocx login <provider>`

‎docs-site/src/content/docs/ko/reference/cli/providers-accounts.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,23 @@ ocx models --provider anthropic --json
3535
ocx models live --provider ark --json
3636
```
3737

38+
:::caution[커스텀 헤더는 자격증명 통로가 아닙니다]
39+
`--headers`는 비밀이 아닌 요청 메타데이터용입니다 — 라우팅 힌트, 테넌트나 프로젝트
40+
선택자, 추적 id 같은 것들이요. 인증 정보를 넣는 자리가 아니고, 검증기는 표준 자격증명
41+
헤더 이름(`Authorization`, `X-Api-Key`, `Cookie` 등)을 `apiKey` / `authMode`를
42+
쓰라는 안내와 함께 거부합니다.
43+
44+
다만 `X-My-Token` 같은 임의 이름까지 알아볼 수는 없으니 그 경계는 사용자가 지켜야
45+
합니다. 이유는 두 가지입니다.
46+
47+
- JSON이 명령줄 인자라서, 비밀이 들어가면 셸 히스토리와 프로세스 목록에 남습니다.
48+
CLI가 무엇을 가리기도 전에 같은 머신의 다른 프로세스가 읽을 수 있습니다.
49+
- 헤더 값은 `config.json`에 평문으로 저장됩니다. 별도 저장·마스킹 경로가 있는
50+
API 키와 다릅니다.
51+
52+
비밀에 해당하는 값은 `--api-key`나 OAuth 로그인을 쓰세요.
53+
:::
54+
3855
## 인증
3956

4057
### `ocx login <provider>`

‎docs-site/src/content/docs/reference/cli/providers-accounts.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,25 @@ ocx models --provider anthropic --json
3636
ocx models live --provider ark --json
3737
```
3838

39+
:::caution[Custom headers are not a credential channel]
40+
`--headers` is for non-secret request metadata — routing hints, tenant or
41+
project selectors, tracing ids. It is **not** a place to put authentication
42+
material, and the validator rejects the standard credential header names
43+
(`Authorization`, `X-Api-Key`, `Cookie`, and the rest) with a pointer to
44+
`apiKey` / `authMode`.
45+
46+
The validator cannot recognize an arbitrary name such as `X-My-Token`, so the
47+
boundary is yours to respect. Two reasons it matters:
48+
49+
- The JSON is a command-line argument, so a secret in it lands in shell history
50+
and in the process list, where any other process on the machine can read it
51+
before the CLI ever redacts anything.
52+
- Header values are persisted in `config.json` in cleartext, unlike API keys,
53+
which have their own storage and masking path.
54+
55+
Use `--api-key` or an OAuth login for anything secret.
56+
:::
57+
3958
## Authentication
4059

4160
### `ocx login <provider>`

‎docs-site/src/content/docs/ru/reference/cli/providers-accounts.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,25 @@ ocx models --provider anthropic --json
3737
ocx models live --provider ark --json
3838
```
3939

40+
:::caution[Пользовательские заголовки — не канал для учётных данных]
41+
`--headers` предназначен для несекретных метаданных запроса — подсказок
42+
маршрутизации, селекторов тенанта или проекта, идентификаторов трассировки. Это не
43+
место для аутентификационных данных: валидатор отклоняет стандартные имена
44+
заголовков с учётными данными (`Authorization`, `X-Api-Key`, `Cookie` и другие),
45+
указывая на `apiKey` / `authMode`.
46+
47+
Произвольное имя вроде `X-My-Token` валидатор распознать не может, поэтому границу
48+
соблюдает пользователь. Две причины, почему это важно:
49+
50+
- JSON передаётся как аргумент командной строки, поэтому секрет попадает в историю
51+
оболочки и в список процессов, где его прочитает любой другой процесс на машине —
52+
ещё до того, как CLI что-либо скроет.
53+
- Значения заголовков сохраняются в `config.json` открытым текстом, в отличие от
54+
API-ключей с их собственным путём хранения и маскирования.
55+
56+
Для всего секретного используйте `--api-key` или вход через OAuth.
57+
:::
58+
4059
## Аутентификация
4160

4261
### `ocx login <provider>`

‎docs-site/src/content/docs/zh-cn/reference/cli/providers-accounts.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,20 @@ ocx models --provider anthropic --json
3636
ocx models live --provider ark --json
3737
```
3838

39+
:::caution[自定义请求头不是凭据通道]
40+
`--headers` 用于非机密的请求元数据 —— 路由提示、租户或项目选择器、追踪 ID 等。它不是
41+
存放认证信息的地方,校验器会拒绝标准凭据请求头名称(`Authorization`、`X-Api-Key`、
42+
`Cookie` 等),并提示改用 `apiKey` / `authMode`。
43+
44+
但校验器无法识别 `X-My-Token` 这类任意名称,因此这条边界需要你自己遵守。原因有两点:
45+
46+
- 该 JSON 是命令行参数,机密会留在 shell 历史和进程列表中;在 CLI 做任何脱敏之前,
47+
同一台机器上的其他进程就能读到。
48+
- 请求头的值以明文保存在 `config.json` 中,这与拥有独立存储和脱敏路径的 API 密钥不同。
49+
50+
任何机密内容请使用 `--api-key` 或 OAuth 登录。
51+
:::
52+
3953
## 认证
4054

4155
### `ocx login <provider>`

‎src/cli/runtime-api.ts‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -128,8 +128,10 @@ export function csv(value: string | undefined): string[] | undefined {
128128

129129
/**
130130
* Options whose VALUE is a credential (or can carry one), listed here so a parse
131-
* error never prints one. `--headers` belongs on the list because custom header
132-
* values may contain tokens or account identifiers.
131+
* error never prints one. `--headers` belongs on the list defensively: custom
132+
* headers are documented as non-secret metadata and the validator rejects the
133+
* standard credential names, but it cannot recognize an arbitrary one such as
134+
* `X-My-Token`, so a parse error must not echo the value back either way.
133135
*
134136
* `takeOption` only understands `--flag value`. `--flag=value` therefore falls
135137
* through to `rejectArgs`, which reports the offending argument verbatim — for

0 commit comments

Comments
 (0)