Skip to content

feat(client): relay the hub management plane for local callers - #8079

Closed
tachyon6 wants to merge 5 commits into
lidge-jun:devfrom
tachyon6:codex/client-management-relay
Closed

tachyon6 wants to merge 5 commits into
lidge-jun:devfrom
tachyon6:codex/client-management-relay

Conversation

@tachyon6

@tachyon6 tachyon6 commented Nov 1, 2026 •

Copy link
Copy Markdown
Contributor

Problem

A connected client stores only a per-client data key. Its listener answered 404 for every /api/* path, so the machine's own tools could not read accounts at all:

  • ocx account list printed Error: not_found
  • the AImorph menu-bar panel failed to load accounts, so + 계정 추가 and re-login never worked
  • the usage reporter's ocx_accounts() returned None on every run

Inference was unaffected, which is why this stayed invisible: only the account surfaces broke.

The relay for exactly this existed already, but only the dashboard used it.

Change

A hub client relays any /api/* path it does not own to the hub and answers with the hub's own handler. /api/machine/* stays local; the data plane is untouched. This is independent of managementTransport — direct is how a browser reaches the hub, but a CLI has no route to it at all.

Nothing reaches the wire credential-free. ocx connect already obtained a management credential in order to issue the client key — a gui-session from the pairing exchange, or the admin token — and then threw it away. It is now kept at ~/.opencodex/hub-management-session.json (mode 0600) and stamped on the relayed request.

Only a hub-issued session is stamped over. A CLI attaches the local config home's admin token, which the hub does not know; the first cut of this kept it and every read still 401'd until the e2e run showed the wrong token leaving the machine.

  • a browser that brings its own session keeps it
  • ocx connect rotate refreshes the stored value, ocx disconnect removes it
  • ocx connect status / ocx status report its state without the value

A pairing grant is single-use, so an expired session is not silently re-exchanged: management reads answer 401 until the next ocx connect rotate, and status says so. Inference keeps working.

Verification

End to end against a stub hub and a real connected client runtime, ocx account list, a raw GET /api/codex-auth/accounts, /api/provider-quotas, and an ocx account use PUT all reached the hub with the stored session and returned 200:

GET /api/codex-auth/accounts key=ocx_session_ss origin=http://localhost:10100
PUT /api/codex-auth/active    key=ocx_session_ss origin=http://localhost:10100

bun run test --changed=dev: 10167 pass, 4 fail. Two were real and are fixed and re-run green: /api/stop relays now, so connected-stop-capability-auth and two other assertions finally expect the relay. Two timeouts came from a live client I had left running and pass without it. One failure, catalog-omit-disabled-native, is a models_cache.json ENOENT that reproduces identically on a clean origin/dev worktree. bun run typecheck clean. Tests cover the store, the stamp (CLI caller, local admin token replacement, browser keeps its own), and the listener relaying a bare management path while machine routes stay local.

Limits

  • The stored session keeps the origin it was minted for, so the hub must already allow that origin in corsAllowOrigins — the same entry ocx hub invite demands. Changing the client's listener port after connecting invalidates it until the next rotate. Documented in guides/remote-hub.md.
  • The credential is a session with the hub's own TTL (12h for pairing), not a permanent grant. Re-running ocx connect rotate needs a fresh code from the hub.
  • Remote Link children are unchanged: they keep their read-only link relay.

Closes nothing; no issue filed yet.

Review readiness checklist

This PR stays in draft until every box below is ticked. Tick all four boxes once the requirements are met:

  • Required local validation passed; commands, results, and any full-suite exception are documented.

  • I pushed my PR to a recent dev commit (at most 10 behind; a maintainer may still ask for the exact tip before merge).

  • I resolved all correct Codex and CodeRabbit findings.

  • My PR is ready for review.

@github-actions

github-actions Bot commented Nov 1, 2026

Copy link
Copy Markdown
Contributor

✅ Deterministic PR hygiene checks passed.

@github-actions github-actions Bot added the enhancement New feature or request label Nov 1, 2026
@github-actions github-actions Bot changed the title feat(client): relay the hub management plane for local callers [WRONG BRANCH] feat(client): relay the hub management plane for local callers Nov 1, 2026
@github-actions

github-actions Bot commented Nov 1, 2026 •

Copy link
Copy Markdown
Contributor

⏳ DRAFT

  • review readiness checklist open (0/4 boxes ticked).

What to do

  • Tick all four boxes in the PR description once you're done (currently 0/4).

Review readiness checklist

  • ⬜ Required local validation passed; commands, results, and any full-suite exception are documented.
  • ⬜ I pushed my PR to a recent dev commit (at most 10 behind; a maintainer may still ask for the exact tip before merge).
  • ⬜ I resolved all correct Codex and CodeRabbit findings.
  • ⬜ My PR is ready for review.

0/4 boxes ticked.

This PR stays in draft until every box above is ticked.

Hygiene

✅ Deterministic PR hygiene checks passed.

@github-actions
github-actions Bot marked this pull request as draft November 1, 2026 14:09
@coderabbitai

coderabbitai Bot commented Nov 1, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@tachyon6
tachyon6 changed the base branch from main to dev November 1, 2026 14:10
@github-actions github-actions Bot changed the title [WRONG BRANCH] feat(client): relay the hub management plane for local callers feat(client): relay the hub management plane for local callers Nov 1, 2026
A connected client stores only a per-client data key. Its listener answered
404 for every `/api/*` path, so the machine's own tools could not read
accounts at all: `ocx account list`, the AImorph panel and the usage
reporter all died on `not_found`, and the panel's add/reauth never worked.

The relay already existed for the dashboard. This points it at the CLI too:
a hub client now relays any `/api/*` path it does not own to the hub and
answers with the hub's own handler. `/api/machine/*` stays local.

Nothing reaches the wire credential-free. `ocx connect` already obtained a
management credential to issue the client key — a gui-session from the
pairing exchange, or the admin token — and threw it away. That credential is
now kept at `hub-management-session.json` (0600) and stamped on relayed
requests. A browser bringing its own session or admin token keeps it.
`ocx connect rotate` refreshes it, `ocx disconnect` removes it, and
`ocx connect status` reports its state without the value.

A pairing grant is single-use, so an expired session is not re-exchanged
automatically: management reads 401 until the next `ocx connect rotate`,
while inference keeps working. `ocx status` says so.

Tests cover the store, the stamp (including EUID-free CLI callers and a
browser that must keep its own credential), and the listener relaying a bare
management path while machine routes stay local. Two existing assertions
that expected a client-local 404 now expect the relay.
The first cut of this kept any caller credential already present. A CLI on a
connected machine attaches the LOCAL config home's admin token, which the hub
does not know, so every account read still 401'd while the e2e run showed the
wrong token leaving the machine.

Only a hub-issued session is valid at the hub, so the stored credential now
replaces anything that is not one. The origin gate takes the stamped session's
browser origin rather than the caller's own port, which also fixes a CLI whose
listener port differs from the port the session was minted for.

Also documents that the hub must allow the client's origin in
`corsAllowOrigins` (the same entry `ocx hub invite` already demands) and that
changing the client port invalidates the session's origin.

Verified end to end against a stub hub: `ocx account list`, a raw
`/api/codex-auth/accounts` GET, and an `ocx account use` PUT all reach the hub
with the stored session and return 200.
/api/stop is a management path, so the loopback call is relayed to the hub now. The
fixture has no hub behind it, which is 502; the attested preflight the test exists
for still runs first and still passes.
@tachyon6
tachyon6 force-pushed the codex/client-management-relay branch from 4eef774 to 873b0a7 Compare November 1, 2026 14:18
 is the config home of my local end-to-end run, not repo content.
The stamp comment still said a caller's credential is kept, written before the fix
that replaced a CLI's own admin token.
@lidge-jun

Copy link
Copy Markdown
Owner

Maintainer review (contributor-backlog lane), head f5e1cd48b9.

Please fix this first, whatever happens to the feature. The head commit tracks a top-level undefined/ directory: a complete opencodex home (admin-api-token, spend-ledger.salt, thought-signature-replay.salt, codex-accounts.json, config.json backups, routing and usage logs). 06992f2965 removed it, and f5e1cd48b9 added it back. That looks like a test or script that resolved its home to the string "undefined" relative to the working directory. Please:

  1. remove the directory and rewrite the branch so it is gone from the branch history, not just from the head;
  2. if any of it came from a real home rather than a test fixture, rotate that admin token;
  3. find the path that produced undefined/ and fail loudly when the home is unset, so it cannot recur.

On the feature. The bug is real: a connected client's loopback listener 404s on /api/*, so management reads break while inference works. But 2,482 lines, a new at-rest credential on every connected client (hub-management-session.json holding a hub session or admin token), and changes to connect rotate/disconnect/status are a lot of auth surface for a fix with no linked issue. Please open an issue describing the failing commands, then reopen this as a smaller PR: the read-only relay of the specific /api/* routes that ocx account list and the usage reporter need, using the credential the client already holds if possible. Any new stored credential will need maintainer security sponsorship. I am not reviewing this head for merge.

@lidge-jun

Copy link
Copy Markdown
Owner

Merge-manager review (owner accepted this feature in the 2026-11-14/15 backlog review, subject to the security review MAINTAINERS.md requires). The security review found blockers, so this needs changes before it can merge:

  1. Relayed management calls must require local auth. In src/client/machine-listener.ts (~280) a request without a machine-session header or Origin skips local auth and goes to relayHubManagementRequest, which then stamps the stored hub credential (src/client/hub-relay.ts ~175) and satisfies its own origin check from the stored origin (~286-289). Any local process can then act on the hub with that credential. Require the local admin token or a machine GUI session on every relayed path (the same gate as /api/machine/hub-relay/*), and only then swap in the hub credential.
  2. Add an explicit relay denylist, at least /api/stop, /api/github/star (see AGENTS.md "User-consent actions"), /api/system/*, and the hub's admin-token / API-key routes.
  3. ocx stop on a client must not reach the hub. stopProxyGracefullyDetailed posts /api/stop with the local admin token (src/lib/process-control.ts ~283/295); with the relay it is forwarded to the hub. The change in tests/service/connected-stop-capability-auth.test.ts (404 → 502 "relayed") records this instead of preventing it.
  4. Host/Origin anti-rebinding on the relay, as link ingress does with isAllowedRequestOrigin.
  5. Remove the committed undefined/ directory (21 files: admin-api-token, codex-accounts.json, sqlite files, .opencodex-owner.json with a local absolute path). 06992f2965 removed it and f5e1cd48b9 re-added it; please also find the test that wrote to OPENCODEX_HOME=undefined.
  6. Prefer storing a hub session over the hub admin token at rest (src/client/connect.ts ~242-295); if admin stays, document that the hub's root credential lives on the client. Align guides/remote-hub.md (~145, ~153) with the code.
  7. Tests for the denied paths: unauthenticated mutation, rebinding Host, /api/stop and /api/github/star not relayed, hub credential never reaching an unauthenticated caller. The current listener test at client-machine-listener.test.ts ~576 asserts the opposite.

The branch is also 463 commits behind dev with conflicts in src/client/connect.ts, src/client/machine-listener.ts and two client tests; please merge dev when you push the fixes.

@lidge-jun

Copy link
Copy Markdown
Owner

Carried in #8925 with a Co-authored-by trailer for your work, built from current dev without the committed undefined/ directory and with the 2026-11-15 security review items addressed (local auth on every relayed call, relay denylist, ocx stop kept off the hub, Host/Origin checks, no hub admin token at rest, denied-path tests). Nothing further is needed from you here; if any file in that directory came from a real home rather than a test fixture, please rotate that admin token. Thank you for the feature.

@lidge-jun lidge-jun closed this Nov 18, 2026
lidge-jun added a commit that referenced this pull request Nov 19, 2026
Rebased onto dev at 0dc315b. The runtime keeps dev's post-#8930 publication
order and starts the scoped Hub lease refresh after PID and runtime-record
publication; restart, recycle, drain and signal shutdown stop it.

Co-authored-by: tachyon6 <songjunjun62754@gmail.com>
lidge-jun added a commit that referenced this pull request Nov 19, 2026
…#8925)

Rebased onto dev at 0dc315b. The runtime keeps dev's post-#8930 publication
order and starts the scoped Hub lease refresh after PID and runtime-record
publication; restart, recycle, drain and signal shutdown stop it.

Co-authored-by: tachyon6 <songjunjun62754@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants