diff --git a/docs/plans/2026-10-24_proxy-page-brief.md b/docs/plans/2026-10-24_proxy-page-brief.md new file mode 100644 index 000000000..a27c49c44 --- /dev/null +++ b/docs/plans/2026-10-24_proxy-page-brief.md @@ -0,0 +1,129 @@ +# 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). +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. 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.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 (the first 12 hex of a sha256, as for key ids). Every other field is dropped, so no token + can pass through even if the proxy returns one. + - 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. **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`. +5. **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). +6. **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. +7. **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 or a body. +8. **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 priority set on a made-up credential reads back, if the stand-in can hold one. 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, a provider outside the allowlist, `login-state-unknown`, + `callback-url-invalid`, `priority-invalid` and `proxy-down`; +- 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.** +- Upstream API keys such as z.ai. Mos's list for the page (mos-1606) doesn't name them, and entering one + means a secret crosses the Console. Sage has asked Mos. Until Mos rules, the page has no API-key entry. +- Removing or disabling an account, and 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. diff --git a/docs/plans/2026-10-24_stack-model-proxy.md b/docs/plans/2026-10-24_stack-model-proxy.md index b62b1dd96..f45f5144f 100644 --- a/docs/plans/2026-10-24_stack-model-proxy.md +++ b/docs/plans/2026-10-24_stack-model-proxy.md @@ -5,6 +5,12 @@ becomes the stack's credential and routing layer, with Q116 and Q127 still in fo Mos rules it before any code. Its build rows go to new Codex gpt-6.1-sol threads (Q246), and each gets its own brief once Mos has ruled. Line numbers are at origin/refactor 2ce476d54. +**Amendments.** Mos's mos-1600, mos-1601 and mos-1602 changes live in the row briefs +(`docs/plans/2026-10-24_model-proxy-rows.md`), which win over this design where they differ. Jason's Q46 +and Q47 answers (DECISIONS Q250, mos-1606, 2026-10-24) are written into this file: accounts are entered in +the Console's own proxy page, and the `/proxy/` forward to the upstream panel (D8) is dropped. The P4 brief +for that page is `docs/plans/2026-10-24_proxy-page-brief.md`. Text marked "(Q250)" below is that change. + Not to be confused with queue row 237 ("one decision lands once", `2026-10-20_agent-credentials.md`). This is Vikunja task 237. @@ -75,11 +81,13 @@ whose sha256 matches PIN. The control panel asset is pinned the same way, with (`config.example.v8.0.27.yaml`:94-103), and that would be unreviewed code behind Authentik. The stack never copies the 8317 binary. The first fetch of the release asset counts as external access, so it is Jason's step J1 or a row Mos approves. For containerized installs the binary and panel go into the proxy image -(section 8). +(section 8). Q250: nothing serves the panel to the Console now. P1 keeps the pin as built, and +removing it is a later cleanup. D5. **Initial config, then hands off.** The stack writes `config.yaml` once, when `/proxy/` is first created, from a template in `packages/model-proxy/`, and never writes the file again. After that the -stack changes the proxy only through the management API, and Jason changes it only through the panel. +stack changes the proxy only through the management API, and Jason changes it only through the Console's +proxy page, which calls the bus, which calls the management API (Q250). Row 96 point 2 (every management write rewrites the whole file and reorders it) then stops mattering, because nobody edits the file by hand. The template sets the defaults in section 3 and section 7, `request-retry: 0` so no hidden retries happen (as in row 96), the client-key list holding only the @@ -93,31 +101,22 @@ prompt doesn't echo the key. It writes the key to `/secrets/proxy-man the initial `config.yaml`. The proxy hashes it in place on its first start (row 96 point 6). The stack reads only the secrets file, never the hashed value in config. The holder is the bus process alone (D12). The sandbox doesn't mount `/secrets`, so no session can read the key, and no verb returns it. Jason -types the same key into the panel to sign in. An agent never runs the prompt (Q173). +types the key only at that prompt. The Console's proxy page needs only his Console sign-in, and the bus adds +the key to its own management calls (Q250). An agent never runs the prompt (Q173). -D7. **Upstream credentials.** Jason adds every upstream account in the proxy's own panel: OAuth sign-ins -(Claude, Codex and the others CLIProxyAPI supports) and API keys (for example z.ai). They live in the +D7. **Upstream credentials.** Accounts are entered in the Console's proxy page (Q250). It covers OAuth +sign-ins for Claude and Codex through the management API's `oauth/auth-url`, `oauth/callback` and +`oauth/status`, and account priority. Whether the page also takes upstream API keys (for example z.ai) is +open with Mos. They live in the proxy's `auth/` directory and config and nowhere else. There is no per-seat credential file. The stack never reads, copies or logs an upstream credential. -D8. **Panel path.** The Console forwards `https://mosaic.woltje.com/proxy/` to `127.0.0.1:`, for -the panel route and the management routes only. It forwards only after its existing auth-header and -allowed-user check (decision 103, `packages/webui/src/serve.mjs`:453-469) passes. The Console never adds or -stores the management key. Jason types it in the panel, and it passes through the forward. This adds no DNS -record and no subdomain, as Q116 requires. Traefik and the tunnel already deliver mosaic.woltje.com to the -Console (7332), so no infra change is needed. The forward gives no new authority. The management key -is the barrier, and loopback processes can already reach the proxy port. Authentik is the outer layer. The -#385 hole (a loopback process forging the Host and header) applies here the same way and is no worse, -since the management key is still required. - -A second Console (.54) forwards to its own instance's proxy, and its Authentik provider settings are Jason's -(Q218). - -Checks for the build row, on a stand-in under `unshare -rn` as in row 96: -- the pinned panel works under the `/proxy/` sub-path (rewrite or base-path setting); -- an OAuth sign-in done from the panel through the forward completes. If the callback can't return through - the forward, the fallback is Jason running the proxy's CLI login in his own shell (`-claude-login - -no-browser` and similar), and J3 says so. +D8. **Dropped (Q250).** The design had the Console forward `https://mosaic.woltje.com/proxy/` to the +proxy's own panel. Jason's Q46 and Q47 answers replace it with the Console's own proxy page (D7). The page +calls bus routes, the bus calls the management API (D12), and 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. Each pinned upgrade runs the page's acceptance +script against the new version (P4 brief item 8). ## 3. Priority routing, and how the business routing table maps onto it @@ -131,10 +130,12 @@ The proxy picks which upstream account serves that model. The two don't overlap: - Account failover inside one model is the proxy's job. The stack doesn't model accounts per session. D10. **Priority settings.** Defaults set in the template are listed below (Q222: settings with defaults). -Jason can change all of them in the panel. +Jason sets account priority in the Console's proxy page. The other routing settings keep the template +defaults, and a page control for them is a later row (Q250). - `routing.strategy: fill-first`. A subscription account is used until it is rate-limited or out of quota, then the next one (`config.example`:150). -- Each account gets a `priority` (larger first, `config.example`:480). Jason sets the order in the panel (J4). +- Each account gets a `priority` (larger first, `config.example`:480). Jason sets the order in the Console's + proxy page (J4). - `routing.session-affinity: true`, so a session stays on one account while it works and keeps its prompt cache (:154-171). Default `session-affinity-rebind-on: quota`, so a transient 5xx doesn't move a session. - No model aliases or alias pools by default. A pool that maps one name to several upstream models @@ -270,7 +271,7 @@ D20. **Settings and who changes them.** Every number in this design is a setting `rotateBy` 30 d, `proxy.rotateGraceMinutes` 120, `proxy.firstOutputSeconds` 120, `usage.cliproxyQueue.pollSeconds` 15, routing strategy fill-first, affinity on. The per-key daily quota and the rotation period guard the human from agents, so only a human can change them (Q222). The routing settings live in the proxy and only Jason -changes them, in the panel. +changes them. Account priority is in the Console's proxy page, and the rest keep their defaults (Q250). ## 8. Row 157 re-scope (#1652, Vikunja 617) @@ -297,7 +298,7 @@ changes. Cutover, per instance, with Jason present (Q127): 2. Jason fetches and verifies the pinned binary and panel (J1). ops-01 or Sage checks the sha256 against PIN. 3. Jason adds the `proxy` section to the instance config (J2), runs `mosaic proxy init` (D6), and starts `mosaic-proxy.service`. The bus isn't restarted yet. -4. Jason signs in to the panel and adds the accounts (J3, J4). No session uses the proxy yet. +4. Jason adds the accounts in the Console's proxy page (J3, J4). No session uses the proxy yet. 5. A Console or bus restart (Jason or Mos, per Q173) picks up the section. The bus reconciles, issues a key for each listed agent, and runs D17's preflight for each one. Any refusal stops the cutover, and the fix is to remove the section and restart. @@ -318,15 +319,13 @@ accounts (J7). The 8317 host proxy and its clients are not part of any step. - **J2.** Add `"proxy": { "port": , "binary": "" }` to the instance's `config.json`, in an editor. - **J3.** In a terminal of your own, run `mosaic proxy init` and type a new management key twice. Keep it in your - password manager. Then open `https://mosaic.woltje.com/proxy/` and sign in to Authentik as jason.woltje. - Paste the management key into the panel's login box. -- **J4.** In the panel's auth or OAuth page, sign in to each subscription account you want this instance to use - (Claude, Codex, and so on). On the API keys page, paste each API key you want it to have (for example z.ai). - Set each account's priority. The highest one is used first, and the next one only when the first is - limited. If an OAuth sign-in doesn't return to the panel, run the CLI login the cutover note gives, in your - own terminal. -- **J5.** Watch the Console while the two test sessions run (cutover step 6), and confirm the panel's usage page - shows their requests on the account you expect. + password manager. You don't type it anywhere else (Q250). +- **J4.** Open the Console's proxy page and sign in to Authentik as jason.woltje. Sign in to each subscription + account you want this instance to use (Claude, Codex). If the sign-in tab doesn't return on its own, copy + the full address from that tab and paste it into the page. Set each account's priority. The highest one is + used first, and the next one only when the first is limited. API keys such as z.ai wait on Mos's ruling. +- **J5.** Watch the Console while the two test sessions run (cutover step 6), and confirm the proxy page's usage + section shows their requests on the account you expect. - **J6.** After 7 days on the proxy, delete `claude-session.env` for that instance. - **J7.** For Melanie's .54 hub, decide which accounts it uses: hers, yours, or new ones. Then do J2 to J4 on .54 through its own Console's Authentik provider (Q218). Only accounts you entered for that hub go into its @@ -339,10 +338,10 @@ credentials, so a Claude reviewer (Dewey) gives the second review. Sage runs the | Row | Piece | Depends on | |---|---|---| -| P1 | `packages/model-proxy/`: PIN, template, management client, `mosaic proxy init`, the `mosaic-proxy` unit, config `proxy` section, stand-in tests (empty list, `/v1/models` local, 401 shape, panel sub-path, OAuth through the forward) | Mos's ruling on D3 | +| P1 | `packages/model-proxy/`: PIN, template, management client, `mosaic proxy init`, the `mosaic-proxy` unit, config `proxy` section, stand-in tests (empty list, `/v1/models` local, 401 shape, OAuth callback URL; the panel checks are dropped, Q250) | Mos's ruling on D3 | | P2 | Per-agent keys: `model` store kind, issue, rotate, revoke, reconcile, D17 preflight | P1, rows 194 and 199 | | P3 | Harness config: Claude Code env, pi `models.json` and preflight, `sessionEnv` proxy mode | P2 | -| P4 | Console `/proxy/` forward behind the existing auth check | P1 | +| P4 | The Console proxy page and its bus verbs (Q250, `2026-10-24_proxy-page-brief.md`) | P1; lands after P2 | | P5 | `usage` plug-in kind and the `cliproxy-queue` module; key ids in `launch.limits.tokens` | P2 | | P6 | Row 157 brief amendment (section 8) | Row 157 resuming | | P7 | Cutover note and per-instance window (section 9) | P1 to P4 landed; Jason present | @@ -353,7 +352,7 @@ The Codex harness config (D16) goes with the Codex harness row, which isn't on t 1. D1/D3: the `proxy` section in the instance config (a schema change), and the proxy as its own user unit. 2. D6: the management key set by Jason at a human-only prompt and held only by the bus process. -3. D8: the Console forwards `/proxy/` rather than a new Traefik route. +3. D8: ruled. Jason's Q46 and Q47 (Q250) drop the forward for the Console's own proxy page. 4. D13: an implicit per-agent model key with no role-file change. 5. D15: plaintext keys at rest accepted under those limits. 6. D16: proxy mode drops the instance-wide provider variables from every session.