@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
353 lines (329 loc) • 15.5 kB
text/typescript
/**
* Local plugin loader.
*
* `ocx start` imports every `*.ts`, `*.js` and `*.mjs` file in `$OPENCODEX_HOME/plugins/`
* before the server binds, so a plugin's hooks are in place for the first request. A missing
* directory means no plugins and no work. `OCX_PLUGINS=0` disables loading for one start.
*
* A plugin is a module whose default export is `{ name?, setup(ctx) }`. It runs in the proxy
* process with the operator's credentials, so the loader accepts only files owned by the
* current user that no other user can write — the same trust boundary as `config.json`.
* Windows auto-loading stays disabled until this trust check is backed by an ACL check.
* Plugins cannot import ocx internals (a compiled binary keeps them inside `$bunfs`); they
* receive everything they may use through `OcxPluginContext`.
*
* Failures are contained: a plugin that throws, times out or has the wrong shape is reported
* and skipped, its context stops accepting registrations, and the remaining plugins and the
* proxy start normally. The setup deadline bounds setup that yields to the event loop; plugins
* run in the proxy's own thread, so synchronous work that never yields cannot be interrupted.
*/
import { lstatSync, readdirSync, realpathSync } from "node:fs";
import { basename, dirname, join } from "node:path";
import { pathToFileURL } from "node:url";
import { spawnSync } from "node:child_process";
import { userInfo } from "node:os";
import { getConfigDir } from "../config/paths";
import { registerOptionalShutdownHook } from "../lib/optional-shutdown-hooks";
import { registerUpstreamRewriter, type UpstreamRewriter } from "./upstream-hooks";
export type { UpstreamRewriter, UpstreamTarget, UpstreamTransport } from "./upstream-hooks";
export interface OcxPluginContext {
/** The plugin's own name, as reported in logs. */
readonly name: string;
/** `$OPENCODEX_HOME`, for plugins that keep state next to the proxy's. */
readonly configDir: string;
/** `$OPENCODEX_HOME/plugins`. */
readonly pluginDir: string;
log(message: string): void;
/** See `src/plugins/upstream-hooks.ts`. Called synchronously on every provider send. */
registerUpstreamRewriter(rewrite: UpstreamRewriter): void;
/** Runs once when the proxy shuts down. Must not throw or block. */
onShutdown(teardown: () => void): void;
}
export interface OcxPlugin {
name?: string;
setup(context: OcxPluginContext): void | Promise<void>;
}
export interface PluginLoadResult {
file: string;
name: string;
loaded: boolean;
error?: "windows_auto_load_disabled" | "directory_read_failed" | "directory_resolution_failed"
| "directory_untrusted" | "ancestor_untrusted" | "file_untrusted"
| "import_failed" | "invalid_export" | "setup_failed" | "setup_timeout";
}
const PLUGIN_EXTENSIONS = [".ts", ".js", ".mjs"];
const SETUP_TIMEOUT_MS = 5_000;
const ACL_PROBE_TIMEOUT_MS = 2_000;
const MAC_ACL_BENIGN_TOKENS = new Set([
"read", "list", "search", "execute", "readattr", "readextattr", "readsecurity",
"file_inherit", "directory_inherit", "limit_inherit", "only_inherit",
]);
/**
* A deny, trusted-user grant, or read-only ACL does not let another user replace a checked path.
* `only_inherit` is not effective on this object; inherited grants on descendants are checked
* when those descendants are visited. Unknown allow rights and malformed entries fail closed.
*/
export function macAclListingTrustError(listing: string, currentUser = userInfo().username): string | null {
const [header, ...lines] = listing.split("\n");
const owner = /^\S+\s+\d+\s+(\S+)\s+/.exec(header ?? "")?.[1];
let unparseable = !owner;
for (const line of lines) {
if (!/^\s*\d+:/.test(line)) continue;
const entry = /^\s*\d+:\s+(.+?)\s+(?:inherited\s+)?(allow|deny)\s+([a-z_,]+)\s*$/.exec(line);
if (!entry) { unparseable = true; continue; }
if (entry[2] === "deny") continue;
const principal = entry[1]!;
// The file owner and this process's user already control the path without an ACE. Require the
// `user:` prefix: a bare or group principal might include other users. macOS `ls` prints a
// resolved directory-record NAME here, so neither `0` nor `root` proves that the ACE is UID 0.
// On a genuinely root-owned path, `root` is still admitted by the owner comparison.
if (principal.startsWith("user:")
&& [owner, currentUser].includes(principal.slice(5))) continue;
const rights = entry[3]!.split(",");
if (rights.includes("only_inherit")) continue;
if (rights.some(right => !MAC_ACL_BENIGN_TOKENS.has(right))) return "has an access control list";
}
return unparseable ? "access control list inspection failed" : null;
}
interface MacAclProbeResult {
status: number | null;
stdout: string;
error?: Error;
}
/** A failed inspection never grants trust, even if a subsequent probe is attempted. */
export function macAclProbeTrustError(probe: () => MacAclProbeResult): string | null {
try {
const first = probe();
// A timeout may carry partial stdout. Its unsafe ACEs are authoritative even if a retry
// would be clean; any other partial listing is incomplete and therefore also refused.
// Retry only when the first probe produced no ACL evidence at all.
let result = first;
if ((first.error as NodeJS.ErrnoException | undefined)?.code === "ETIMEDOUT") {
if (first.stdout.trim()) {
return macAclListingTrustError(first.stdout) ?? "access control list inspection failed";
}
result = probe();
}
if (result.error || result.status !== 0) return "access control list inspection failed";
return macAclListingTrustError(result.stdout);
} catch {
return "access control list inspection failed";
}
}
/** Refuse extended ACLs: mode bits alone cannot prove who can rewrite a plugin path. */
function aclTrustError(path: string): string | null {
if (process.platform !== "darwin" && process.platform !== "linux") return null;
const mac = process.platform === "darwin";
// CI and operator PATHs may put GNU coreutils ahead of the macOS tool.
// GNU ls does not support -e, so pin the OS ACL inspector.
const probe = () => spawnSync(mac ? "/bin/ls" : "getfacl", mac
? ["-lebd", "--", path] : ["-cp", "--", path], {
encoding: "utf8",
timeout: ACL_PROBE_TIMEOUT_MS,
maxBuffer: 64 * 1024,
env: { ...process.env, LC_ALL: "C" },
});
if (mac) return macAclProbeTrustError(probe);
const result = probe();
// getfacl is optional on Linux. Without it, the POSIX owner/mode checks below remain;
// the documented Linux ACL limitation must be visible to operators.
if ((result.error as NodeJS.ErrnoException | undefined)?.code === "ENOENT") return null;
if (result.error || result.status !== 0) return "access control list inspection failed";
return result.stdout.split("\n").some(line => /^(?:user:[^:]+:|group:[^:]+:|mask::|default:)/.test(line))
? "has an access control list" : null;
}
export function pluginDirectory(): string {
return join(getConfigDir(), "plugins");
}
/** A missing directory is "no plugins"; any other read failure propagates to be reported. */
function listPluginFiles(dir: string): string[] {
let entries: string[];
try {
entries = readdirSync(dir);
} catch (error) {
if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
throw error;
}
return entries
.filter(entry => !entry.startsWith(".") && !entry.startsWith("_") && !entry.endsWith(".d.ts"))
.filter(entry => PLUGIN_EXTENSIONS.some(extension => entry.endsWith(extension)))
.sort()
.map(entry => join(dir, entry));
}
/**
* Null when `path` is safe to trust, otherwise the reason it is refused. `lstat` is used so a
* symbolic link is judged as a link — and refused — rather than as the file it points to: a
* link to a file you own would otherwise pass the owner and mode checks. Windows has no
* POSIX owner or mode bits; the loader refuses execution on that platform.
*/
function trustError(path: string, kind: "file" | "directory"): string | null {
let stats: ReturnType<typeof lstatSync>;
try {
stats = lstatSync(path);
} catch {
return "filesystem inspection failed";
}
if (stats.isSymbolicLink()) return "is a symbolic link";
if (kind === "file" ? !stats.isFile() : !stats.isDirectory()) return `not a regular ${kind}`;
if (process.platform === "win32") return null;
const uid = process.getuid?.();
if (uid !== undefined && stats.uid !== uid) return "owned by another user";
// A POSIX ACL write mask may also set group-write mode bits. Inspect the ACL first so
// the extended grant is explicitly refused even when the mode check would also refuse it.
const aclError = aclTrustError(path);
if (aclError) return aclError;
if ((stats.mode & 0o022) !== 0) return "writable by group or others (chmod go-w)";
return null;
}
/** Null when the file is safe to execute, otherwise the reason it is refused. */
export function pluginFileTrustError(file: string): string | null {
return trustError(file, "file");
}
/**
* A directory another user can write lets them add or swap plugin files, so its owner and
* mode are checked like each file's.
*/
export function pluginDirectoryTrustError(dir: string): string | null {
return trustError(dir, "directory");
}
/**
* Every directory above the (resolved) plugin directory, up to `/`, must be owned by the user
* or root and not writable by group or others unless it is sticky (like `/tmp`), where others
* cannot rename or replace entries they do not own. With no writable component on the path, no
* other user can swap what the loader checked for something else before it is imported
* (OpenSSH StrictModes applies the same rule). POSIX only.
*/
export function pluginAncestorsTrustError(realDir: string): string | null {
if (process.platform === "win32") return null;
const uid = process.getuid?.();
let current = dirname(realDir);
for (;;) {
let stats: ReturnType<typeof lstatSync>;
try {
stats = lstatSync(current);
} catch {
return "ancestor inspection failed";
}
if (uid !== undefined && stats.uid !== uid && stats.uid !== 0) return `${current} is owned by another user`;
const aclError = aclTrustError(current);
if (aclError) return aclError;
if ((stats.mode & 0o022) !== 0 && (stats.mode & 0o1000) === 0) {
return `${current} is writable by group or others`;
}
const parent = dirname(current);
if (parent === current) return null;
current = parent;
}
}
function isPlugin(value: unknown): value is OcxPlugin {
return typeof value === "object" && value !== null && typeof (value as OcxPlugin).setup === "function";
}
async function withTimeout<T>(work: Promise<T>, ms: number): Promise<T> {
let timer: ReturnType<typeof setTimeout> | undefined;
const timeout = new Promise<never>((_, reject) => {
timer = setTimeout(() => reject(new PluginSetupTimeoutError()), ms);
});
try {
return await Promise.race([work, timeout]);
} finally {
clearTimeout(timer);
}
}
class PluginSetupTimeoutError extends Error {}
export interface LoadOcxPluginsOptions {
/** Deadline for a setup that yields; see the module comment. */
setupTimeoutMs?: number;
}
export async function loadOcxPlugins(
dir = pluginDirectory(),
options: LoadOcxPluginsOptions = {},
): Promise<PluginLoadResult[]> {
if (process.env["OCX_PLUGINS"] === "0") return [];
if (process.platform === "win32") {
return [{ file: dir, name: "plugins directory", loaded: false, error: "windows_auto_load_disabled" }];
}
let files: string[];
try {
files = listPluginFiles(dir);
} catch {
return [{ file: dir, name: "plugins directory", loaded: false, error: "directory_read_failed" }];
}
if (files.length === 0) return [];
const dirRefused = pluginDirectoryTrustError(dir);
if (dirRefused) return [{ file: dir, name: "plugins directory", loaded: false, error: "directory_untrusted" }];
// Check and import through the resolved path, so both refer to the same components.
let realDir: string;
try {
realDir = realpathSync(dir);
} catch {
return [{ file: dir, name: "plugins directory", loaded: false, error: "directory_resolution_failed" }];
}
const ancestorRefused = pluginAncestorsTrustError(realDir);
if (ancestorRefused) return [{ file: dir, name: "plugins directory", loaded: false, error: "ancestor_untrusted" }];
const results: PluginLoadResult[] = [];
for (const file of files.map(listed => join(realDir, basename(listed)))) {
const fallbackName = basename(file).replace(/\.(ts|js|mjs)$/, "");
const refused = pluginFileTrustError(file);
if (refused) {
results.push({ file, name: fallbackName, loaded: false, error: "file_untrusted" });
continue;
}
const unregister: Array<() => void> = [];
// Closed when setup fails or times out: a setup that resumes later must not register.
let active = true;
let shutdownCount = 0;
const whileActive = (name: string, register: () => () => void): void => {
if (!active) {
console.error("[opencodex] plugin registration ignored: setup_failed");
return;
}
unregister.push(register());
};
let phase: "import" | "export" | "setup" = "import";
try {
const module = await import(pathToFileURL(file).href) as { default?: unknown; plugin?: unknown };
const plugin = module.default ?? module.plugin;
phase = "export";
if (!isPlugin(plugin)) throw new Error("default export must be { name?, setup(context) }");
const name = typeof plugin.name === "string" && plugin.name.trim() ? plugin.name.trim() : fallbackName;
const context: OcxPluginContext = {
name,
configDir: getConfigDir(),
pluginDir: dir,
log: message => console.log(`[plugin:${name}] ${message}`),
registerUpstreamRewriter: rewrite => whileActive(name, () => registerUpstreamRewriter(name, rewrite)),
// Keyed by file and registration, not name: two plugins may share a display name, and
// one plugin may register several teardowns.
onShutdown: teardown => whileActive(name, () => registerOptionalShutdownHook(`plugin:${file}#${++shutdownCount}`, teardown)),
};
const timeoutMs = options.setupTimeoutMs ?? SETUP_TIMEOUT_MS;
phase = "setup";
await withTimeout(Promise.resolve(plugin.setup(context)), timeoutMs);
results.push({ file, name, loaded: true });
} catch (error) {
// A half-initialised plugin must not leave hooks behind, now or later.
active = false;
for (const undo of unregister) undo();
results.push({
file,
name: fallbackName,
loaded: false,
error: error instanceof PluginSetupTimeoutError ? "setup_timeout"
: phase === "import" ? "import_failed"
: phase === "export" ? "invalid_export" : "setup_failed",
});
}
}
return results;
}
/** `ocx start` entry: load and print one line per plugin. Never throws. */
export async function loadAndReportOcxPlugins(): Promise<void> {
try {
for (const result of await loadOcxPlugins()) {
if (result.loaded) console.log(`🔌 Plugin loaded: ${result.name}`);
else console.error(`⚠️ Plugin skipped: ${result.error}`);
}
} catch {
console.error("⚠️ Plugin loading failed: internal_error");
}
}