Mos approved the P4 brief with upstream API keys added: a human-only write-only verb, z.ai-only allowlist, apikey-invalid and provider-not-allowed refusals, a canary test and an echo mutant. Account ids hash the proxy's own credential identifier, never a token or key value. Account removal stays out of P4.
11 KiB
Brief: row 330 (P4), the Console proxy page
Written 2026-10-24 by Sage for Mos's mos-1606, which carries Jason's Q46 and Q47 answers (DECISIONS Q250).
Mos approved it in mos-1608, adding upstream API keys (item 4) and the account id rule (item 2).
Read the design (docs/plans/2026-10-24_stack-model-proxy.md, amended for Q250) and the rows doc
(docs/plans/2026-10-24_model-proxy-rows.md) first. The rows doc's "Rules for every row" apply here
unchanged. Line numbers are at origin/refactor 0ce22dde6. Check them before you edit.
This brief replaces two parts of the rows doc:
- its P4 brief (the
/proxy/forward to the upstream panel, rows doc :118-182), which is dropped with D8; - P1's two panel acceptance bullets (rows doc :104-108). P1's finding on the OAuth callback URL for Claude and Codex still counts, and this row uses it.
The rows doc isn't edited, because every row from 329 to 333 pins that file's blob and row 329 is near its landing. The P4 brief lives here instead.
Brief: P4 the Console proxy page
Why. Q250: Jason enters accounts in the Console's own proxy page, not in the upstream panel. That covers both his OAuth accounts and his API keys (Q248 item 1, Q249, mos-1608). The page calls bus routes, and the bus calls the proxy's management API (D12). The management key stays in the bus (D6). No new hostname is added. A panel subdomain is a fallback only if our page can't keep up with the management API across pinned proxy upgrades, and that call is Jason's (Q46).
What ships.
- Bus verbs. New broker verbs for the page, for example
proxy.accounts,proxy.login.start,proxy.login.submit,proxy.login.status,proxy.login.cancel,proxy.apikey.add,proxy.priority.setandproxy.keys. Settle the names in BUILD.md.- Every verb is human-only. A tester, agent or granted-user caller refuses
human-required, the way the grants admin verbs do (packages/bus/src/broker.mjs:3721-3731). - With no proxy in the validated config (P1 item 3), every verb refuses
not-configured. - Each verb calls the management client from P1 (
packages/model-proxy/src/client.mjs). P4 adds the calls it needs under P1's rules: the key goes only in theAuthorizationheader, only to loopback, and each call writes a receipt with no body and no secret. - A proxy that doesn't answer refuses
proxy-down, with no retry.
- Every verb is human-only. A tester, agent or granted-user caller refuses
- Accounts.
proxy.accountslists the upstream accounts from the pinned version's credentials endpoint (/credentialsin the 8.0.27 doc,agents/researcher/work/i1-proxy-test/docs/management-api-v8.0.27.md:101).- The bus copies only allowlisted fields: provider, a display name, status and priority, plus an account id. Every other field is dropped, so no token can pass through even if the proxy returns one.
- The account id is the first 12 hex of the sha256 of the proxy's own credential identifier, never of a token or key value (mos-1608).
- Record in BUILD.md which endpoint and fields the pinned version has.
- OAuth sign-in through
oauth/auth-url,oauth/callbackandoauth/status(management-api-v8.0.27.md:108-138).- Start. The page picks a provider from an allowlist:
claudeandcodex. Adding a provider is a reviewed change. The bus callsauth-urland returns the authorization URL and thestate. The page opens the URL in a new tab withnoopenerandnoreferrer. - Return. After Jason signs in, the provider redirects to the callback URL that the proxy named.
P1's acceptance records that URL for each provider. If the redirect reaches the proxy directly, the
status poll shows the result. If it doesn't, Jason pastes the full URL from the address bar into the
page, and the bus POSTs it to
oauth/callbackasredirect_url. - Checks on a pasted URL. It must parse as a URL, stay under a size limit, and carry a
statethat this bus started and that hasn't finished. Anything else refuseslogin-state-unknownorcallback-url-invalid. The URL carries the authorization code, so it is never logged, stored or echoed back. - Status. Only an
okfromoauth/statuscounts as signed in. An accepted callback with statuswaitdoesn't, because the doc says acceptance isn't completion (:136-138). The bus stops polling onok,error, or after a timeout setting (default 300 s). - Cancel calls
DELETE oauth/session.
- Start. The page picks a provider from an allowlist:
- Upstream API keys (mos-1608). A human-only verb (for example
proxy.apikey.add; name it in BUILD.md) adds one upstream API key.- The provider allowlist starts with z.ai only. Adding a provider is a reviewed change. BUILD.md records which management endpoint the pinned 8.0.42 uses for it.
- The Console route has the same checks as the other writes (item 8). The page's input is
type=passwordwithautocomplete=off. - The value is write-only. Neither the Console nor the bus logs it, stores it, caches it, or puts it in a receipt or an error. No part of it is echoed, not even the last four characters. The bus passes it straight to the management API in the request body and then drops it.
- After the add, the key shows in
proxy.accountsthrough the same allowlisted fields, and priority (item 5) works on it. - An empty value, one over a size limit, or one outside a charset refuses
apikey-invalid. A provider outside the allowlist refusesprovider-not-allowed.
- Priority.
proxy.priority.setsets one account's priority, an integer in a range the builder records. Use the pinned version's credential-field endpoint (/credentials/fieldsPATCH in the 8.0.27 doc). Confirm it on the stand-in and record what it changes. A bad account id or value refusespriority-invalid. - Client keys, list only.
proxy.keysreadsGET /config/access/api-keys, maps each value to its key id in memory and drops the value (D15).- It joins P2's record to show agent, issue time and state for each key id.
- The sentinel is labelled. A key without this instance's prefix shows as "not stack-managed".
- The page has no key write. Issue and revoke stay with hire and fire (P2).
- Usage. P5's Console view (rows doc P5 item 3) sits on this page. Whichever of P4 and P5 lands second puts it there. P4 adds no usage source.
- The page and its Console routes. An owner-only
/proxypage inpackages/webui, built like the existing pages, with routes under/api/proxy/.- Each route makes one call over the owner's human transport, the way the Agents section does
(
AGENT_ROUTESatpackages/webui/src/serve.mjs:451,agentCalleratpackages/webui/src/console-bus.mjs:12).consoleBusgets aPROXY_VERBSlist, and the caller refuses any other verb. - Writes need a signed-in owner, the Console's own
Origin,sec-fetch-site: same-origin,--sendand a named host, asagentSendchecks (serve.mjs:459-470). The routes are refused for a granted user (userRoute), on the tester listener and on a loopback Host. - The Console never holds the management key, never reads
proxyfrom the config, and never opens a connection to the proxy port. - Logs record method, route, status and user only. They never record the authorization URL, a pasted callback URL, a state, an API key or a body.
- Each route makes one call over the owner's human transport, the way the Agents section does
(
- Upgrade check. An acceptance script, beside P1's and outside the gate's
scripts/test-*.shset, runs the bus verbs against the pinned binary underunshare -rn. It uses a made-up config, key and data root in a fresh temp root, the same way P1's run does.- With no network, it checks what can be checked offline. The account list starts empty.
auth-urlreturns a URL and a state forclaudeand forcodex. A callback with a made-up code never reportsok. A made-up z.ai API key added through the verb shows in the account list, and a priority set on it reads back. The key list returns ids only. - It prints the endpoints and fields the page relies on, so a version change shows up as a diff.
packages/model-proxy/README.mdrecords the rule: a PIN change lands only with this script's output for the new version in that row's BUILD.md, and Sage's landing gate checks for it.- If the script fails on a new version and the row can't fix the page, the row stops. Sage takes Q46's fallback to Jason through Mos.
- With no network, it checks what can be checked offline. The account list starts empty.
Tests. Cover each of these:
- every verb against a fake management server;
- each refusal code by its own test (mos-1590):
not-configured,human-requiredfor the tester, an agent and a granted user,provider-not-allowedfor sign-in and for an API key,login-state-unknown,callback-url-invalid,apikey-invalid(empty, over the size limit and outside the charset, each its own case),priority-invalidandproxy-down; - an API-key canary: a unique made-up value goes through the Console route against the fake management server. Afterwards every Console and bus log, receipt, response, store file and error output from that run has zero matches for it, and the fake received it exactly once;
- an added API key listed by
proxy.accountswith allowlisted fields only, and priority set on it; - account ids derived from the credential identifier, with a fake whose token values never appear in an id;
- a fake that puts token-like values in every credential field, where no value reaches a response, log or receipt;
- a fake key list with full values, where only ids come back, the sentinel is labelled and a foreign key is marked;
- no authorization URL, callback URL, code or state in any log or receipt;
- an accepted callback with status
waitnot reported as signed in; - the Console routes: owner allowed, and a granted user, the tester listener, a loopback Host, a
signed-out request, a cross-origin request and a request without
sec-fetch-siteeach refused, and every write read-only without--send; - no
packages/webuimodule imports the model-proxy client or reads theproxyconfig.
Out of scope.
- Removing or disabling an account. Mos is filing a Vikunja task for a later row (mos-1608).
- Every routing setting other than account priority.
- Issuing or revoking client keys (P2), and any usage source (P5).
- The upstream panel, any forward to the proxy port, and the subdomain fallback.
- Traefik, DNS, Authentik settings, and the .54 Console's provider (Q218).
- Any live instance, the management key, and the 8317 proxy.
Order. P4 starts when P1 lands, because it needs P1's client and config contract. It rebases on P2 before its gate, for the key join, and lands after P2.
Gate. Gladstone gives the first Codex review, and Filbert reviews the landing candidate. The model-proxy,
bus and webui suites run whole, webui with MOSAIC_REQUIRE_EDITOR_BUILD=1. Every touched test file runs
whole. The named mutants below are killed. Every package suite but queue plus every scripts/test-*.sh is
green on Sage's landing gate. BUILD.md has the upgrade-check output on the pinned version. Mutants: the
accounts verb returns an unfiltered field; the callback verb skips the state check; a /api/proxy/ route
accepts a granted user; the API-key verb echoes the value in an error or a log.