@bitkyc08/opencodex 2.60.0 → 2.61.0

package/src/claude/intercept/runtime.ts

@@ -0,0 +1,98 @@
+import type { Server } from "bun";
+import type { OcxConfig } from "../../types";
+import { getConfigDir } from "../../config/paths";
+import { CLAUDE_INTERCEPT_HOSTS, startConnectProxy, type ConnectProxyHandle } from "./connect-proxy";
+import { startClaudeInterceptListener } from "./listener";
+import { claudeInterceptCaCertPath, ensureLocalInterceptCaForStartup, issueLocalInterceptLeaf } from "./local-ca";
+
+/**
+ * Lifecycle for the Claude intercept pair (CONNECT proxy + TLS listener).
+ *
+ * Started next to the public listener, torn down with it. The proxy port is derived from the
+ * public port unless configured, because Claude Code's `settings.json` must name a port that
+ * survives restarts; the TLS listener is ephemeral and only ever reached through the proxy.
+ */
+
+export const CLAUDE_INTERCEPT_PORT_OFFSET = 100;
+
+export function claudeInterceptEnabled(config: Pick<OcxConfig, "claudeCode" | "runtimeRole">): boolean {
+  if (config.runtimeRole === "client") return false;
+  if (config.claudeCode?.enabled === false) return false;
+  return config.claudeCode?.intercept?.enabled !== false;
+}
+
+export function claudeInterceptProxyPort(config: Pick<OcxConfig, "claudeCode">, publicPort: number): number {
+  const configured = config.claudeCode?.intercept?.port;
+  if (typeof configured === "number" && Number.isInteger(configured) && configured >= 1 && configured <= 65535) return configured;
+  return publicPort + CLAUDE_INTERCEPT_PORT_OFFSET;
+}
+
+export interface ClaudeInterceptState {
+  proxyPort: number;
+  caCertPath: string;
+}
+
+export interface ClaudeInterceptHandle<T = undefined> extends ClaudeInterceptState {
+  listener: Server<T>;
+  stop(): Promise<void>;
+}
+
+let activeState: ClaudeInterceptState | null = null;
+
+/** Live intercept endpoints, or `null` when the pair is not running in this process. */
+export function getClaudeInterceptState(): ClaudeInterceptState | null {
+  return activeState;
+}
+
+export interface StartClaudeInterceptOptions<T> {
+  config: OcxConfig;
+  /** Bound public port; the derived proxy port is offset from it. */
+  publicPort: number;
+  /**
+   * Port the operator asked for. `0` (ephemeral) gives the derived proxy port no stable value
+   * to write into `settings.json`, so intercept stays off unless `intercept.port` is explicit.
+   */
+  requestedPort?: number;
+  dispatch: (req: Request, server: Server<T>) => Promise<Response>;
+  maxRequestBodySize?: number;
+  configDir?: string;
+}
+
+/**
+ * Bind both halves. Resolves `null` when intercept is disabled. A bind failure is reported by
+ * rejecting; callers treat it as a degraded optional integration, never as a startup failure.
+ */
+export async function startClaudeIntercept<T>(options: StartClaudeInterceptOptions<T>): Promise<ClaudeInterceptHandle<T> | null> {
+  if (!claudeInterceptEnabled(options.config)) return null;
+  const explicitPort = typeof options.config.claudeCode?.intercept?.port === "number";
+  if (options.requestedPort === 0 && !explicitPort) return null;
+  const configDir = options.configDir ?? getConfigDir();
+  const ca = await ensureLocalInterceptCaForStartup(configDir);
+  const leaf = issueLocalInterceptLeaf(ca, CLAUDE_INTERCEPT_HOSTS);
+  const listener = startClaudeInterceptListener<T>({
+    leaf,
+    dispatch: options.dispatch,
+    upstreamBase: options.config.claudeCode?.anthropicBaseUrl,
+    ...(options.maxRequestBodySize !== undefined ? { maxRequestBodySize: options.maxRequestBodySize } : {}),
+  });
+  let proxy: ConnectProxyHandle;
+  try {
+    proxy = await startConnectProxy(claudeInterceptProxyPort(options.config, options.publicPort), {
+      interceptPort: listener.port!,
+    });
+  } catch (error) {
+    await listener.stop(true);
+    throw error;
+  }
+  const state: ClaudeInterceptState = { proxyPort: proxy.port, caCertPath: claudeInterceptCaCertPath(configDir) };
+  activeState = state;
+  return {
+    ...state,
+    listener,
+    stop: async () => {
+      if (activeState === state) activeState = null;
+      await proxy.close();
+      await listener.stop(true);
+    },
+  };
+}

package/src/claude/intercept/settings.ts

@@ -0,0 +1,189 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { claudeConfigDir } from "../auth-detect";
+
+/**
+ * Claude Code `settings.json` env block for intercept mode.
+ *
+ * Both the Claude Desktop Code tab and the standalone `claude` CLI read the user
+ * `~/.claude/settings.json` and export its `env` map into the process before any network
+ * call. Two keys make every Claude Code process route through the local CONNECT proxy while
+ * the app itself stays a first-party install:
+ *
+ *   env.HTTPS_PROXY         = http://127.0.0.1:<proxy port>
+ *   env.NODE_EXTRA_CA_CERTS = <configDir>/claude-intercept/ca.pem
+ *
+ * Ownership is tracked by value, never by a marker key. The CA path is the anchor: it lives
+ * under opencodex's own config directory, so only a block whose `NODE_EXTRA_CA_CERTS` names
+ * that file is treated as ours. A user's own proxy or CA setting is left alone.
+ */
+
+export const CLAUDE_INTERCEPT_MANAGED_ENV = ["HTTPS_PROXY", "NODE_EXTRA_CA_CERTS"] as const;
+export type ClaudeInterceptManagedEnv = typeof CLAUDE_INTERCEPT_MANAGED_ENV[number];
+
+export interface ClaudeInterceptEnv {
+  HTTPS_PROXY: string;
+  NODE_EXTRA_CA_CERTS: string;
+}
+
+export function claudeInterceptProxyUrl(port: number): string {
+  return `http://127.0.0.1:${port}`;
+}
+
+export function buildClaudeInterceptEnv(proxyPort: number, caCertPath: string): ClaudeInterceptEnv {
+  return { HTTPS_PROXY: claudeInterceptProxyUrl(proxyPort), NODE_EXTRA_CA_CERTS: caCertPath };
+}
+
+export type ClaudeInterceptSettingsState =
+  | { kind: "absent" }
+  | { kind: "applied"; env: ClaudeInterceptEnv }
+  | { kind: "stale"; env: Partial<ClaudeInterceptEnv> }
+  | { kind: "foreign"; env: Partial<Record<ClaudeInterceptManagedEnv, string>> }
+  | { kind: "unreadable"; path: string };
+
+type SettingsDoc = Record<string, unknown> & { env?: Record<string, unknown> };
+
+function settingsPath(configDir: string): string {
+  return join(configDir, "settings.json");
+}
+
+function readSettings(path: string): { doc: SettingsDoc } | { error: "missing" | "unreadable" } {
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch (error) { // no-excuse-ok: catch -- an absent settings file is the fresh-install state.
+    return { error: (error as NodeJS.ErrnoException).code === "ENOENT" ? "missing" : "unreadable" };
+  }
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return { error: "unreadable" };
+    return { doc: parsed as SettingsDoc };
+  } catch { // no-excuse-ok: catch -- a corrupt settings file must be reported, not overwritten.
+    return { error: "unreadable" };
+  }
+}
+
+function envRecord(doc: SettingsDoc): Record<string, unknown> {
+  return doc.env && typeof doc.env === "object" && !Array.isArray(doc.env) ? doc.env : {};
+}
+
+/** Loopback proxy URLs are the only shape opencodex ever writes. */
+export function isClaudeInterceptProxyUrl(value: unknown): value is string {
+  return typeof value === "string" && /^http:\/\/127\.0\.0\.1:\d{1,5}\/?$/.test(value.trim());
+}
+
+function isOwnedCaPath(value: unknown, ownedCaPath: string): value is string {
+  return typeof value === "string" && value.trim() === ownedCaPath;
+}
+
+/** Classify the current settings env against the values this router would write. */
+export function inspectClaudeInterceptSettings(
+  expected: ClaudeInterceptEnv,
+  configDir = claudeConfigDir(),
+): ClaudeInterceptSettingsState {
+  const path = settingsPath(configDir);
+  const read = readSettings(path);
+  if ("error" in read) return read.error === "missing" ? { kind: "absent" } : { kind: "unreadable", path };
+  const env = envRecord(read.doc);
+  const proxy = env.HTTPS_PROXY;
+  const ca = env.NODE_EXTRA_CA_CERTS;
+  if (proxy === undefined && ca === undefined) return { kind: "absent" };
+  if (proxy === expected.HTTPS_PROXY && ca === expected.NODE_EXTRA_CA_CERTS) return { kind: "applied", env: expected };
+  const caOurs = isOwnedCaPath(ca, expected.NODE_EXTRA_CA_CERTS);
+  const proxyOurs = proxy === undefined || isClaudeInterceptProxyUrl(proxy);
+  if (caOurs && proxyOurs) {
+    return {
+      kind: "stale",
+      env: {
+        ...(typeof proxy === "string" ? { HTTPS_PROXY: proxy } : {}),
+        ...(typeof ca === "string" ? { NODE_EXTRA_CA_CERTS: ca } : {}),
+      },
+    };
+  }
+  return {
+    kind: "foreign",
+    env: {
+      ...(typeof proxy === "string" ? { HTTPS_PROXY: proxy } : {}),
+      ...(typeof ca === "string" ? { NODE_EXTRA_CA_CERTS: ca } : {}),
+    },
+  };
+}
+
+function writeSettings(path: string, doc: SettingsDoc): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(doc, null, 2)}\n`, "utf8");
+  renameSync(tmp, path);
+}
+
+export type ClaudeInterceptSettingsWrite =
+  | { ok: true; changed: boolean; path: string }
+  | { ok: false; reason: "unreadable" | "foreign_env"; path: string };
+
+/** Capture only the managed keys. Rollback preserves unrelated edits and refuses
+ * to overwrite a newer proxy/CA choice made after this apply. */
+export function captureClaudeInterceptSettingsRollback(
+  expected: ClaudeInterceptEnv,
+  configDir = claudeConfigDir(),
+): () => boolean {
+  const path = settingsPath(configDir);
+  const before = readSettings(path);
+  if ("error" in before && before.error !== "missing") return () => false;
+  const previous = "doc" in before ? { ...envRecord(before.doc) } : {};
+  return () => {
+    try {
+      const current = readSettings(path);
+      if (!("doc" in current)) return false;
+      const env = envRecord(current.doc);
+      if (CLAUDE_INTERCEPT_MANAGED_ENV.some(key => env[key] !== expected[key])) return false;
+      for (const key of CLAUDE_INTERCEPT_MANAGED_ENV) {
+        if (previous[key] === undefined) delete env[key];
+        else env[key] = previous[key];
+      }
+      if (Object.keys(env).length === 0) delete current.doc.env;
+      else current.doc.env = env;
+      writeSettings(path, current.doc);
+      return true;
+    } catch { return false; }
+  };
+}
+
+/**
+ * Write the intercept env into `settings.json`. Refuses when a managed key already holds a
+ * value opencodex did not write (a user-configured corporate proxy, for instance).
+ */
+export function applyClaudeInterceptSettings(
+  env: ClaudeInterceptEnv,
+  configDir = claudeConfigDir(),
+): ClaudeInterceptSettingsWrite {
+  const path = settingsPath(configDir);
+  const state = inspectClaudeInterceptSettings(env, configDir);
+  if (state.kind === "unreadable") return { ok: false, reason: "unreadable", path };
+  if (state.kind === "foreign") return { ok: false, reason: "foreign_env", path };
+  if (state.kind === "applied") return { ok: true, changed: false, path };
+  const read = readSettings(path);
+  const doc: SettingsDoc = "doc" in read ? read.doc : {};
+  doc.env = { ...envRecord(doc), ...env };
+  writeSettings(path, doc);
+  return { ok: true, changed: true, path };
+}
+
+/** Remove the managed keys, but only the values opencodex owns. */
+export function removeClaudeInterceptSettings(
+  ownedCaPath: string,
+  configDir = claudeConfigDir(),
+): ClaudeInterceptSettingsWrite {
+  const path = settingsPath(configDir);
+  const read = readSettings(path);
+  if ("error" in read) {
+    return read.error === "missing" ? { ok: true, changed: false, path } : { ok: false, reason: "unreadable", path };
+  }
+  const env = envRecord(read.doc);
+  if (!isOwnedCaPath(env.NODE_EXTRA_CA_CERTS, ownedCaPath)) return { ok: true, changed: false, path };
+  delete env.NODE_EXTRA_CA_CERTS;
+  if (isClaudeInterceptProxyUrl(env.HTTPS_PROXY)) delete env.HTTPS_PROXY;
+  if (Object.keys(env).length === 0) delete read.doc.env;
+  else read.doc.env = env;
+  writeSettings(path, read.doc);
+  return { ok: true, changed: true, path };
+}

package/src/cli/access.ts

@@ -12,6 +12,8 @@ import {
 const USAGE = `Usage:
   ocx access key [list] [--json]
   ocx access key create [name] [--json]
+  ocx access key get <id-or-name> [--json]
+  ocx access key set <id-or-name> [--allow-provider <name>]... [--allow-model <id>]... [--clear] [--json]
   ocx access key rotate <id> [--json]
   ocx access key rotate commit <id> <rotation-id> [--json]
   ocx access key rotate abort <id> <rotation-id> [--json]
@@ -65,6 +67,51 @@ function formatKeyRows(payload: Record<string, unknown>, keys: Array<Record<stri
   return footer.length > 0 ? [...lines, "", ...footer] : lines;
 }
 
+/**
+ * Repeatable option values, in the order given.
+ *
+ * takeOption removes one occurrence, so a scope with several entries needs the
+ * loop: reading it once would silently keep only the first `--allow-model` and
+ * write a narrower scope than the operator typed.
+ */
+function takeAllOptions(args: string[], name: string): string[] {
+  const values: string[] = [];
+  for (;;) {
+    const value = takeOption(args, name);
+    if (value === undefined) break;
+    values.push(value);
+  }
+  return values;
+}
+
+/**
+ * Find a key by id or by name, without ever reading the secret.
+ *
+ * The management API keys every mutation by id, so a name has to be resolved
+ * here. An ambiguous name is refused rather than resolved to the first match:
+ * silently scoping one of two keys that share a name is the kind of mistake
+ * only discovered when the wrong client stops working.
+ */
+function findKeyRow(keys: Array<Record<string, unknown>>, selector: string): Record<string, unknown> {
+  const wanted = selector.trim().toLowerCase();
+  const byId = keys.filter(entry => String(entry.id ?? "").toLowerCase() === wanted);
+  if (byId.length === 1) return byId[0]!;
+  const byName = keys.filter(entry => String(entry.name ?? "").trim().toLowerCase() === wanted);
+  if (byName.length === 1) return byName[0]!;
+  if (byName.length > 1) throw new CliUsageError("key name " + selector + " is ambiguous; use the id", USAGE);
+  throw new CliUsageError("no API key matches " + selector, USAGE);
+}
+
+function scopeLines(entry: Record<string, unknown>): string[] {
+  const list = (value: unknown): string =>
+    Array.isArray(value) && value.length > 0 ? (value as string[]).join(", ") : "(any)";
+  return [
+    "API key " + String(entry.name ?? "") + " (" + String(entry.id ?? "") + ")",
+    "  allowed providers: " + list(entry.allowedProviders),
+    "  allowed models:    " + list(entry.allowedModels),
+  ];
+}
+
 async function key(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   const args = [...argv];
   const action = (args.shift() ?? "list").toLowerCase();
@@ -90,6 +137,46 @@ async function key(argv: string[], deps: RuntimeApiDeps): Promise<void> {
     ]);
     return;
   }
+  if (action === "get") {
+    const selector = args.shift();
+    if (!selector) throw new CliUsageError("key id or name is required", USAGE);
+    rejectArgs(args, USAGE);
+    const result = await runtimeRequest<Record<string, unknown>>("/api/keys", {}, deps);
+    const entry = findKeyRow(Array.isArray(result.keys) ? result.keys as Array<Record<string, unknown>> : [], selector);
+    // The list response carries the masked prefix and never the secret, so the
+    // row is safe to print as-is under --json.
+    printData(entry, wantsJson, scopeLines(entry));
+    return;
+  }
+  if (action === "set") {
+    const selector = args.shift();
+    if (!selector) throw new CliUsageError("key id or name is required", USAGE);
+    const clear = takeFlag(args, "--clear");
+    const providers = takeAllOptions(args, "--allow-provider");
+    const models = takeAllOptions(args, "--allow-model");
+    rejectArgs(args, USAGE);
+    if (!clear && providers.length === 0 && models.length === 0) {
+      throw new CliUsageError("set requires --allow-provider, --allow-model, or --clear", USAGE);
+    }
+    const listed = await runtimeRequest<Record<string, unknown>>("/api/keys", {}, deps);
+    const target = findKeyRow(Array.isArray(listed.keys) ? listed.keys as Array<Record<string, unknown>> : [], selector);
+    // A set REPLACES the named dimension rather than appending to it, and
+    // --clear removes both. Naming one dimension leaves the other alone, so
+    // narrowing providers cannot accidentally widen models.
+    const body: Record<string, unknown> = { id: target.id };
+    if (clear) {
+      body.allowedProviders = null;
+      body.allowedModels = null;
+    }
+    if (providers.length > 0) body.allowedProviders = providers;
+    if (models.length > 0) body.allowedModels = models;
+    const result = await runtimeRequest<Record<string, unknown>>("/api/keys", {
+      method: "PATCH",
+      body: JSON.stringify(body),
+    }, deps);
+    printData(result, wantsJson, scopeLines(result));
+    return;
+  }
   if (action === "rotate") {
     const operation = args[0] === "commit" || args[0] === "abort" ? args.shift()! : "start";
     const id = args.shift();

package/src/cli/account-auth.ts

@@ -2,6 +2,7 @@ import { writeSync } from "node:fs";
 import { modelSelectionGuidance, modelSelectionNextSteps } from "./model-selection-guidance";
 import { warnIfCodexCatalogRefreshPending } from "./account-catalog-refresh";
 import { isCodexResetCreditOperationId } from "../codex/reset-credit-recovery";
+import { BROWSER_LAUNCH_FAILED_NOTICE } from "../lib/browser-launch-notice";
 import {
   CliUsageError,
   printData,
@@ -69,8 +70,25 @@ interface LoginStart {
   flowId?: string;
   instructions?: string;
   deviceCode?: string;
+  /** Whether the host actually opened a browser. Absent from older proxies. */
+  browserLaunch?: "started" | "failed" | "skipped";
 }
 
+/**
+ * Said only when the host could not open a browser (#5261).
+ *
+ * Without it, a failed launch is indistinguishable from a successful one: the URL is printed
+ * either way, so the user waits at a terminal that looks like it is working. Names the fixed
+ * callback port because that is the part people cannot guess — ChatGPT supplies the redirect
+ * URI, so the flow cannot move to a free port, and `--device` is the way around it.
+ *
+ * Extends the shared notice rather than repeating it: only the second line is specific to this
+ * flow, and the first is the sentence every other login prints for the same failure.
+ */
+export const BROWSER_LAUNCH_FAILED_HINT =
+  BROWSER_LAUNCH_FAILED_NOTICE
+  + "\n   If nothing on this machine can reach http://localhost:1455, rerun with --device instead.";
+
 /** `-` means "read it from stdin", the documented way to pass a code silently. */
 const STDIN_SENTINEL = "-";
 
@@ -145,6 +163,7 @@ async function login(argv: string[], deps: RuntimeApiDeps): Promise<void> {
         start.url ? `Open this URL to sign in:\n${start.url}` : "",
         start.deviceCode ? `Device code: ${start.deviceCode}` : "",
         start.instructions ?? "",
+        start.browserLaunch === "failed" ? BROWSER_LAUNCH_FAILED_HINT : "",
         start.flowId ? `Flow: ${start.flowId}` : "",
       ].filter(line => line !== "").join("\n");
       if (block) writeStdoutFully(`${block}\n`);

package/src/cli/capabilities.ts

@@ -211,6 +211,21 @@ export const CAPABILITIES: readonly Capability[] = [
     json: "envelope",
     details: ["Reads /healthz plus local config; drives no management API route."],
   },
+  {
+    command: ["resolve"],
+    summary: "One JSON document naming the config home, the effective port, and the identity-checked proxy liveness verdict.",
+    // No management route, same split as status: discovery is the identity-checked
+    // /healthz probe inside findLiveProxy plus local config and the home from
+    // src/config/paths.ts.
+    routes: [],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit the resolve document as JSON (the shell contract)." }],
+    mutates: false,
+    json: "envelope",
+    details: [
+      "Exit 0 carries a trustworthy verdict (live or proven absent); exit 1 means the CLI could not resolve and a caller must refuse to guess — unknown liveness never reads as absent.",
+      "Built for embedding shells (desktop app): the liveness budgets stay owned by src/server/proxy-liveness.ts.",
+    ],
+  },
   {
     command: ["hub", "invite"],
     summary: "Mint a single-use pairing code on a hub and print the exact `ocx connect` line for one more machine.",
@@ -314,6 +329,22 @@ export const CAPABILITIES: readonly Capability[] = [
       "Headless services usually have no unlocked keychain session; prefer ${ENV_VAR} references there.",
     ],
   },
+  {
+    command: ["companion"],
+    summary: "Inspect and configure menu-bar and widget companion usage settings.",
+    routes: [
+      { method: "GET", path: "/api/companion/settings" },
+      { method: "GET", path: "/api/usage/timeline" },
+      { method: "PUT", path: "/api/companion/settings" },
+    ],
+    flags: [{ name: "--json", value: "boolean", summary: "Emit companion settings as JSON." }],
+    mutates: true,
+    json: "payload",
+    details: [
+      "`show` (the default) reads settings; `set key=value ...` updates selected settings; `reset` restores defaults.",
+      "Values accepted by `set` are parsed as JSON when valid, so booleans, numbers, arrays, objects, and null can be passed directly.",
+    ],
+  },
   {
     command: ["account", "history"],
     summary: "Cached quota observations for one stored Codex pool account.",