@remodex/rmx 1.0.2

package/src/server/management-api.ts

@@ -0,0 +1,269 @@
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import type { CatalogModel } from "../codex/catalog";
+import { catalogModelSlug, invalidateCodexModelsCache, nativeModelRows, uniqueCatalogModelsForPublicList } from "../codex/catalog";
+import {
+  DEFAULT_SUBAGENT_MODELS,
+  codexAutoStartEnabled,
+  hasOwnProvider,
+  isValidProviderName,
+  multiAgentGuidanceEnabled,
+  providerBaseUrlConfigError,
+  providerHeadersConfigError,
+  saveConfigPreservingClaudeCode,
+} from "../config";
+import {
+  clearLoginState,
+  getLoginStatus,
+  isPublicOAuthProvider,
+  listOAuthProviders,
+  startLoginFlow,
+  submitManualLoginCode,
+  upsertOAuthProvider,
+} from "../oauth";
+import { OAuthMutationBusyError, removeCredential } from "../oauth/store";
+import { providerDestinationResolvedError } from "../lib/destination-policy";
+import { enrichProviderFromCatalog, listKeyLoginProviders } from "../oauth/key-providers";
+import { deriveProviderPresets } from "../providers/derive";
+import { providerCodexAccountMode } from "../providers/registry";
+import { routedSlug, slugEquals } from "../providers/slug-codec";
+import { clearProviderQuotaCache, fetchProviderQuotaReports } from "../providers/quota";
+import { isCanonicalOpenAiForwardProvider } from "../providers/openai-tiers";
+import { clearThreadAccountMap } from "../codex/routing";
+import { primeCodexPoolQuotas } from "../codex/auth-api";
+import { DEFAULT_PROVIDER_CONTEXT_CAP, globalContextCapValue, providerContextCap, providerContextCaps, setAllProviderContextCaps, setGlobalContextCapValue, setProviderContextCap } from "../providers/context-cap";
+import { resolveCodexHomeDir } from "../codex/home";
+import { readUsageEntries } from "../usage/log";
+import { getUsageDebugLogEntries } from "../usage/debug";
+import { parseRange, parseUsageSurface, summarizeUsage } from "../usage/summary";
+import { stripCodexRuntimeProviderFields } from "../codex/auth-context";
+import { getProviderRegistryEntry } from "../providers/registry";
+import { getDebugLogEntries } from "../lib/debug-log-buffer";
+import { getInjectionDebugLogEntries } from "../lib/injection-debug-log";
+import {
+  clearDebugSettings,
+  clearDebugSetting,
+  getDebugSettings,
+  setDebugSettings,
+  type DebugFlag,
+} from "../lib/debug-settings";
+import type { OcxClaudeCodeConfig, OcxClaudeDesktopProfile, OcxConfig, OcxCustomModel, OcxProviderConfig } from "../types";
+import type { DesktopProfileModel } from "../claude/desktop-profile";
+import { acquireTemporaryDrain, beginShutdownDrain, drainAndShutdown } from "./lifecycle";
+import { prepareProxyStop } from "./proxy-stop";
+import { filterRequestLogs, getRequestLogEntries, type RequestLogEntry } from "./request-log";
+import { estimateComboCost, estimateRequestCost, normalizeCostTokens, tokensPerSecond } from "../usage/cost";
+import type { PersistedUsageAttempt } from "../usage/log";
+import { isAllowedManagementOrigin, jsonResponse, providerManagementConfigError, publicProviderBaseUrl, safeConfigDTO } from "./auth-cors";
+import { applySystemEnvToggle } from "./system-env";
+
+import type { ManagementApiDeps } from "./management/context";
+import { handleConfigRoutes } from "./management/config-routes";
+import { handleLogsUsageRoutes } from "./management/logs-usage-routes";
+import { handleRequestHistoryRoutes } from "./management/request-history-routes";
+import { handleRoutingAnalyticsRoutes } from "./management/routing-analytics-routes";
+import { handleRoutingProfileRoutes } from "./management/routing-profile-routes";
+import { handleProviderRoutes } from "./management/provider-routes";
+import { handleModelRoutes } from "./management/model-routes";
+import { handleAgentSettingsRoutes } from "./management/agent-settings-routes";
+import { handleOauthAccountRoutes } from "./management/oauth-account-routes";
+import { handleComboRoutes } from "./management/combo-routes";
+import { handleSystemRoutes } from "./management/system-routes";
+import { handleSidebarRoutes } from "./management/sidebar-routes";
+import { handleIntegrationRoutes } from "./management/integration-routes";
+import { handleNativeIntegrationRoutes } from "./management/native-integration-routes";
+import { handleAndroidRemoteRoutes } from "./management/android-remote-routes";
+import type { ManagementContext } from "./management/context";
+import type { ManagementPrincipal } from "./management-auth";
+export type { ManagementApiDeps } from "./management/context";
+import { fetchAllModels } from "./management/shared";
+import { CatalogGatherBusyError } from "../codex/catalog/provider-fetch";
+import type { CatalogDisposition, ConvergeCodex } from "../codex/convergence-types";
+import { normalizeCatalogDisposition } from "../codex/catalog-refresh-status";
+import { managementBodyTooLargeResponse } from "./management/body";
+
+// installed npm version instead of a stale hardcode.
+export const VERSION = (() => {
+  try {
+    return JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version as string;
+  } catch {
+    return "0.0.0";
+  }
+})();
+
+const managementConvergenceBindings = new WeakMap<object, Readonly<{
+  factory: (config: Readonly<OcxConfig>) => ConvergeCodex;
+  converge: ConvergeCodex;
+}>>();
+
+export async function handleManagementAPI(
+  req: Request,
+  url: URL,
+  config: OcxConfig,
+  deps: ManagementApiDeps = {},
+  principal?: ManagementPrincipal,
+): Promise<Response | null> {
+  if (!isAllowedManagementOrigin(req, config)) {
+    return jsonResponse({ error: "cross-origin request blocked" }, 403, req, config);
+  }
+  // Management bodies are small JSON (provider names, key ids, settings). Reject oversized
+  // payloads before any handler buffers them — the data plane has its own decompression cap.
+  if (req.method === "POST" || req.method === "PUT" || req.method === "PATCH") {
+    const contentLength = Number(req.headers.get("content-length") ?? "0");
+    if (Number.isFinite(contentLength) && contentLength > 2 * 1024 * 1024) {
+      return jsonResponse({ error: "request body too large" }, 413, req, config);
+    }
+  }
+  async function convergeCodexCatalog(): Promise<CatalogDisposition> {
+    let convergenceInvoked = false;
+    let managementConvergeCodex: ConvergeCodex | undefined;
+    try {
+      if (!managementConvergeCodex) {
+        const factory = deps.createManagementConvergeCodex
+          ?? (await import("../codex/management-convergence")).createManagementConvergeCodex;
+        if (typeof factory !== "function") throw new TypeError("Catalog convergence factory is unavailable.");
+        let binding = managementConvergenceBindings.get(config);
+        if (!binding || binding.factory !== factory) {
+          const created = factory(config);
+          if (typeof created !== "function") throw new TypeError("Catalog convergence factory returned no function.");
+          binding = { factory, converge: created };
+          managementConvergenceBindings.set(config, binding);
+        }
+        managementConvergeCodex = binding.converge;
+      }
+      const { createCatalogConvergeRequest } = await import("../codex/catalog-admission");
+      convergenceInvoked = true;
+      const outcome = await managementConvergeCodex(createCatalogConvergeRequest({ deadlineMs: 1_000 }));
+      const catalogRefresh = outcome?.kind === "catalog-only"
+        ? normalizeCatalogDisposition(outcome.catalogRefresh)
+        : null;
+      if (!catalogRefresh) {
+        throw new TypeError("Catalog convergence returned an invalid outcome.");
+      }
+      return catalogRefresh;
+    } catch {
+      return {
+        status: "failed",
+        reason: "disk",
+        phase: convergenceInvoked ? "commit" : "gather",
+        retryable: false,
+        partialWrite: convergenceInvoked,
+      };
+    }
+  }
+
+  async function syncClaudeAgentDefsBestEffort(): Promise<void> {
+    try {
+      const { injectClaudeAgentDefs } = await import("../claude/agents-inject");
+      if (config.claudeCode?.enabled === false || config.claudeCode?.injectAgents === false) {
+        injectClaudeAgentDefs(config, {});
+        return;
+      }
+      try {
+        const [models, { buildClaudeContextWindows }, { visibleNativeSlugs }] = await Promise.all([
+          fetchAllModels(config),
+          import("../claude/context-windows"),
+          import("../codex/catalog"),
+        ]);
+        injectClaudeAgentDefs(config, buildClaudeContextWindows([...visibleNativeSlugs(config)], models));
+      } catch {
+        // Keep routes available through a provider-discovery blip. A later
+        // launch-time sync restores any context markers missing from this pass.
+        injectClaudeAgentDefs(config, {});
+      }
+    } catch { /* best-effort */ }
+  }
+  const ctx: ManagementContext = { req, url, config, deps, principal, convergeCodexCatalog, syncClaudeAgentDefsBestEffort };
+  let routed: Response | null;
+  try {
+    routed = (await handleConfigRoutes(ctx))
+    ??     (await handleLogsUsageRoutes(ctx))
+    ??     (await handleRequestHistoryRoutes(ctx))
+    ??     (await handleRoutingAnalyticsRoutes(ctx))
+    ??     (await handleRoutingProfileRoutes(ctx))
+    ??     (await handleProviderRoutes(ctx))
+    ??     (await handleModelRoutes(ctx))
+    ??     (await handleIntegrationRoutes(ctx))
+    ??     (await handleNativeIntegrationRoutes(ctx))
+    ??     (await handleAndroidRemoteRoutes(ctx))
+    ??     (await handleAgentSettingsRoutes(ctx))
+    ??     (await handleOauthAccountRoutes(ctx))
+    ??     (await handleComboRoutes(ctx))
+    ??     (await handleSystemRoutes(ctx))
+      ?? (await handleSidebarRoutes(ctx));
+  } catch (error) {
+    const tooLarge = managementBodyTooLargeResponse(error, req, config);
+    if (tooLarge) return tooLarge;
+    if (error instanceof OAuthMutationBusyError) {
+      return new Response(JSON.stringify({ error: { type: "server_error", code: "oauth_mutation_busy", message: error.message } }), {
+        status: 503,
+        headers: { "content-type": "application/json", "Retry-After": "1" },
+      });
+    }
+    if (!(error instanceof CatalogGatherBusyError)) throw error;
+    return new Response(JSON.stringify({ error: { type: "server_error", code: "catalog_busy", message: error.message } }), {
+      status: 503,
+      headers: { "content-type": "application/json", "Retry-After": "1" },
+    });
+  }
+  if (routed) return routed;
+
+  if (url.pathname === "/api/stop" && req.method === "POST") {
+    const { restoreNativeCodexAsync } = await import("../codex/inject");
+    const {
+      assertServiceEnvironmentMatchesInstall,
+      isServiceInstalled,
+      stopServiceIfInstalled,
+    } = await import("../service");
+    const { stripGrokConfig } = await import("../grok/inject");
+    const prepared = await prepareProxyStop({
+      acquireDrain: () => acquireTemporaryDrain("proxy-stop"),
+      assertServiceOwnership: assertServiceEnvironmentMatchesInstall,
+      restoreNativeCodex: restoreNativeCodexAsync,
+      restoreGrok: stripGrokConfig,
+      serviceInstalled: isServiceInstalled,
+      stopService: stopServiceIfInstalled,
+      beginShutdown: () => { beginShutdownDrain(); },
+    });
+    if (!prepared.ok) {
+      return jsonResponse({ success: false, message: prepared.message }, prepared.status, req, config);
+    }
+
+    setTimeout(async () => {
+      await drainAndShutdown(undefined, config.shutdownTimeoutMs ?? 5000);
+      process.exit(0);
+    }, 200);
+    return jsonResponse({ success: true, message: prepared.message }, 200, req, config);
+  }
+
+  if (url.pathname.startsWith("/api/native-main-profiles")) {
+    const { handleNativeProfileAPI } = await import("../codex/native-profile-api");
+    return handleNativeProfileAPI(req, url, config, deps.nativeProfileApi);
+  }
+
+  if (url.pathname.startsWith("/api/codex-auth/")) {
+    const { handleCodexAuthAPI } = await import("../codex/auth-api");
+    const { ConfigMutationLockError } = await import("../config");
+    const { CodexCredentialRefreshLockTimeoutError } = await import("../codex/account-store");
+    try {
+      return await handleCodexAuthAPI(req, url, config, convergeCodexCatalog);
+    } catch (error) {
+      // Credential writers remap ConfigMutationLockError to CodexCredentialRefreshLockTimeoutError;
+      // treat both as the same retryable busy response.
+      if (error instanceof ConfigMutationLockError || error instanceof CodexCredentialRefreshLockTimeoutError) {
+        return jsonResponse(
+          { error: "Configuration is busy; retry shortly", code: "CONFIG_MUTATION_LOCK_UNAVAILABLE" },
+          503,
+          req,
+          config,
+        );
+      }
+      throw error;
+    }
+  }
+
+  return null;
+}
+
+
+export { buildClaudeDesktopState, fetchAllModels } from "./management/shared";

package/src/server/management-auth.ts

@@ -0,0 +1,353 @@
+import { randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+import {
+  chmodSync,
+  closeSync,
+  fsyncSync,
+  linkSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+import { adminApiTokenFilePath } from "../lib/admin-secrets";
+import {
+  SYSTEM_RESTART_CAPABILITY_HEADER,
+  SYSTEM_RESTART_EXPECTED_PID_HEADER,
+  SYSTEM_RESTART_NONCE_HEADER,
+  SYSTEM_RESTART_PATH,
+  parseExpectedSystemRestartPid,
+  verifySystemRestartCapability,
+} from "../lib/system-restart-contract";
+import { forgetEphemeralSecretPath, forgetHardenedSecretPath, hardenSecretDir, hardenSecretPath } from "../lib/windows-secret-acl";
+import type { OcxConfig } from "../types";
+import {
+  isAllowedManagementOrigin,
+  isApiAuthRequired,
+  isDataPlaneAdmissionSecret,
+  isLoopbackHostname,
+  managementRequestOrigin,
+  parseHttpHost,
+} from "./auth-cors";
+
+const GUI_SESSION_TTL_MS = 5 * 60_000;
+const GUI_SESSION_LIMIT = 128;
+
+interface GuiSessionRecord {
+  csrfToken: string;
+  origin: string;
+  expiresAt: number;
+}
+
+export interface GuiSessionBootstrap extends GuiSessionRecord {
+  token: string;
+}
+
+export type ManagementAuthState =
+  | {
+    available: true;
+    token: string;
+    source: "environment" | "file";
+    sessions: Map<string, GuiSessionRecord>;
+  }
+  | { available: false; reason: string };
+
+function fail(reason: string): ManagementAuthState {
+  return { available: false, reason };
+}
+
+function assertSafeDirectory(path: string): void {
+  mkdirSync(path, { recursive: true, mode: 0o700 });
+  const stat = lstatSync(path);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error("management token directory is not a regular directory");
+  chmodSync(path, 0o700);
+  let hardened: { ok: boolean };
+  try {
+    hardened = hardenSecretDir(path, { required: true });
+  } catch {
+    // required:true hardening now fails closed on genuine ACL timeouts too;
+    // keep the actionable guidance in the surfaced reason.
+    hardened = { ok: false };
+  }
+  if (!hardened.ok) {
+    throw new Error(
+      "management token directory ACL hardening did not complete; set OPENCODEX_ADMIN_AUTH_TOKEN to use an environment token instead of a file-backed token",
+    );
+  }
+}
+
+function readExistingToken(path: string): string {
+  const stat = lstatSync(path);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 512) {
+    throw new Error("management token path is not a regular secret file");
+  }
+  chmodSync(path, 0o600);
+  let hardened: { ok: boolean };
+  try {
+    hardened = hardenSecretPath(path, { required: true });
+  } catch {
+    hardened = { ok: false };
+  }
+  if (!hardened.ok) {
+    throw new Error(
+      "management token file ACL hardening did not complete; set OPENCODEX_ADMIN_AUTH_TOKEN to use an environment token instead of a file-backed token",
+    );
+  }
+  const token = readFileSync(path, "utf8").trim();
+  if (!/^ocx_admin_[A-Za-z0-9_-]{43}$/.test(token)) throw new Error("management token file is invalid");
+  return token;
+}
+
+export function removeManagementTokenPathBestEffort(
+  path: string,
+  remove: (path: string) => void = unlinkSync,
+  options?: { ephemeral?: boolean },
+): void {
+  // Temps get the full ephemeral release (success + both timeout namespaces);
+  // stable token paths drop only the success memo — destination-keyed timeout
+  // memos are intentional anti-restall state.
+  const forget = options?.ephemeral ? forgetEphemeralSecretPath : forgetHardenedSecretPath;
+  try {
+    remove(path);
+    forget(path);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") forget(path);
+    /* other failures retain fail-closed state for the caller */
+  }
+}
+
+function createTokenFile(path: string): string {
+  const directory = dirname(path);
+  const token = `ocx_admin_${randomBytes(32).toString("base64url")}`;
+  const temporary = join(directory, `.${randomUUID()}.admin-token.tmp`);
+  let linked = false;
+  let fd: number | null = null;
+  try {
+    fd = openSync(temporary, "wx", 0o600);
+    writeFileSync(fd, `${token}\n`, "utf8");
+    fsyncSync(fd);
+    closeSync(fd);
+    fd = null;
+    chmodSync(temporary, 0o600);
+    let temporaryHardened: { ok: boolean };
+    try {
+      // Destination-keyed timeout memo (the final token path), not the temp.
+      temporaryHardened = hardenSecretPath(temporary, { required: true, timeoutMemoKey: path });
+    } catch {
+      temporaryHardened = { ok: false };
+    }
+    if (!temporaryHardened.ok) {
+      throw new Error(
+        "management token temporary ACL hardening did not complete; set OPENCODEX_ADMIN_AUTH_TOKEN to use an environment token instead of a file-backed token",
+      );
+    }
+    try {
+      linkSync(temporary, path);
+      linked = true;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "EEXIST") return readExistingToken(path);
+      throw error;
+    }
+    let finalHardened: { ok: boolean };
+    try {
+      finalHardened = hardenSecretPath(path, { required: true });
+    } catch {
+      finalHardened = { ok: false };
+    }
+    if (!finalHardened.ok) {
+      throw new Error(
+        "management token file ACL hardening did not complete; set OPENCODEX_ADMIN_AUTH_TOKEN to use an environment token instead of a file-backed token",
+      );
+    }
+    return token;
+  } catch (error) {
+    if (linked) removeManagementTokenPathBestEffort(path);
+    throw error;
+  } finally {
+    if (fd !== null) {
+      try { closeSync(fd); } catch { /* best effort */ }
+    }
+    removeManagementTokenPathBestEffort(temporary, unlinkSync, { ephemeral: true });
+  }
+}
+
+function ready(token: string, source: "environment" | "file", config: OcxConfig): ManagementAuthState {
+  if (isDataPlaneAdmissionSecret(token, config)) {
+    return fail("management credential conflicts with a data-plane credential");
+  }
+  return { available: true, token, source, sessions: new Map() };
+}
+
+export function initializeManagementAuthState(config: OcxConfig): ManagementAuthState {
+  const environmentToken = process.env.OPENCODEX_ADMIN_AUTH_TOKEN?.trim();
+  if (environmentToken) {
+    return ready(environmentToken, "environment", config);
+  }
+  try {
+    const path = adminApiTokenFilePath();
+    assertSafeDirectory(dirname(path));
+    let token: string;
+    try {
+      token = readExistingToken(path);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      token = createTokenFile(path);
+    }
+    return ready(token, "file", config);
+  } catch (error) {
+    return fail(error instanceof Error ? error.message : "management token initialization failed");
+  }
+}
+
+function equalSecret(actual: string, expected: string): boolean {
+  const encoder = new TextEncoder();
+  const left = encoder.encode(actual);
+  const right = encoder.encode(expected);
+  return left.length === right.length && timingSafeEqual(left, right);
+}
+
+function removeExpiredSessions(state: Extract<ManagementAuthState, { available: true }>, now = Date.now()): void {
+  for (const [token, session] of state.sessions) {
+    if (session.expiresAt <= now) state.sessions.delete(token);
+  }
+}
+
+function randomSessionSecret(prefix: "ocx_session_"): string {
+  return `${prefix}${randomBytes(32).toString("base64url")}`;
+}
+
+export function issueGuiSession(
+  req: Request,
+  config: OcxConfig,
+  state: ManagementAuthState,
+): GuiSessionBootstrap | null {
+  if (isApiAuthRequired(config) || !state.available || req.method !== "GET" || !isAllowedManagementOrigin(req, config)) return null;
+  const host = parseHttpHost(req.headers.get("Host"));
+  if (!host || !isLoopbackHostname(host.hostname)) return null;
+  const origin = managementRequestOrigin(req, config);
+  if (!origin) return null;
+  const now = Date.now();
+  removeExpiredSessions(state, now);
+  while (state.sessions.size >= GUI_SESSION_LIMIT) {
+    const oldest = state.sessions.keys().next().value as string | undefined;
+    if (!oldest) break;
+    state.sessions.delete(oldest);
+  }
+  const token = randomSessionSecret("ocx_session_");
+  const session: GuiSessionRecord = {
+    csrfToken: randomBytes(32).toString("base64url"),
+    origin,
+    expiresAt: now + GUI_SESSION_TTL_MS,
+  };
+  state.sessions.set(token, session);
+  return { token, ...session };
+}
+
+/**
+ * Which credential actually authorized a management request.
+ *
+ * `admin-token` is the raw token from disk/env: anything running as the user can
+ * read it, including a coding agent. `gui-session` is a session token this process
+ * minted for a browser, and it only authorizes a mutation after the origin and the
+ * per-session CSRF token match. Consent-bearing routes must key off this value
+ * rather than off request headers, which the token holder can forge freely.
+ * `system-restart-capability` is a process-scoped HMAC accepted only for the exact
+ * restart route and bound to the current process PID and listening port.
+ */
+export type ManagementPrincipal = "admin-token" | "gui-session" | "system-restart-capability";
+
+export interface LocalManagementAuthContext {
+  attestationSecret: string;
+  pid: number;
+  port: number;
+}
+
+function hasSystemRestartCapability(
+  req: Request,
+  local: LocalManagementAuthContext | undefined,
+): boolean {
+  if (!local || req.method !== "POST") return false;
+  let path: string;
+  try {
+    path = new URL(req.url).pathname;
+  } catch {
+    return false;
+  }
+  if (path !== SYSTEM_RESTART_PATH) return false;
+  const expectedPid = parseExpectedSystemRestartPid(
+    req.headers.get(SYSTEM_RESTART_EXPECTED_PID_HEADER),
+  );
+  if (expectedPid.kind !== "present" || expectedPid.pid !== local.pid) return false;
+  return verifySystemRestartCapability(
+    local.attestationSecret,
+    req.headers.get(SYSTEM_RESTART_NONCE_HEADER),
+    req.method,
+    path,
+    local.pid,
+    local.port,
+    req.headers.get(SYSTEM_RESTART_CAPABILITY_HEADER),
+  );
+}
+
+/**
+ * The principal for a request that already passed `requireManagementAuth`. Kept as a
+ * separate resolution (rather than a changed return type) so every existing caller
+ * keeps its `Response | null` contract. Browser and admin principals are derived
+ * from the same session table and CSRF comparison the gate uses; the restart
+ * principal is derived from the same process-scoped capability check.
+ */
+export function managementPrincipal(
+  req: Request,
+  state: ManagementAuthState,
+  config?: OcxConfig,
+  local?: LocalManagementAuthContext,
+): ManagementPrincipal | null {
+  if (hasSystemRestartCapability(req, local)) return "system-restart-capability";
+  if (!state.available) return null;
+  const actual = req.headers.get("x-opencodex-api-key")?.trim()
+    || req.headers.get("authorization")?.replace(/^Bearer\s+/i, "").trim();
+  if (!actual) return null;
+  if (equalSecret(actual, state.token)) return "admin-token";
+  if (!config) return null;
+  removeExpiredSessions(state);
+  return state.sessions.has(actual) ? "gui-session" : null;
+}
+
+export function requireManagementAuth(
+  req: Request,
+  state: ManagementAuthState,
+  config?: OcxConfig,
+  local?: LocalManagementAuthContext,
+): Response | null {
+  if (hasSystemRestartCapability(req, local)) return null;
+  if (!state.available) {
+    return Response.json({
+      error: "management API unavailable",
+      reason: state.reason,
+      hint: "Set OPENCODEX_ADMIN_AUTH_TOKEN to bypass file-backed admin token ACL hardening",
+    }, { status: 503 });
+  }
+  const actual = req.headers.get("x-opencodex-api-key")?.trim()
+    || req.headers.get("authorization")?.replace(/^Bearer\s+/i, "").trim();
+  if (actual && equalSecret(actual, state.token)) return null;
+  if (actual && config) {
+    removeExpiredSessions(state);
+    const session = state.sessions.get(actual);
+    if (session) {
+      const requestOrigin = managementRequestOrigin(req, config);
+      const claimedOrigin = req.headers.get("x-opencodex-gui-origin");
+      const browserOrigin = req.headers.get("Origin");
+      const sameOrigin = requestOrigin === session.origin
+        && claimedOrigin === session.origin
+        && (!browserOrigin || browserOrigin === session.origin);
+      const safeMethod = req.method === "GET" || req.method === "HEAD";
+      const csrf = req.headers.get("x-opencodex-csrf-token")?.trim();
+      if (sameOrigin && (safeMethod || (browserOrigin === session.origin && !!csrf && equalSecret(csrf, session.csrfToken)))) {
+        return null;
+      }
+    }
+  }
+  return Response.json({ error: "Remodex admin token required" }, { status: 401 });
+}