Skip to content

Commit 414a73e

Browse files
committed
docs(structure,devlog): record the scope boundary on the unrouted data planes
The three data-plane documents that own these handlers now say where a configured key's scope is applied and what each surface is judged against, so the ownership rule holds for the source areas this lane changed. The lane note records the shape of each endpoint's destination, including the one the brief had backwards: the search sidecar fallback ignores the caller's model and spends the backend the operator configured.
1 parent eff2a4b commit 414a73e

4 files changed

Lines changed: 110 additions & 0 deletions

File tree

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Lane I — per-key scope on the unrouted data planes
2+
3+
Status: OPEN. Branch `codex/260920-lane-i-key-scope-dataplane` against `dev`, one pull request,
4+
ordered commits. Base is `origin/dev` at `043aa435ff`.
5+
6+
Scope is one thing: the part of #5049 that #5265 (`447ac22ca6`) could not reach. That change put
7+
the model and provider scope on the resolved route, at the single capture point every Responses
8+
destination passes through, and Chat and Messages inherit it by translating into that path. Four
9+
authenticated endpoints spend provider quota without ever resolving a model through the router, so
10+
the predicate never saw them.
11+
12+
## What each surface turned out to be
13+
14+
### Images
15+
16+
`handleImages` can settle on four different destinations, and only two of them use the model the
17+
caller sent. The ChatGPT forward account and a keyed OpenAI provider relay the body verbatim; the
18+
xAI Imagine bridge always runs `images.bridgeModel` on the configured xAI provider; the Antigravity
19+
fallback always runs its own CCA image model. Judging the body would therefore have authorized one
20+
thing and billed another on two of the four branches, which is the failure the landed design names.
21+
22+
Each branch is checked as it is entered — the bridge and the Antigravity fallback before they
23+
resolve a credential, the two relays before the forward probe lease is consumed or the keyed picker
24+
commits a rotation. A refused request spends nothing and mutates nothing.
25+
26+
### Audio and voice
27+
28+
Transcription, the dictation socket, external voice call-create and the external sideband join all
29+
resolve through `resolveAudioUpstream`, which already receives both the admission and the model the
30+
upstream will run. One check on each of its two return paths covers all four endpoints. The forward
31+
path releases its probe lease on refusal, mirroring the adjacent unusable-account branch.
32+
33+
The native `/v1/live` and `/v1/realtime/calls` path does not share that resolver, so it needed its
34+
own: `resolveLiveRelay` now takes the destination it is resolving for. The model is read where the
35+
client states it — `session.model` in a JSON or multipart call-create, the `model` parameter of a
36+
standalone socket query — and a join onto an existing call carries the default, because the call it
37+
attaches to stated its model when it was created.
38+
39+
### Search
40+
41+
The brief expected the non-account-qualified branch to hand the caller's model to the sidecar. It
42+
does not, and the distinction matters for where the check belongs. There are two unrouted branches,
43+
not one:
44+
45+
- the forward relay copies the caller's model to whichever ChatGPT account the upstream resolved,
46+
and that account is billed for it;
47+
- the sidecar fallback ignores the caller's model entirely and runs the backend and model the
48+
operator configured, spending that backend's own credential.
49+
50+
Both are destinations a scoped key must not reach, so both are checked — the first against the
51+
resolved account and the caller's model, the second against the configured backend and the model
52+
that backend runs. Exa has no provider entry, so its backend name is its destination. The
53+
account-qualified branch keeps the single check #5265 gave it and is not judged twice.
54+
55+
## Rules that fell out of the review
56+
57+
A request that names no model has no destination a model list can allow: the relay would copy the
58+
body and let the upstream pick. `UNNAMED_DESTINATION_MODEL` makes that explicit, so a key scoped by
59+
model is refused rather than sent to a provider default. A key scoped only by provider is
60+
unaffected, and a key with no scope at all reaches every surface exactly as before.
61+
62+
No new policy system was introduced. `admissionScopeDenial` is a three-line composition of the
63+
landed `resolveAdmissionModelScope`, `routeAllowedByScope` and `admissionModelDeniedResponse`,
64+
shaped for handlers that return a `Response` rather than throwing into a route resolver. Every
65+
refusal is the same 403 naming the caller's own selector, with the resolved destination left to the
66+
server log.
67+
68+
## Explicitly out of scope
69+
70+
Redis, multi-tenancy, budgets and RPM/TPM ceilings. Nothing here reads or writes a credential, and
71+
no new field is logged: a refusal carries the selector the caller already knows and no account
72+
identifier, provider credential or request body.
73+
74+
## Verification
75+
76+
Static review against the `dev` source plus exact-head hosted CI. Per the lane instruction the
77+
local suite, focused test files, `typecheck`, `build`, `install` and any running `ocx` were NOT
78+
RUN; the file-size ratchet and the union-exhaustiveness classes were checked by reading the
79+
baseline and the changed files instead. No touched file carries a baseline cap, and the largest,
80+
`src/server/index/serve-options.ts`, stays well under the 2000-line threshold. The four new test
81+
files are registered in both `scripts/test-layout/layout.json` and
82+
`tests/fixtures/test-layout-expected.json`.
83+
84+
## Remaining scope on #5049
85+
86+
The issue stays open for the coordinator to judge. This lane closes the four endpoints named in the
87+
#5265 adversarial review and nothing beyond them.
88+

‎structure/data-planes/images.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,14 @@ The keyed path never enters `handleResponses`, so `src/server/images.ts` repeats
4747
`selectProactiveApiKeyTransport` inside the keyed branch and rebuilds Authorization from the
4848
returned clone rather than the earlier snapshot.
4949

50+
A configured key's model and provider scope applies to whichever destination the request settles
51+
on: the ChatGPT forward account, the keyed provider, the xAI Imagine bridge, or the Antigravity
52+
fallback. It is evaluated against that destination rather than the selector in the body, because
53+
the bridge and the fallback choose their own model, and a body that names no model cannot satisfy
54+
a model list. A refusal is the same 403 the scope returns on the routed path, and a key with no
55+
scope reaches every destination as before. Coverage lives in
56+
`tests/server/api-key-scope-images.test.ts`.
57+
5058
The API-key `openai-responses` path also adapts Codex's private standalone image tool to the public
5159
Responses tool surface. A complete `image_gen` namespace is lowered to safe
5260
`image_gen__<inner-name>` function aliases even when no hosted image tool is present, because public

‎structure/data-planes/inbound-compat.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,14 @@ keep credentials and audio content out of redirects, request logs and durable st
2828
`tests/server/audio-transcriptions.test.ts` exercises the real ingress and synthetic upstream;
2929
`tests/server/api-key-attribution.test.ts` uses multipart fixtures for the HTTP auth matrix.
3030

31+
`src/server/audio-upstream.ts` is also where a configured key's model and provider scope is
32+
applied, once for every audio surface that resolves through it: the model it is handed is the one
33+
the upstream will run — the transcription model, the live session model, or the model a standalone
34+
socket names in its own query — and a refused forward request releases its probe lease. The native
35+
voice path in `src/server/live.ts` applies the same predicate, reading the model from the
36+
call-create session or the socket query and the provider from the upstream it settles on. Coverage
37+
lives in `tests/server/api-key-scope-audio.test.ts` and `tests/server/api-key-scope-live.test.ts`.
38+
3139
## Streaming audio
3240

3341
`src/server/audio-client.ts` recognizes explicit audio keys before local legacy admission.

‎structure/data-planes/search.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,12 @@ find instead of asking for ChatGPT auth, and the request reaches no other backen
1616
fails answers with its own diagnostic. The fallback never runs while a forward candidate exists,
1717
so the verbatim relay stays the path for a ChatGPT deployment.
1818

19+
A configured key's scope covers both branches, each against what it actually reaches. An
20+
account-qualified selector is judged against its resolved route; an unqualified one against the
21+
account the upstream resolved and the model the body names; the fallback against the configured
22+
backend and the model that backend runs, with Exa named by its backend because it has no provider
23+
entry. `tests/server/api-key-scope-alpha-search.test.ts` covers the two unrouted branches.
24+
1925
## Standalone Search and exact account selectors
2026

2127
`POST /v1/alpha/search` retains the selected model in its request body. When that value is an

0 commit comments

Comments
 (0)