|
| 1 | +# 000 — Research: remote hub mode (evidence base) |
| 2 | + |
| 3 | +Unit: 260827_remote_hub · Branch: codex/remote-hub-design · Status: research |
| 4 | + |
| 5 | +## Motivation (user request, 2026-08-27) |
| 6 | + |
| 7 | +Run one ocx as a central HUB (Oracle VM / Mac mini / Docker — any machine), keep every |
| 8 | +provider key, OAuth credential, and shared config there, and let other machines connect |
| 9 | +with only a pointer + token ("ocx connect <tailnet-dns>"). The dashboard on a client |
| 10 | +machine must still work at localhost:10100 with a two-plane split: shared pages operate |
| 11 | +the hub, machine pages operate local file integration. Explicit constraint from the user: |
| 12 | +today a Tailscale-bound GUI is unusable for some operations even WITH the admin token — |
| 13 | +the design must fix remote GUI operability without collapsing the consent boundary. |
| 14 | + |
| 15 | +## In-repo evidence (verified 2026-08-27 on dev @ 8b1b65b8d) |
| 16 | + |
| 17 | +- Non-loopback bind forces the data token: `isApiAuthRequired` returns true whenever the |
| 18 | + bind hostname is not loopback (src/server/auth-cors.ts:260-262), and startup refuses a |
| 19 | + public bind without a configured data credential. |
| 20 | +- The remote-GUI limitation is a deliberate restriction, not an unreported weakness, and |
| 21 | + it is already visible in shipped public code: `issueGuiSession` returns null when |
| 22 | + `isApiAuthRequired(config)` is true and additionally requires a loopback Host |
| 23 | + (src/server/management-auth.ts, `issueGuiSession`). The published dashboard guide |
| 24 | + states the same boundary in user terms. |
| 25 | + |
| 26 | + The consequence is a capability gap rather than an exposure: on a remote bind the |
| 27 | + principal `gui-session` is unobtainable, so consent-bearing routes requiring |
| 28 | + `ctx.principal === "gui-session"` (src/server/management/sidebar-routes.ts:42, |
| 29 | + src/server/management/codex-prompt-routes.ts:298) answer 403 even to the admin token. |
| 30 | + That 403 is correct and stays correct — the admin token must never be able to spend the |
| 31 | + user's consent (AGENTS.md user-consent boundary). What is missing is any path for a |
| 32 | + *browser* to mint a session remotely, which is what this unit designs. |
| 33 | + |
| 34 | + Stated precisely: the current behavior fails closed. Nothing here describes a way to |
| 35 | + obtain authority one should not have, so this note is a design rationale rather than |
| 36 | + pre-disclosure material, and `AGENTS.md`'s scratch-space rule for unfixed defects does |
| 37 | + not apply to it. Anything in this unit that WOULD describe an unfixed exploitable |
| 38 | + weakness belongs in scratch space, not in `devlog/`. |
| 39 | +- `managementRequestOrigin` returns null for a non-loopback Host when apiAuth is NOT |
| 40 | + required (src/server/auth-cors.ts:118-129); when apiAuth IS required it derives the |
| 41 | + origin from the request, which a TLS terminator breaks (http observed vs https public). |
| 42 | +- The GUI attaches credentials only same-origin: `needsApiAuth` refuses absolute |
| 43 | + cross-origin URLs (gui/src/api.ts:53-60). A two-plane GUI therefore needs an explicit |
| 44 | + multi-target API layer, not a base-URL swap. |
| 45 | +- The GUI needs a secure context in places: `crypto.subtle.digest` at |
| 46 | + gui/src/log-conversation-id.ts:26, `navigator.clipboard` at |
| 47 | + gui/src/oauth-health-display.ts:133 (with execCommand fallback). |
| 48 | +- Injector already supports non-loopback targets: dedicated provider block with |
| 49 | + `env_key = "OPENCODEX_API_AUTH_TOKEN"` and `model_catalog_json` requiring a LOCAL |
| 50 | + absolute path (src/codex/inject.ts:186-247, 622+). |
| 51 | +- `GET /api/catalog` and `GET /api/client-config` already exist behind management auth |
| 52 | + (src/server/management/model-routes.ts:334-420). |
| 53 | +- Headless OAuth exists: `oauthOpenBrowser: false` (src/oauth/open-browser-choice.ts) and |
| 54 | + `POST /api/oauth/login/code` (src/server/management/oauth-account-routes.ts:208). |
| 55 | +- Allowlist-listener precedent: the unauthenticated loopback listener enumerates exactly |
| 56 | + the routes it serves (src/server/index.ts, loopbackRouteAllowed) — the machine-plane |
| 57 | + listener should copy this failure mode (default-404). |
| 58 | +- Token-file delivery precedent: `OCX_API_TOKEN_FILE` (src/lib/service-secrets.ts, |
| 59 | + src/service.ts:1571+). |
| 60 | +- CLI already talks to the management API over HTTP with injectable baseUrl |
| 61 | + (src/cli/runtime-api.ts, RuntimeApiDeps.baseUrl) — client-mode remote management |
| 62 | + commands are a URL + credential change, not a new client. |
| 63 | + |
| 64 | +## External evidence (Luna swarm, 3 lanes, sources opened 2026-08-27) |
| 65 | + |
| 66 | +Peer proxies separate UI sessions from master keys: |
| 67 | +- LiteLLM: LITELLM_MASTER_KEY for API/admin, separate UI login minting expiring |
| 68 | + virtual keys; per-user/per-device virtual keys with budgets, central key custody. |
| 69 | + https://docs.litellm.com.cn/docs/proxy/ui , virtual_keys.md / access_control.md in |
| 70 | + BerriAI/litellm-docs (opened 2026-08-27). |
| 71 | +- sub2api: admin web UI uses JWT session; automation uses a separate global Admin API |
| 72 | + Key (x-api-key). https://github.com/Wei-Shaw/sub2api (opened 2026-08-27). |
| 73 | +- One API broken-access-control reports (#2410, #2423) show central key custody makes |
| 74 | + route-level authz the main defense. |
| 75 | + |
| 76 | +Tailscale transport facts (official docs, verified dates in page footers): |
| 77 | +- `tailscale serve` = tailnet-only reverse proxy to a localhost backend; injects |
| 78 | + Tailscale-User-* identity headers; backend must bind loopback or headers are |
| 79 | + spoofable. https://tailscale.com/docs/features/tailscale-serve |
| 80 | +- `tailscale cert` issues public CA certs only for the ts.net FQDN (not bare MagicDNS |
| 81 | + short names); names land in Certificate Transparency logs. |
| 82 | + https://tailscale.com/docs/how-to/set-up-https-certificates |
| 83 | +- Funnel is public-internet exposure (ports 443/8443/10000) — out of scope here. |
| 84 | + |
| 85 | +Browser platform facts (MDN/WHATWG/IETF, opened 2026-08-27): |
| 86 | +- Plain-HTTP non-localhost origins are NOT secure contexts: no crypto.subtle, no |
| 87 | + async clipboard, Secure cookies unavailable. http://localhost IS potentially |
| 88 | + trustworthy. https://developer.mozilla.org/en-US/docs/Web/Security/Defenses/Secure_Contexts |
| 89 | +- Header-token SPAs avoid ambient-cookie CSRF but still need exact-origin allowlists |
| 90 | + and Origin checks on mutations (WHATWG Fetch; RFC 9700 OAuth BCP). |
| 91 | +- RFC 8628 device flow is the reference pattern for headless-hub OAuth; ocx's |
| 92 | + oauthOpenBrowser:false + /api/oauth/login/code is already equivalent in shape. |
| 93 | + |
| 94 | +## Design consequences (carried into 010) |
| 95 | + |
| 96 | +1. Two credential worlds stay separate: data-plane admission (client machines) vs |
| 97 | + management (admin token / gui-session). Peers (LiteLLM, sub2api) validate this split. |
| 98 | +2. Remote GUI needs a NEW session-issuance path, not a weakening of requireManagementAuth: |
| 99 | + the loopback-only refusal in issueGuiSession is the single gate to generalize. |
| 100 | +3. HTTPS via tailscale serve against a loopback-only management ingress is the |
| 101 | + recommended browser path; plain-HTTP tailnet operation must exist as a documented |
| 102 | + opt-in because usability on a private tailnet was the user's explicit complaint. |
| 103 | +4. localhost:10100 client GUI + direct-to-hub shared plane is cross-origin; the hub |
| 104 | + needs management CORS for an allowlisted client origin, or the client listener |
| 105 | + relays. Both appear in 010 with the relay constrained to a fixed target. |
0 commit comments