Files
stack/docs/plans/2026-10-24_proxy-page-brief.md
jason.woltje 966ee31ea8 docs: row 330 P4 brief and design D7/J4 for mos-1608
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.
2026-10-24 15:54:18 -05:00

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.

  1. 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.set and proxy.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 the Authorization header, 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.
  2. Accounts. proxy.accounts lists the upstream accounts from the pinned version's credentials endpoint (/credentials in 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.
  3. OAuth sign-in through oauth/auth-url, oauth/callback and oauth/status (management-api-v8.0.27.md:108-138).
    • Start. The page picks a provider from an allowlist: claude and codex. Adding a provider is a reviewed change. The bus calls auth-url and returns the authorization URL and the state. The page opens the URL in a new tab with noopener and noreferrer.
    • 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/callback as redirect_url.
    • Checks on a pasted URL. It must parse as a URL, stay under a size limit, and carry a state that this bus started and that hasn't finished. Anything else refuses login-state-unknown or callback-url-invalid. The URL carries the authorization code, so it is never logged, stored or echoed back.
    • Status. Only an ok from oauth/status counts as signed in. An accepted callback with status wait doesn't, because the doc says acceptance isn't completion (:136-138). The bus stops polling on ok, error, or after a timeout setting (default 300 s).
    • Cancel calls DELETE oauth/session.
  4. 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=password with autocomplete=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.accounts through 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 refuses provider-not-allowed.
  5. Priority. proxy.priority.set sets one account's priority, an integer in a range the builder records. Use the pinned version's credential-field endpoint (/credentials/fields PATCH in the 8.0.27 doc). Confirm it on the stand-in and record what it changes. A bad account id or value refuses priority-invalid.
  6. Client keys, list only. proxy.keys reads GET /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).
  7. 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.
  8. The page and its Console routes. An owner-only /proxy page in packages/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_ROUTES at packages/webui/src/serve.mjs:451, agentCaller at packages/webui/src/console-bus.mjs:12). consoleBus gets a PROXY_VERBS list, and the caller refuses any other verb.
    • Writes need a signed-in owner, the Console's own Origin, sec-fetch-site: same-origin, --send and a named host, as agentSend checks (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 proxy from 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.
  9. Upgrade check. An acceptance script, beside P1's and outside the gate's scripts/test-*.sh set, runs the bus verbs against the pinned binary under unshare -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-url returns a URL and a state for claude and for codex. A callback with a made-up code never reports ok. 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.md records 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.

Tests. Cover each of these:

  • every verb against a fake management server;
  • each refusal code by its own test (mos-1590): not-configured, human-required for the tester, an agent and a granted user, provider-not-allowed for 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-invalid and proxy-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.accounts with 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 wait not 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-site each refused, and every write read-only without --send;
  • no packages/webui module imports the model-proxy client or reads the proxy config.

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.