fix(opencode): read /api/models with the admin token, not the admission key

docs-site/src/content/docs/guides/opencode.md

@@ -175,6 +175,22 @@ see [Remote access](/reference/configuration/#remote-access). This admission key
 own, and is unrelated to the upstream provider keys configured under
 [Providers](/guides/providers/).
 
+## How the catalogue is read
+
+The launcher's own catalogue read is a management request, not a data-plane one. `ocx opencode`
+fetches `GET /api/models` with the configured management credential (`OPENCODEX_ADMIN_AUTH_TOKEN`,
+or the `admin-api-token` file in `~/.opencodex`) and refuses to send it anywhere but a loopback
+`/api/*` origin, over a transport that ignores `HTTP(S)_PROXY` and never follows a redirect. When the
+proxy answered the launcher's identity probe itself, the read uses a single-use, process-bound
+capability instead, so no reusable credential is sent at all.
+
+If no management credential is configured, the launcher falls back to the admission key above. A
+hardened proxy refuses that key on `/api/*` with `401 opencodex admin token required`, so set
+`OPENCODEX_ADMIN_AUTH_TOKEN` (or the token file) on such a host.
+
+A non-loopback `hostname` is refused for this read. Bind the proxy to loopback, or enable a hub
+management ingress, so this machine has a local `/api/*` address.
+
 ## Reverting
 
 Nothing to undo — no generated config file is written under `~/.opencodex`. Run plain

src/cli/opencode.ts

@@ -19,7 +19,7 @@ import { spawn } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
-import { loadConfig } from "../config";
+import { getConfigDir, loadConfig } from "../config";
 import {
   OPENCODE_API_KEY_ENV,
   OPENCODE_CONFIG_SCHEMA,
@@ -40,9 +40,15 @@ import type {
   OpencodeV2ProviderBlock,
 } from "../clients/config-export";
 import { filterCatalogVisibleModels, visibleNativeSlugs } from "../codex/catalog";
+import { isLoopbackHostname } from "../codex/loopback-target";
+import { configuredAdminToken } from "../lib/admin-secrets";
+import { localManagementOrigin } from "../lib/local-destinations";
+import { LOCAL_MANAGEMENT_READ_PATHS } from "../lib/local-management-capability";
 import { commandInvocation } from "../lib/win-exec";
 import { loadServiceTokenFromFile, serviceApiTokenFilePath } from "../lib/service-secrets";
 import { providerCodexAccountMode } from "../providers/registry";
+import { directLocalHttpFetch } from "../server/direct-local-http";
+import { fetchBoundLocalManagementRead } from "../server/local-management-read-client";
 import { findLiveProxy, probeHostname, type LiveProxy } from "../server/proxy-liveness";
 import type { OcxConfig } from "../types";
 import { withProcessRuntimeProvenance } from "../lib/bun-runtime";
@@ -306,16 +312,95 @@ function opencodeBlocks(
 /** Default deadline for authenticated GET /api/models during `ocx opencode` launch. */
 export const OPENCODE_PROXY_MODELS_TIMEOUT_MS = 8_000;
 
-/** Fetch the live model catalog from a running proxy's management API. */
+/**
+ * Fetch the live model catalog from a running proxy management API.
+ *
+ * `GET /api/models` sits behind `requireManagementAuth`, so `managementToken` has to be a
+ * management credential. It is deliberately NOT the data-plane admission key `buildOpencodeEnv`
+ * hands the child process, and two boundaries keep it local:
+ *
+ * 1. Destination — the resolved origin must be loopback. `probeHostname` already normalises every
+ *    wildcard spelling to 127.0.0.1 and brackets bare IPv6 literals, so the supported
+ *    wildcard/IPv4/IPv6 listener cases keep working, while a non-loopback bind is refused before
+ *    any token-bearing request exists.
+ * 2. Transport — `directLocalHttpFetch` never consults proxy environment variables, never follows
+ *    a redirect, and drops proxy headers. A global `fetch` can do all three, so the management
+ *    credential does not travel through one.
+ *
+ * When the live proxy is process-attested (`live.source === "runtime"`) the read goes through the
+ * single-use local management capability instead, so no reusable credential leaves this process at
+ * all. A proxy that does not recognise that capability yet (an older build) falls back to the
+ * loopback token read below.
+ */
+export interface OpencodeProxyModelsDeps {
+  fetchImpl?: typeof fetch;
+  timeoutMs?: number;
+  /**
+   * `/api/*` origin for this read, normally `localManagementOrigin(config, live.port)`, which
+   * prefers a hub loopback management ingress. Defaults to the identity-probed proxy record.
+   */
+  origin?: string;
+  /** Capability-read seam; defaults to the real single-use capability client. */
+  boundRead?: typeof fetchBoundLocalManagementRead;
+}
+
+/** True when `origin` is a plain-HTTP loopback destination this process may carry a token to. */
+export function isLocalManagementOrigin(origin: string): boolean {
+  try {
+    const url = new URL(origin);
+    return url.protocol === "http:" && !url.username && !url.password && isLoopbackHostname(url.hostname);
+  } catch {
+    return false;
+  }
+}
+
+function opencodeProxyModelRows(response: Response, text: string): OpencodeProxyModelRow[] {
+  let body: unknown = null;
+  if (text) {
+    try { body = JSON.parse(text); }
+    catch { body = text; }
+  }
+  if (!response.ok) {
+    const message = body && typeof body === "object" && typeof (body as Record<string, unknown>).error === "string"
+      ? (body as Record<string, string>).error
+      : `Management request failed (${response.status})`;
+    throw new Error(message);
+  }
+  if (!Array.isArray(body)) {
+    throw new Error("Management API returned an unexpected /api/models payload.");
+  }
+  return body as OpencodeProxyModelRow[];
+}
+
 export async function fetchOpencodeProxyModels(
   live: LiveProxy,
-  apiKey: string,
-  deps: { fetchImpl?: typeof fetch; timeoutMs?: number } = {},
+  managementToken: string,
+  deps: OpencodeProxyModelsDeps = {},
 ): Promise<OpencodeProxyModelRow[]> {
-  const baseUrl = `http://${probeHostname(live.hostname)}:${live.port}`;
-  const fetchImpl = deps.fetchImpl ?? fetch;
+  const attestedOrigin = `http://${probeHostname(live.hostname)}:${live.port}`;
+  const origin = deps.origin ?? attestedOrigin;
+  if (!isLocalManagementOrigin(origin)) {
+    throw new Error(
+      `Refusing to send the opencodex management credential to ${origin}: it is not a loopback address. `
+      + "Bind the proxy to loopback, or enable the hub management ingress, so this host has a local /api/* address.",
+    );
+  }
+  const target = new URL(origin);
+  // The capability is bound to the attested pid AND to the port the request arrives on, so it can
+  // only be presented to the proxy listener that minted it, never to a separate management ingress.
+  if (live.source === "runtime"
+    && target.port === String(live.port)
+    && target.hostname === new URL(attestedOrigin).hostname) {
+    const read = await (deps.boundRead ?? fetchBoundLocalManagementRead)(
+      live,
+      LOCAL_MANAGEMENT_READ_PATHS.models,
+      { timeoutMs: deps.timeoutMs ?? OPENCODE_PROXY_MODELS_TIMEOUT_MS },
+    );
+    if (read.kind === "response") return opencodeProxyModelRows(read.response, await read.response.text());
+  }
+  const fetchImpl = deps.fetchImpl ?? directLocalHttpFetch;
   const headers = new Headers({ Accept: "application/json" });
-  const token = apiKey.trim();
+  const token = managementToken.trim();
   if (token) headers.set("X-OpenCodex-API-Key", token);
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), deps.timeoutMs ?? OPENCODE_PROXY_MODELS_TIMEOUT_MS);
@@ -335,7 +420,7 @@ export async function fetchOpencodeProxyModels(
   let text: string;
   try {
     response = await Promise.race([
-      fetchImpl(`${baseUrl}/api/models`, {
+      fetchImpl(`${target.origin}/api/models`, {
         headers,
         signal: controller.signal,
       }),
@@ -352,21 +437,7 @@ export async function fetchOpencodeProxyModels(
   } finally {
     clearTimeout(timeout);
   }
-  let body: unknown = null;
-  if (text) {
-    try { body = JSON.parse(text); }
-    catch { body = text; }
-  }
-  if (!response.ok) {
-    const message = body && typeof body === "object" && typeof (body as Record<string, unknown>).error === "string"
-      ? (body as Record<string, string>).error
-      : `Management request failed (${response.status})`;
-    throw new Error(message);
-  }
-  if (!Array.isArray(body)) {
-    throw new Error("Management API returned an unexpected /api/models payload.");
-  }
-  return body as OpencodeProxyModelRow[];
+  return opencodeProxyModelRows(response, text);
 }
 
 /**
@@ -602,6 +673,26 @@ export function opencodeApiKey(config: OcxConfig, env: OpencodeLaunchEnv = proce
   return config.apiKeys?.[0]?.key || "ocx";
 }
 
+/**
+ * Credential for the launcher's `GET /api/models` read.
+ *
+ * That route is a management route, so `requireManagementAuth` only admits the admin credential —
+ * the data-plane admission key {@link opencodeApiKey} returns for the child process is refused there
+ * with `opencodex admin token required`. Prefer the configured admin token, the same credential every
+ * other headless management caller sends (`runningProxyUpdateHeaders`), and keep the admission key as
+ * the fallback for a host that has no admin token configured.
+ *
+ * The destination and transport are constrained by {@link fetchOpencodeProxyModels}: the credential
+ * only ever reaches a loopback `/api/*` origin, and an attested proxy answers the same read over a
+ * single-use capability that needs no reusable credential at all.
+ */
+export function opencodeManagementToken(config: OcxConfig, env: OpencodeLaunchEnv = process.env): string {
+  // Name the directory instead of passing `undefined`: an explicit `env` may describe a different
+  // OPENCODEX_HOME than this process, and the admin token file is read from that directory.
+  const configDir = env.OPENCODEX_HOME?.trim() || getConfigDir();
+  return configuredAdminToken(configDir, env) ?? opencodeApiKey(config, env);
+}
+
 async function ensureProxyForOpencode(config: OcxConfig): Promise<LiveProxy | null> {
   const live = await findLiveProxy();
   if (live) return live;
@@ -650,9 +741,13 @@ export async function cmdOpencode(args: string[]): Promise<number> {
   }
 
   const apiKey = opencodeApiKey(startupConfig);
+  const managementToken = opencodeManagementToken(startupConfig);
   let proxyModels: OpencodeProxyModelRow[];
   try {
-    proxyModels = await fetchOpencodeProxyModels(live, apiKey);
+    proxyModels = await fetchOpencodeProxyModels(live, managementToken, {
+      // A hub reaches its own management API through the loopback ingress, not the public bind.
+      origin: localManagementOrigin(startupConfig, live.port),
+    });
   } catch (error) {
     const reason = error instanceof Error ? error.message : String(error);
     console.error(`❌ Could not fetch the model catalog from the proxy: ${reason}`);

src/lib/local-management-capability.ts

@@ -10,6 +10,11 @@ export const LOCAL_MANAGEMENT_CAPABILITY_TTL_MS = 10_000;
 export const LOCAL_MANAGEMENT_READ_PATHS = {
   codexAccounts: "/api/codex-auth/accounts",
   systemMemory: "/api/system/memory",
+  // `ocx opencode` needs the same process-attested read the CLI already performs for memory and
+  // Codex accounts: the launcher cannot start without the catalog, and the alternative is a
+  // reusable admin credential on the wire. The route is registered `mutates: false` in
+  // `src/server/management/route-registry.ts`, which is what makes it eligible for a read grant.
+  models: "/api/models",
 } as const;
 
 export type LocalManagementReadPath =
@@ -32,7 +37,8 @@ export function parseExpectedLocalManagementPid(value: string | null): ExpectedL
 
 function isLocalManagementReadPath(path: string): path is LocalManagementReadPath {
   return path === LOCAL_MANAGEMENT_READ_PATHS.codexAccounts
-    || path === LOCAL_MANAGEMENT_READ_PATHS.systemMemory;
+    || path === LOCAL_MANAGEMENT_READ_PATHS.systemMemory
+    || path === LOCAL_MANAGEMENT_READ_PATHS.models;
 }
 
 function localReadCapabilityPayload(

structure/clients/claude-desktop.md

@@ -18,6 +18,13 @@ writes the resulting local Desktop configuration. No admin token, hub-profile up
 alias regeneration is part of this flow. Unsupported old hubs, invalid snapshots and unavailable
 Desktop models fail apply without a local-catalog or loopback fallback.
 
+Local launchers read hub management state only through an authenticated, loopback-only origin.
+`src/cli/opencode.ts` applies that rule to its `GET /api/models` catalogue read: the management
+credential is refused a non-loopback destination before any request is built, the transport is the
+direct local one (no proxy environment variables and no redirects), and the admission key handed to
+the child process carries no management authority. An attested proxy answers that read over a
+single-use local read capability instead of the credential itself.
+
 Date-shaped Desktop IDs can overlap genuine native model IDs. When available discovery and
 mapping evidence cannot resolve one, Messages and count-tokens return HTTP 503 with the fixed
 `desktop_model_mapping_unavailable` error rather than classifying it as invalid. Unknown legacy hash aliases

structure/config.md

@@ -50,6 +50,7 @@ matters for maintainers is which groups exist and who resolves them:
 | Retained state | `appOwnedMemoryBudgetMb` | Process-wide eviction target for app-owned logs, caches, blobs, and continuation payloads. Default 256 MiB, valid 64..4096; pinned state may temporarily exceed the target, but every pin-capable store has a finite local cap and their documented aggregate stays below `APP_OWNED_WORST_CASE_PINNED_BYTES` (512 MiB). Neither value caps RSS or native runtime memory. |
 | Transport | stream mode, timeouts, proxy settings, `websockets`, `emptyCompletionRetry` | `streamMode` persists in config.json; Windows services need a persisted input, and macOS uses it for explicit eager-relay opt-in. Empty-completion replay is an explicit top-level opt-in because its second upstream request may be billable. |
 | Credentials | `apiKeys` | Data-plane only; never admitted to `/api/*`. |
+| Management credential | `OPENCODEX_ADMIN_AUTH_TOKEN`, `admin-api-token` file | Resolved by `configuredAdminToken`. `src/cli/opencode.ts` presents it on `GET /api/models`; a non-loopback destination is refused before that request is built. |
 | Lifecycle | `codexAutoStart`, shim/start behavior, resume-history sync, storage cleanup | Startup safety reads these; see [`gui-and-management-api.md`](gui-and-management-api.md). |
 
 Env values are resolved through `src/config.ts`, so a config value naming an env var never persists

structure/ops/docs-and-release.md

@@ -8,6 +8,12 @@ served at the site root, with Korean under `/ko`, Simplified Chinese under `/zh-
 Manual navigation is defined in `docs-site/astro.config.mjs`. When adding a public page, update the
 sidebar and either add localized copies or intentionally accept Starlight fallback behavior.
 
+The `ocx opencode` guide (`docs-site/src/content/docs/guides/opencode.md`) documents the launcher
+management-read contract: the management credential versus the child admission key, the loopback-only
+destination, and the direct local transport. `src/cli/opencode.ts` owns that behavior, so changing
+which credential the launcher sends on `/api/*` updates that guide together with `runtime.md`,
+`config.md`, and `clients/claude-desktop.md` — the other documents assigned to `src/cli/`.
+
 ## GitHub Pages
 
 `.github/workflows/deploy-docs.yml` publishes the docs to:

structure/runtime.md

@@ -191,6 +191,17 @@ not an authentication or entitlement decision.
 
 Routed Responses continuations whose local replay state is missing resolve their recovery decision from the selected wire protocol, not the model name; the contract lives in [Responses transport](transports/responses.md).
 
+`src/cli/opencode.ts` reads its model catalogue from the authenticated management route
+`GET /api/models`, so it presents the management credential (`configuredAdminToken`:
+`OPENCODEX_ADMIN_AUTH_TOKEN`, then the hardened `admin-api-token` file) and keeps the data-plane
+admission key for the child process environment alone. The read is loopback-only — the resolved
+`/api/*` origin must be a loopback address, with `probeHostname` normalizing the wildcard and IPv6
+spellings — and it travels over `directLocalHttpFetch`, which ignores proxy environment variables
+and never follows a redirect. A process-attested proxy answers the same read over the single-use
+local management capability for `/api/models` (`src/lib/local-management-capability.ts`) rather than
+a reusable credential; a proxy without that capability falls back to the loopback token read. See
+[Config surface](config.md).
+
 ## Remote Hub hardening ownership
 
 `src/remote/protocol.ts` owns pure interval/feature negotiation. `src/remote/hub-state.ts` owns the `GET|HEAD /v1/hub-state` contract, its caps, and the parser both sides share. `src/client/hub-client.ts` owns bounded, schema-validated remote catalog consumption, hub-state reads, and key-id probes; `src/client/hub-state.ts` owns the resolution and the owner-stamped 0600 cache, and a failed read reports "unavailable" rather than degrading to the client's own local provider and login state. `src/client/hub-relay.ts` is a fixed-authority management relay with URL, header, body, redirect, and stream bounds. The public data listener remains the direct client→hub path; the loopback management ingress never serves data-plane routes.