Skip to content

Commit d560ac6

Browse files
committed
merge dev into main for the v2.33.0 release
# Conflicts: # package.json
2 parents 71c57ea + e1fb675 commit d560ac6

130 files changed

Lines changed: 5181 additions & 314 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# 000 — OAuth login UX: baseline, pain points, and work-phase map
2+
3+
Unit opened 2026-08-25. Session `01a036cb-4f1c-7b81-8c8d-277f92c914a7`.
4+
Goalplan slug `fix-oauth-login-remote-headless-ux-in-opencodex`.
5+
6+
## Baseline
7+
8+
| Ref | SHA |
9+
|-----|-----|
10+
| `origin/dev` | `bb89eafbe` |
11+
| `origin/main` | `71c57ea64` |
12+
13+
## The pain points, as reported
14+
15+
These are the operator's own words, recorded before any code was read. Every
16+
work-phase in this unit traces back to one of them.
17+
18+
> 지금 oauth 로그인 + 원격 지원이 너무 불편하다
19+
>
20+
> 1. 이미 프로바이더가 추가된 상태에서는 링크를 복사할 수 있지만 → 첫 추가 때 못함
21+
> → 링크 복사 못함, 크롬 다른 프로필 못함
22+
> 2. 프로바이더 추가도 링크는 보이지만 device 로그인을 하기가 좀 불편함. GUI에서
23+
> 코드 붙여넣기가 있는 그록이나 claude 쪽도 약간 불편함
24+
25+
In English, for the issue tracker:
26+
27+
1. **The first add is the worst experience.** Once a provider exists, its
28+
workspace panel shows the authorization URL with a copy button. During the
29+
very first login — the one where the operator has no other way in — that
30+
affordance is not there. No copyable link means no way to open the URL in a
31+
*different* Chrome profile, and no way to finish the login from another
32+
machine.
33+
2. **Device login is awkward in the GUI**, and the paste-a-code providers
34+
(xAI Grok, Anthropic Claude) are awkward too.
35+
36+
## What the code says
37+
38+
The report is accurate, and the cause is a split that nobody planned. Two
39+
login surfaces exist and each one has exactly the half the other is missing.
40+
41+
| Affordance | Workspace panel (existing provider) | Add-provider modal (first add) |
42+
|------------|-------------------------------------|--------------------------------|
43+
| Authorization URL + copy | yes | **no** |
44+
| Device / user code + copy | yes | **no** |
45+
| Paste redirect URL or code | **no** | yes |
46+
| Cancel | yes | no |
47+
48+
- `gui/src/components/provider-workspace/ProviderAuthPanel.tsx` renders the
49+
URL and the device code, and has no paste input anywhere in its 568 lines.
50+
- `gui/src/components/add-provider-oauth-pane.tsx` renders the paste input,
51+
and its `LoginUrlBlock` is fed by a hook that never reads `deviceCode`.
52+
- `gui/src/components/use-add-provider-oauth.ts` parses the login response as
53+
`{ url, instructions, error }`. The server returns `deviceCode` as well
54+
(`src/server/management/oauth-account-routes.ts`); the modal discards it.
55+
- The Accounts tab of the add-provider modal
56+
(`gui/src/components/provider-catalog/ProviderCatalog.tsx`) starts a login
57+
through `Providers.tsx`, which stores the hint in `loginInfo` — read only
58+
by `ProviderAuthPanel`. During a first add the modal is on screen and the
59+
panel is not, so the hint is computed, stored, and never displayed.
60+
61+
That is the whole of pain point 1: not a missing feature, a hint with no
62+
renderer.
63+
64+
## The remote half
65+
66+
`POST /api/oauth/login` calls `openUrl(authUrl)` unconditionally whenever a
67+
browser flow returns a URL. `src/lib/open-url.ts` shells out to `open` /
68+
`xdg-open` / `rundll32`, which means the **OS default browser profile** —
69+
the operator cannot send it to a second Chrome profile, and on a headless or
70+
SSH host the spawn is simply lost. There is no opt-out today: not a request
71+
field, not a config key, not an environment variable.
72+
73+
## Work-phase map
74+
75+
| Phase | Doc | Deliverable |
76+
|-------|-----|-------------|
77+
| WP1 | this unit | Docs-only roadmap at diff-level precision |
78+
| WP2 | `010` | One login-hint component: URL + device code + paste, on all three surfaces |
79+
| WP3 | `020` | First-add parity: the hint renders inside the add-provider modal |
80+
| WP4 | `030` | Operator control over server-side browser auto-open |
81+
| WP5 | `040` | Paste normalization and survivable failures |
82+
83+
One work-phase is one full PABCD cycle, one decade doc, one issue, one PR
84+
against `dev`.
85+
86+
## Scope boundary
87+
88+
Out of scope, stated once:
89+
90+
- Token storage format, credential refresh, and the account store schema.
91+
- New providers or adapters, account-pool routing, quota surfaces.
92+
- `src/lab/` — the core-lab boundary test exists for a reason.
93+
- Publishing, releasing, or merging anything.
94+
95+
## Security invariants this unit must not break
96+
97+
These are already load-bearing in the code and a UX change is not permitted to
98+
soften them:
99+
100+
- `src/oauth/github-copilot.ts` constructs its verification URL locally and
101+
refuses a non-allowlisted one; a server-supplied `verification_uri_complete`
102+
is never handed to `openUrl`.
103+
- `src/oauth/callback-server.ts` enforces state on `url`/`query`-shaped
104+
pastes and exempts only a syntactically raw in-session code.
105+
- `src/oauth/index.ts` bounds a pasted payload at 4 KiB and validates it
106+
synchronously before it reaches the flow.
107+
- No token, authorization code, or request body may be logged.
108+
109+
## Evidence rule
110+
111+
A remembered pass is not evidence. Every completion claim carries exact command
112+
output, the issue and PR numbers, the head SHA, and the CI conclusion on it.
Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
# 001 — Current-state inventory of every login surface
2+
3+
Read at `bb89eafbe`. Every claim below is a file:line read, not a memory.
4+
5+
## Three surfaces, three renderers
6+
7+
There are three places a human can start an OAuth login in the GUI, and they
8+
do not share a renderer.
9+
10+
### A. Workspace auth panel — an already-added provider
11+
12+
`gui/src/components/provider-workspace/ProviderAuthPanel.tsx`
13+
14+
- `:242` picks the hint for this row: `loginHint?.provider === item.name`.
15+
- `:392-401` renders the device code with a copy button.
16+
- `:402` renders `<LoginUrlBlock url={hintForThis.url ?? ""} />`.
17+
- `:403-408` renders Cancel.
18+
- A search for `paste`, `manual`, or `submitManual` across all 568 lines
19+
returns nothing. **This surface cannot accept a pasted code.**
20+
21+
### B. Add-provider modal, OAuth pane — a first add via a catalog preset
22+
23+
`gui/src/components/add-provider-oauth-pane.tsx`
24+
25+
- `:59` renders `<LoginUrlBlock url={oauthUrl} />`.
26+
- `:60-99` renders the paste input and submit button.
27+
- No device code is rendered anywhere. The prop does not exist.
28+
- When a device flow returns no `url`, `LoginUrlBlock` returns `null`
29+
(`login-url-block.tsx:16`), so the pane shows a spinner label and an empty
30+
paste box with nothing to act on.
31+
32+
The hook behind it, `gui/src/components/use-add-provider-oauth.ts:53`:
33+
34+
```ts
35+
const data = await res.json() as { url?: string; instructions?: string; error?: string };
36+
```
37+
38+
`deviceCode` is not in the type and is never read, although
39+
`src/server/management/oauth-account-routes.ts:176` returns it:
40+
41+
```ts
42+
return jsonResponse({ url: authUrl, instructions, deviceCode });
43+
```
44+
45+
### C. Add-provider modal, Accounts tab — a first add via an account row
46+
47+
`gui/src/components/provider-catalog/ProviderCatalog.tsx:148-212`
48+
49+
The account rows call `onLogin(row.id)`, which is `Providers.tsx`'s
50+
`requestLoginOAuth`. That path stores the hint:
51+
52+
- `gui/src/pages/use-providers-oauth.ts:93-96` reads `url`,
53+
`instructions` **and** `deviceCode`, then calls `setLoginInfo`.
54+
- `gui/src/pages/Providers.tsx:365` passes `loginInfo` to
55+
`ProviderDetails` → `ProviderAuthPanel`.
56+
57+
`ProviderAuthPanel` is the workspace surface for an **existing** provider.
58+
During a first add the modal is open and no panel is mounted for that
59+
provider, so the hint has no renderer. The row renders
60+
`t("prov.waitingBrowser")` and a Cancel button, and that is all the operator
61+
gets: no URL, no code, no paste box.
62+
63+
**This is pain point 1 exactly.** The data arrives; nothing draws it.
64+
65+
### D. Codex account modal — a fourth, near-duplicate surface
66+
67+
`gui/src/components/add-codex-account-waiting-step.tsx:38-69` renders
68+
`LoginUrlBlock` plus its own paste input against
69+
`/api/codex-auth/login/code`. `src/codex/auth-api.ts:2077` returns only
70+
`{ flowId, url, instructions }` — no device code on this path either.
71+
72+
## What each provider actually returns
73+
74+
`startLoginFlow` (`src/oauth/index.ts:1420-1504`) resolves
75+
`{ url, instructions?, deviceCode? }` from the provider's `onAuth` call.
76+
77+
| Provider | Shape | Produced at |
78+
|----------|-------|-------------|
79+
| xAI, Anthropic, ChatGPT, Cursor, Antigravity, Kiro | browser redirect + loopback callback | `OAuthCallbackFlow.login()`, `callback-server.ts:116` |
80+
| Kimi | device flow | `kimi.ts:212` — `instructions: "Enter code: …"`, **no `deviceCode` field** |
81+
| Nous | device flow | `nous.ts:660-663` — sets `deviceCode: device.userCode` |
82+
| GitHub Copilot | device flow | `github-copilot.ts:393-402` — locally constructed verify URL, `deviceCode: device.userCode` |
83+
| local-token import | no browser | `index.ts:1473` resolves `{ url: "" }` with an explanatory string |
84+
85+
Two observations that matter for WP2:
86+
87+
1. Kimi puts the user code inside a free-text `instructions` string instead of
88+
the structured `deviceCode` field, so no surface can render it as a code.
89+
2. `github-copilot.ts:170` refuses to trust `verification_uri_complete` and
90+
builds the URL itself. That invariant is not negotiable in WP4.
91+
92+
## The manual-paste path, end to end
93+
94+
1. `POST /api/oauth/login/code` — `oauth-account-routes.ts:202-213`.
95+
Caps input at 4096 chars, calls `submitManualLoginCode`, returns 409 on
96+
failure.
97+
2. `submitManualLoginCode` — `index.ts:1329-1360`. Rejects empty, rejects
98+
>4 KiB, rejects when no login is in progress, then `parseCallbackInput`.
99+
Rejects when no `code` is found; for `url`/`query` shapes enforces
100+
state once the flow has registered `expectedState`.
101+
3. `parseCallbackInput` — `callback-server.ts:273-300`. Three shapes:
102+
a parseable URL, a string containing `code=`, or a raw code with optional
103+
`#state`.
104+
4. `OAuthCallbackFlow.#waitForCallback` — `callback-server.ts:238-261`
105+
re-parses and loops on a bad paste.
106+
107+
The flow **does** survive a rejected paste — the loop re-prompts. What it does
108+
not do is tell the operator anything useful: the GUI shows
109+
`t("prov.pasteFail", { error })`, and only surface B has a paste box at all.
110+
111+
Accepted today: `https://…/callback?code=X&state=Y`, `?code=X&state=Y`,
112+
`code=X&state=Y`, `X`, `X#Y`. Whitespace is trimmed at three separate
113+
layers. A URL missing `state` is rejected with a specific message.
114+
115+
## Server-side browser opening
116+
117+
`oauth-account-routes.ts:170-175`:
118+
119+
```ts
120+
if (authUrl && !deviceCode) {
121+
const { openUrl } = await import("../../lib/open-url");
122+
openUrl(authUrl);
123+
}
124+
```
125+
126+
Unconditional for browser flows. `src/codex/auth-api.ts:1844` does the same
127+
on the Codex path. `src/lib/open-url.ts:11-24` spawns the platform opener,
128+
which resolves the **default** browser and therefore the default profile. It
129+
swallows spawn errors deliberately (a headless host emits ENOENT
130+
asynchronously), so a failed open is indistinguishable from a successful one
131+
from the GUI's perspective.
132+
133+
There is no opt-out: no request field, no config key, no environment variable.
134+
Grepping `openUrl` finds callers in `login-cli.ts:85`, `dispatch.ts:305`,
135+
`auth-api.ts:1844`, and `oauth-account-routes.ts:173`; none is conditional.
136+
137+
## Existing tests
138+
139+
`tests/oauth-manual-code.test.ts` covers the paste path;
140+
`tests/oauth-callback-server.test.ts` and `oauth-callback-binds.test.ts`
141+
cover parsing and binding; `tests/github-copilot-oauth.test.ts`,
142+
`nous-oauth.test.ts`, `kimi-oauth-identity.test.ts` cover device flows;
143+
`tests/oauth-public-surface.test.ts` and `oauth-status-privacy.test.ts`
144+
cover the management surface and its redaction.
145+
146+
Not covered anywhere: what the GUI *renders* during a login. Every gap in this
147+
unit lives in that hole.
Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# 002 — Plan audit: what ships, what does not, and how it splits
2+
3+
## The one-sentence diagnosis
4+
5+
Nothing here is missing infrastructure. The server already computes the
6+
authorization URL, the device code, and the manual-paste channel; four GUI
7+
surfaces each render a different subset of it, and one of them renders none of
8+
it at the exact moment the operator has no other option.
9+
10+
## Candidate list, and the cut
11+
12+
Eleven changes were on the table after reading the tree. Four ship in this
13+
unit. The rest are recorded here so a later cycle does not rediscover them.
14+
15+
### Shipping
16+
17+
| WP | Change | Why it is in |
18+
|----|--------|--------------|
19+
| WP2 | One login-hint component: URL + device code + paste on all surfaces | Directly answers pain point 2; every other GUI fix depends on it existing |
20+
| WP3 | The hint renders during a first add | Directly answers pain point 1 |
21+
| WP4 | Operator control over server-side auto-open | The "다른 Chrome 프로필" half of pain point 1, and the whole remote story |
22+
| WP5 | Paste normalization: hash-fragment redirects | A real paste that looks valid and is silently rejected today |
23+
24+
### Deferred, with reasons
25+
26+
- **Expiry countdown / poll interval in the GUI.** The polling math is already
27+
correct in each provider; showing it is additive UI over a DTO that does not
28+
carry `expiresAt` yet. Real, but not a pain point that was reported.
29+
- **Kimi allowlisting of `verification_uri_complete`.** Kimi and Nous pass the
30+
provider-supplied complete URI into `onAuth`. Copilot refuses to
31+
(`github-copilot.ts:393`). Tightening Kimi/Nous is a **security** change,
32+
not a UX change, and it does not belong in a PR whose title says "GUI". It
33+
gets its own issue.
34+
- **`openUrl` returning success/failure.** Attractive, but the spawn is
35+
detached and a browser that opens then fails is indistinguishable from one
36+
that never launched. A truthful signal needs more than an exit code.
37+
- **A browser/profile picker in the GUI.** WP4 gives the operator the
38+
*ability* to not have their default profile hijacked. A full picker is a
39+
product surface, and the operator asked for control, not a picker.
40+
- **`ocx login` re-prompt loop.** The CLI's one-shot readline is a smaller
41+
version of the same bug, on a surface nobody reported. Own issue.
42+
43+
## The default-preservation rule
44+
45+
WP4 is the only phase that can change what already happens, so it carries the
46+
strictest constraint in this unit: **auto-open stays the default.** An
47+
operator who upgrades and does nothing must see byte-identical behavior. The
48+
new capability is an explicit choice, never an inferred one.
49+
50+
That rules out the tempting version of this feature — sniffing
51+
`SSH_CONNECTION` or an absent `DISPLAY` and silently declining to open. A
52+
false positive there (X11 forwarding, WSLg, a desktop session that does not
53+
advertise itself) breaks a login that works today, and breaks it silently.
54+
Explicit opt-out first; inference is a separate decision with its own
55+
evidence.
56+
57+
## Security invariants, restated as gates
58+
59+
A PR in this unit fails review if it:
60+
61+
1. Hands a provider-supplied `verification_uri_complete` to `openUrl`.
62+
2. Weakens state enforcement on `url`/`query`-shaped pastes
63+
(`callback-server.ts:252`, `index.ts:1347-1350`).
64+
3. Accepts `access_token` from a URL fragment — hash parsing in WP5 reads
65+
`code` and `state` only, never a token.
66+
4. Raises the 4 KiB paste bound or the 4096-char route cap.
67+
5. Logs a URL, a code, a token, or a request body.
68+
6. Passes a shell string where an argv array is required.
69+
70+
## Dependency order and the PR stack
71+
72+
```
73+
WP2 (shared hint component)
74+
└── WP3 (first-add parity — renders the WP2 component)
75+
WP4 (auto-open control) ← independent
76+
WP5 (paste normalization) ← independent
77+
```
78+
79+
WP3 stacks on WP2 because it mounts the component WP2 creates. WP4 and WP5
80+
touch disjoint files and target `dev` directly.
81+
82+
| WP | Issue template | PR base | GUI screenshot |
83+
|----|----------------|---------|----------------|
84+
| WP2 | feature_request | `dev` | required |
85+
| WP3 | bug_report | WP2 head | required |
86+
| WP4 | feature_request | `dev` | required if GUI toggle lands |
87+
| WP5 | bug_report | `dev` | not required |
88+
89+
## Verdict
90+
91+
PASS. Four phases, dependency-ordered, each with a falsifiable test and a
92+
bounded diff. The audit's one binding instruction to later phases: WP4 must
93+
ship the explicit choice and must not ship inference.

0 commit comments

Comments
 (0)