@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
231 lines (211 loc) • 9.12 kB
text/typescript
import { existsSync, readFileSync, statSync } from "node:fs";
import { basename, extname, isAbsolute, join, relative, resolve } from "node:path";
import { browserSecurityHeaders } from "./auth-cors";
import type { GuiSessionBootstrap } from "./gui-session";
import { packageVersion } from "../lib/package-version";
import { isStandaloneBinary, standaloneRoot } from "../lib/standalone";
/** opencodex version, read from the packaged package.json (same source as the server bootstrap). */
const VERSION = packageVersion("0.0.0");
const MIME_TYPES: Record<string, string> = {
".html": "text/html", ".js": "application/javascript", ".css": "text/css",
".json": "application/json", ".svg": "image/svg+xml", ".png": "image/png",
".ico": "image/x-icon",
};
/**
* Matches Vite's content-hashed bundle filenames (e.g. `index-B5r7LNHN.js` or `style-D5SiRo8X.css`).
* Unhashed static assets (e.g. `runtime-config.js` or unversioned icons) must not be cached immutably.
*/
const HASHED_ASSET_PATTERN = /-[a-zA-Z0-9_-]{8,}\.[a-zA-Z0-9]+$/;
export function findGuiDist(): string | null {
const candidates = [
process.env.OPENCODEX_GUI_DIST,
...(isStandaloneBinary() ? [join(standaloneRoot(), "gui", "dist")] : []),
join(import.meta.dir, "..", "..", "gui", "dist"),
join(import.meta.dir, "..", "..", "..", "gui", "dist"),
].filter((candidate): candidate is string => Boolean(candidate));
for (const c of candidates) {
if (existsSync(join(c, "index.html"))) return c;
}
return null;
}
export function resolveGuiFilePath(guiDist: string, pathname: string): string | null {
let decodedPath: string;
try {
decodedPath = decodeURIComponent(pathname);
} catch {
return null;
}
if (decodedPath.includes("\0")) return null;
const relativePath = decodedPath === "/" || decodedPath === ""
? "index.html"
: decodedPath.replace(/\\/g, "/").replace(/^\/+/, "");
const root = resolve(guiDist);
const filePath = resolve(root, relativePath);
const rel = relative(root, filePath);
if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) return null;
return filePath;
}
function isFile(path: string): boolean {
try {
return statSync(path).isFile();
} catch {
return false;
}
}
/** HTML-attribute escape for values interpolated into meta tags. */
function escapeHtmlAttribute(value: string): string {
return value
.replaceAll("&", "&")
.replaceAll('"', """)
.replaceAll("<", "<")
.replaceAll(">", ">");
}
/** Shared session meta-tag block, escaped for quoted attribute interpolation. */
function sessionBootstrapMeta(session: GuiSessionBootstrap): string {
return [
`<meta name="opencodex-session-token" content="${escapeHtmlAttribute(session.token)}">`,
`<meta name="opencodex-session-csrf" content="${escapeHtmlAttribute(session.csrfToken)}">`,
`<meta name="opencodex-session-origin" content="${escapeHtmlAttribute(session.browserOrigin)}">`,
`<meta name="opencodex-session-server-origin" content="${escapeHtmlAttribute(session.serverOrigin)}">`,
].join("");
}
/**
* Runtime role, emitted on every served document.
*
* Separate from the session block on purpose: the session exists only once a GUI session
* has been issued, but the role has to be known on the very first paint of a plain
* standalone install — which never issues one. Without it the GUI has to ASK, and asking
* means a request to a remote-hub endpoint from a user who never enabled remote hub.
*
* Non-secret: it names which topology this proxy is running, which the operator configured
* and which the dashboard already reflects everywhere else.
*/
function runtimeRoleMeta(runtimeRole: string): string {
return `<meta name="opencodex-runtime-role" content="${escapeHtmlAttribute(runtimeRole)}">`;
}
/**
* Does this bind require a typed management credential?
*
* Emitted for the same reason as the role: so the dashboard can answer a question on first
* paint without asking a remote-hub endpoint. It is NOT the same question as the role.
* `standalone` + `hostname: "0.0.0.0"` is an operator who deliberately exposed the dashboard
* and must type the admin token, while a `hub` on loopback still mints its own session — so
* the role cannot stand in for this, and using it that way locked out exactly the operator
* who is supposed to see the prompt.
*
* Non-secret: it restates the bind the operator chose, which `/healthz` and the dashboard
* already reflect.
*/
function managementAuthRequiredMeta(required: boolean): string {
return `<meta name="opencodex-management-auth-required" content="${required ? "1" : "0"}">`;
}
function htmlDocumentResponse(html: string): Response {
return new Response(html, {
headers: {
"Content-Type": "text/html",
"Cache-Control": "no-store",
Pragma: "no-cache",
...browserSecurityHeaders(),
},
});
}
function htmlResponse(
path: string,
session?: GuiSessionBootstrap,
runtimeRole?: string,
managementAuthRequired?: boolean,
): Response {
let html = readFileSync(path, "utf8");
const bootstrap = [
runtimeRole ? runtimeRoleMeta(runtimeRole) : "",
managementAuthRequired === undefined ? "" : managementAuthRequiredMeta(managementAuthRequired),
session ? sessionBootstrapMeta(session) : "",
].join("");
if (bootstrap) {
html = html.includes("</head>") ? html.replace("</head>", `${bootstrap}</head>`) : `${bootstrap}${html}`;
}
return htmlDocumentResponse(html);
}
/**
* Minimal session-bootstrap document, independent of any packaged GUI build. The dev
* GUI (Vite) proxies /opencodex-session to the backend with the original host so the
* backend can mint an origin-bound loopback session even when gui/dist does not exist.
*/
export function serveSessionBootstrap(session: GuiSessionBootstrap): Response {
const bootstrap = sessionBootstrapMeta(session);
const html = `<!doctype html><html><head><meta charset="utf-8">${bootstrap}</head><body></body></html>`;
return htmlDocumentResponse(html);
}
/**
* Serves a GUI static file from the distribution directory.
* Returns a Response with MIME type and appropriate Cache-Control headers:
* - HTML files receive `no-store` to guarantee immediate bootstrap updates.
* - Content-hashed bundles under `assets/` receive 1-year `immutable` caching.
* - Non-hashed static files (e.g. favicon, unhashed assets) receive `no-cache` for prompt revalidation.
* Returns null if the file cannot be found or resolved.
*/
export function serveGuiFile(
pathname: string,
guiDist = findGuiDist(),
session?: GuiSessionBootstrap,
runtimeRole?: string,
managementAuthRequired?: boolean,
): Response | null {
if (!guiDist) return null;
const filePath = resolveGuiFilePath(guiDist, pathname);
if (!filePath) return null;
if (!isFile(filePath)) {
if (!extname(pathname)) {
const indexPath = join(guiDist, "index.html");
if (isFile(indexPath)) {
return htmlResponse(indexPath, session, runtimeRole, managementAuthRequired);
}
}
return null;
}
const ext = extname(filePath);
const contentType = MIME_TYPES[ext] || "application/octet-stream";
if (ext === ".html") return htmlResponse(filePath, session, runtimeRole, managementAuthRequired);
const root = resolve(guiDist);
// "assets/" matches Vite's default assetsDir (gui/vite.config.ts). If that value is
// ever changed, update this prefix to match. filePath is already resolve()-normalized
// by resolveGuiFilePath, so rel cannot contain ".." fragments.
//
// Immutable 1-year caching is only applied when the file is under assets/ AND its basename
// matches Vite's content-hash pattern (e.g. index-B5r7LNHN.js). Any unhashed asset under
// assets/ (e.g. runtime-config.js) or elsewhere falls back to no-cache so clients revalidate,
// whereas index.html uses no-store above to avoid storing any bootstrap state.
const rel = relative(root, filePath).replace(/\\/g, "/");
const isHashedAsset = rel.startsWith("assets/") && HASHED_ASSET_PATTERN.test(basename(filePath));
const cacheControl = isHashedAsset
? "public, max-age=31536000, immutable"
: "no-cache";
// Snapshot bytes before returning the response. Bun.file is lazy: if gui/dist is replaced
// after Bun frames the response but before the stream finishes, its Content-Length can
// describe the old file while the body comes from the new one (#2792).
return new Response(readFileSync(filePath), {
headers: {
"Content-Type": contentType,
"Cache-Control": cacheControl,
...browserSecurityHeaders(),
},
});
}
export function rootFallbackPayload() {
return {
status: "ok",
service: "opencodex",
version: VERSION,
dashboard: {
available: false,
reason: "GUI build not found. Run `bun run build:gui` from the opencodex repo, or use `ocx gui` from a packaged install.",
},
endpoints: {
health: "/healthz",
models: "/v1/models",
responses: "/v1/responses",
chatCompletions: "/v1/chat/completions",
management: "/api/*",
},
};
}