UNPKG

@bitkyc08/opencodex

Version:

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code

586 lines (554 loc) • 24.3 kB
import { createPrivateKey, createPublicKey, randomUUID, sign, verify } from "node:crypto"; import { arch, hostname, platform } from "node:os"; import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, statSync } from "node:fs"; import { basename, dirname, isAbsolute, join } from "node:path"; import { atomicWriteFile } from "../config/atomic-write"; import { getConfigDir } from "../config/paths"; import { workspaceSecretFileExists, workspaceSecretPermissions, type WorkspaceSecretPermissions } from "./workspace-secret-store"; import { generateRemoteControlIdentityKeyPair, type RemoteControlIdentityKeyPair, } from "./crypto"; import { RemoteWorkspaceExecutor } from "./workspace-executor"; import { RemoteWorkspaceExecutorAgentConnection } from "./workspace-agent-connection"; import { createPlatformRemoteWorkspaceCommandRunner, discoverRemoteWorkspaceNativeHelper, parseRemoteWorkspaceNativeHelperDescriptor, pinRemoteWorkspaceNativeHelper, type RemoteWorkspaceNativeHelperDescriptor, } from "./workspace-command-runner"; import type { RemoteWorkspaceCommandRunner } from "./workspace-executor"; import { REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION, serializeRemoteWorkspaceAgentMessage, } from "./workspace-agent-protocol"; import { parseRemoteWorkspaceCapabilities, type RemoteWorkspaceCapability, } from "./workspace-tools"; export const REMOTE_WORKSPACE_DEVICE_STATE_VERSION = 1 as const; const DEVICE_TOKEN_PATTERN = /^ocxrw_[A-Za-z0-9_-]{43}$/; const MAX_PAIR_RESPONSE_BYTES = 64 * 1024; const MAX_DEVICE_STATE_BYTES = 1024 * 1024; const PAIR_TIMEOUT_MS = 15_000; export interface RemoteWorkspaceDeviceRoot { id: string; label: string; path: string; } export interface RemoteWorkspaceDeviceState { version: typeof REMOTE_WORKSPACE_DEVICE_STATE_VERSION; hubUrl: string; agentUrl: string; deviceId: string; deviceName: string; devicePlatform: string; capabilities: RemoteWorkspaceCapability[]; deviceToken: string; deviceIdentity: RemoteControlIdentityKeyPair; hubPublicKey: string; roots: RemoteWorkspaceDeviceRoot[]; toolchainRoots: string[]; nativeHelper?: RemoteWorkspaceNativeHelperDescriptor; } export interface RemoteWorkspaceDeviceStateStore { load(): RemoteWorkspaceDeviceState | null; save(state: RemoteWorkspaceDeviceState): void; } export interface PairRemoteWorkspaceDeviceOptions { hubUrl: string; pairingCode: string; name?: string; roots: Array<{ path: string; label?: string }>; fetchImpl?: typeof fetch; store?: RemoteWorkspaceDeviceStateStore; devicePlatform?: string; capabilities?: RemoteWorkspaceCapability[]; toolchainRoots?: string[]; nativeHelperPath?: string; } export interface RemoteWorkspaceWebSocketLike { readyState: number; send(value: string): void; close(code?: number, reason?: string): void; addEventListener(type: "open" | "close" | "error" | "message", listener: (event: Event | MessageEvent) => void): void; } export type RemoteWorkspaceWebSocketFactory = ( url: string, headers: Record<string, string>, ) => RemoteWorkspaceWebSocketLike; function boundedText(value: unknown, label: string, max: number): string { if (typeof value !== "string") throw new Error(`invalid remote workspace ${label}`); const normalized = value.trim(); if (normalized.length < 1 || normalized.length > max || /[\x00-\x1f\x7f]/.test(normalized)) { throw new Error(`invalid remote workspace ${label}`); } return normalized; } function uuid(value: unknown, label: string): string { const text = boundedText(value, label, 64); if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(text)) { throw new Error(`invalid remote workspace ${label}`); } return text; } function publicKey(value: unknown, label: string): string { const encoded = boundedText(value, label, 1024); if (!/^[A-Za-z0-9_-]+$/.test(encoded)) throw new Error(`invalid remote workspace ${label}`); const key = createPublicKey({ key: Buffer.from(encoded, "base64url"), type: "spki", format: "der" }); if (key.asymmetricKeyType !== "ed25519") throw new Error(`remote workspace ${label} must use Ed25519`); return encoded; } function identity(value: unknown): RemoteControlIdentityKeyPair { if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("invalid remote workspace device identity"); const raw = value as Record<string, unknown>; const pub = publicKey(raw.publicKey, "device public key"); const priv = boundedText(raw.privateKey, "device private key", 2048); const privateKey = createPrivateKey({ key: Buffer.from(priv, "base64url"), type: "pkcs8", format: "der" }); if (privateKey.asymmetricKeyType !== "ed25519") throw new Error("remote workspace device key must use Ed25519"); const challenge = Buffer.from("opencodex remote workspace device identity v1", "utf8"); if (!verify( null, challenge, createPublicKey({ key: Buffer.from(pub, "base64url"), type: "spki", format: "der" }), sign(null, challenge, privateKey), )) throw new Error("remote workspace device identity key pair does not match"); return { publicKey: pub, privateKey: priv }; } export function normalizeRemoteWorkspaceHubUrl(value: string): string { const url = new URL(value); const local = (url.hostname === "127.0.0.1" || url.hostname === "localhost") && url.protocol === "http:"; if (url.protocol !== "https:" && !local) throw new Error("remote workspace hub must use HTTPS"); if (url.username || url.password || url.search || url.hash) throw new Error("remote workspace hub URL must not contain credentials or fragments"); url.pathname = url.pathname.replace(/\/+$/, "") || "/"; return url.toString().replace(/\/$/, ""); } function agentUrlForHub(hubUrl: string): string { const url = new URL("/remote-workspace/agent", `${hubUrl}/`); url.protocol = url.protocol === "https:" ? "wss:" : "ws:"; return url.toString(); } function validateRootInputs(values: Array<{ path: string; label?: string }>): RemoteWorkspaceDeviceRoot[] { if (values.length < 1 || values.length > 32) throw new Error("remote workspace device needs one to 32 roots"); const paths = new Set<string>(); const labels = new Set<string>(); return values.map(value => { if (!isAbsolute(value.path) || value.path.includes("\0")) throw new Error("remote workspace root must be an absolute path"); const metadata = lstatSync(value.path); if (!metadata.isDirectory() || metadata.isSymbolicLink()) throw new Error("remote workspace root must be a real directory"); const path = realpathSync(value.path); const label = boundedText(value.label ?? basename(path), "root label", 80); const folded = label.toLocaleLowerCase("en-US"); if (paths.has(path) || labels.has(folded)) throw new Error("duplicate remote workspace root"); paths.add(path); labels.add(folded); return { id: randomUUID(), label, path }; }); } function parseRoots(value: unknown): RemoteWorkspaceDeviceRoot[] { if (!Array.isArray(value) || value.length < 1 || value.length > 32) throw new Error("invalid remote workspace device roots"); const paths = new Set<string>(); const ids = new Set<string>(); return value.map(item => { if (!item || typeof item !== "object" || Array.isArray(item)) throw new Error("invalid remote workspace device root"); const raw = item as Record<string, unknown>; const id = uuid(raw.id, "root ID"); const label = boundedText(raw.label, "root label", 80); const path = boundedText(raw.path, "root path", 4096); if (!isAbsolute(path) || ids.has(id) || paths.has(path)) throw new Error("invalid remote workspace device root"); ids.add(id); paths.add(path); return { id, label, path }; }); } function validateToolchainRoots(value: unknown): string[] { if (value === undefined) return []; if (!Array.isArray(value) || value.length > 16) throw new Error("invalid remote workspace toolchain roots"); const paths = new Set<string>(); for (const candidate of value) { if (typeof candidate !== "string" || !isAbsolute(candidate) || candidate.includes("\0")) { throw new Error("remote workspace toolchain root must be an absolute directory"); } const metadata = lstatSync(candidate); if (!metadata.isDirectory() || metadata.isSymbolicLink()) { throw new Error("remote workspace toolchain root must be a real directory"); } paths.add(realpathSync(candidate)); } return [...paths]; } export function parseRemoteWorkspaceDeviceState(value: unknown): RemoteWorkspaceDeviceState { if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("invalid remote workspace device state"); const raw = value as Record<string, unknown>; if (raw.version !== REMOTE_WORKSPACE_DEVICE_STATE_VERSION) throw new Error("unsupported remote workspace device state"); const hubUrl = normalizeRemoteWorkspaceHubUrl(boundedText(raw.hubUrl, "hub URL", 2048)); const agentUrl = boundedText(raw.agentUrl, "agent URL", 2048); if (agentUrl !== agentUrlForHub(hubUrl)) throw new Error("remote workspace agent URL does not match its hub"); const deviceToken = boundedText(raw.deviceToken, "device token", 128); if (!DEVICE_TOKEN_PATTERN.test(deviceToken)) throw new Error("invalid remote workspace device token"); return { version: REMOTE_WORKSPACE_DEVICE_STATE_VERSION, hubUrl, agentUrl, deviceId: uuid(raw.deviceId, "device ID"), deviceName: boundedText(raw.deviceName, "device name", 80), devicePlatform: boundedText(raw.devicePlatform, "device platform", 80), capabilities: parseRemoteWorkspaceCapabilities(raw.capabilities), deviceToken, deviceIdentity: identity(raw.deviceIdentity), hubPublicKey: publicKey(raw.hubPublicKey, "hub public key"), roots: parseRoots(raw.roots), toolchainRoots: validateToolchainRoots(raw.toolchainRoots), ...(raw.nativeHelper === undefined ? {} : { nativeHelper: parseRemoteWorkspaceNativeHelperDescriptor(raw.nativeHelper) }), }; } export class RemoteWorkspaceDeviceFileStore implements RemoteWorkspaceDeviceStateStore { constructor( private readonly path = join(getConfigDir(), "remote-workspace-device.json"), private readonly permissions: WorkspaceSecretPermissions = workspaceSecretPermissions, ) {} load(): RemoteWorkspaceDeviceState | null { if (!workspaceSecretFileExists(this.path)) return null; this.permissions.prepareDirectory(dirname(this.path)); this.permissions.hardenFile(this.path); const metadata = statSync(this.path); if (!metadata.isFile() || metadata.size > MAX_DEVICE_STATE_BYTES) { throw new Error("remote workspace device state is too large"); } return parseRemoteWorkspaceDeviceState(JSON.parse(readFileSync(this.path, "utf8"))); } save(state: RemoteWorkspaceDeviceState): void { this.permissions.prepareDirectory(dirname(this.path)); if (workspaceSecretFileExists(this.path)) this.permissions.hardenFile(this.path); atomicWriteFile(this.path, `${JSON.stringify(parseRemoteWorkspaceDeviceState(state), null, 2)}\n`); } } async function boundedJson(response: Response): Promise<unknown> { const declared = Number(response.headers.get("content-length") ?? "0"); if (Number.isFinite(declared) && declared > MAX_PAIR_RESPONSE_BYTES) throw new Error("remote workspace hub response is too large"); const reader = response.body?.getReader(); const chunks: Uint8Array[] = []; let total = 0; if (reader) { try { while (true) { const next = await reader.read(); if (next.done) break; total += next.value.byteLength; if (total > MAX_PAIR_RESPONSE_BYTES) { await reader.cancel("remote workspace hub response is too large").catch(() => {}); throw new Error("remote workspace hub response is too large"); } chunks.push(next.value); } } finally { reader.releaseLock(); } } const body = new Uint8Array(total); let offset = 0; for (const chunk of chunks) { body.set(chunk, offset); offset += chunk.byteLength; } const text = new TextDecoder("utf-8", { fatal: true }).decode(body); try { return text ? JSON.parse(text) : {}; } catch { throw new Error(`remote workspace hub returned HTTP ${response.status}`); } } export async function pairRemoteWorkspaceDevice(options: PairRemoteWorkspaceDeviceOptions): Promise<RemoteWorkspaceDeviceState> { const hubUrl = normalizeRemoteWorkspaceHubUrl(options.hubUrl); const roots = validateRootInputs(options.roots); const deviceName = boundedText(options.name ?? hostname(), "device name", 80); const devicePlatform = boundedText(options.devicePlatform ?? `${platform()}-${arch()}`, "device platform", 80); const toolchainRoots = validateToolchainRoots(options.toolchainRoots); const nativeHelper = options.nativeHelperPath ? pinRemoteWorkspaceNativeHelper(options.nativeHelperPath) : discoverRemoteWorkspaceNativeHelper(); const commandRunner = createPlatformRemoteWorkspaceCommandRunner({ linux: { toolchainRoots, writableRoots: roots.map(root => root.path) }, ...(nativeHelper ? { native: { helper: nativeHelper, toolchainRoots, writableRoots: roots.map(root => root.path), } } : {}), }); const capabilities = remoteWorkspaceCapabilitiesForCommandRunner(commandRunner, options.capabilities); const deviceIdentity = generateRemoteControlIdentityKeyPair(); const response = await (options.fetchImpl ?? fetch)(new URL("/remote-workspace/pair", `${hubUrl}/`), { method: "POST", redirect: "error", signal: AbortSignal.timeout(PAIR_TIMEOUT_MS), headers: { "content-type": "application/json", accept: "application/json" }, body: JSON.stringify({ code: options.pairingCode, name: deviceName, platform: devicePlatform, publicKey: deviceIdentity.publicKey, capabilities, roots: roots.map(root => ({ id: root.id, label: root.label })), }), }); const body = await boundedJson(response); if (!response.ok || !body || typeof body !== "object" || Array.isArray(body)) { const error = body && typeof body === "object" && "error" in body && typeof body.error === "string" ? body.error : `remote workspace pairing failed (${response.status})`; throw new Error(error); } const raw = body as Record<string, unknown>; const device = raw.device && typeof raw.device === "object" && !Array.isArray(raw.device) ? raw.device as Record<string, unknown> : null; if (!device) throw new Error("remote workspace hub returned an invalid device"); const state = parseRemoteWorkspaceDeviceState({ version: REMOTE_WORKSPACE_DEVICE_STATE_VERSION, hubUrl, agentUrl: agentUrlForHub(hubUrl), deviceId: device.id, deviceName, devicePlatform, capabilities, deviceToken: raw.deviceToken, deviceIdentity, hubPublicKey: raw.hubPublicKey, roots, toolchainRoots, ...(nativeHelper ? { nativeHelper } : {}), }); (options.store ?? new RemoteWorkspaceDeviceFileStore()).save(state); return state; } function defaultWebSocketFactory(url: string, headers: Record<string, string>): RemoteWorkspaceWebSocketLike { return new WebSocket(url, { headers } as unknown as string[]) as unknown as RemoteWorkspaceWebSocketLike; } async function messageBytes(event: MessageEvent): Promise<string | Uint8Array> { if (typeof event.data === "string") return event.data; if (event.data instanceof ArrayBuffer) return new Uint8Array(event.data); if (ArrayBuffer.isView(event.data)) return new Uint8Array(event.data.buffer, event.data.byteOffset, event.data.byteLength); if (event.data instanceof Blob) return new Uint8Array(await event.data.arrayBuffer()); throw new Error("remote workspace agent received an unsupported frame"); } export interface RemoteWorkspaceAgentHandle { connected: Promise<void>; closed: Promise<void>; stop(): void; } export interface RemoteWorkspaceAgentRunStatus { state: "connecting" | "online" | "reconnecting" | "stopped"; attempt: number; message?: string; } /** Never advertise more authority than both local support and the pairing-time grant allow. */ export function remoteWorkspaceCapabilitiesForCommandRunner( commandRunner: RemoteWorkspaceCommandRunner | undefined, approved?: readonly RemoteWorkspaceCapability[], ): RemoteWorkspaceCapability[] { const available = parseRemoteWorkspaceCapabilities([ "workspace.read", "workspace.write", ...(commandRunner ? ["workspace.exec" as const] : []), ]); const requested = parseRemoteWorkspaceCapabilities(approved ?? available); const allowed = new Set(available); return parseRemoteWorkspaceCapabilities(requested.filter(capability => allowed.has(capability))); } export function connectRemoteWorkspaceAgent(options: { state: RemoteWorkspaceDeviceState; webSocketFactory?: RemoteWorkspaceWebSocketFactory; commandRunner?: RemoteWorkspaceCommandRunner | null; }): RemoteWorkspaceAgentHandle { const state = parseRemoteWorkspaceDeviceState(options.state); const commandRunner = options.commandRunner === undefined ? createPlatformRemoteWorkspaceCommandRunner({ linux: { toolchainRoots: state.toolchainRoots, writableRoots: state.roots.map(root => root.path), }, ...(state.nativeHelper ? { native: { helper: state.nativeHelper, toolchainRoots: state.toolchainRoots, writableRoots: state.roots.map(root => root.path), } } : {}), }) : options.commandRunner ?? undefined; const capabilities = remoteWorkspaceCapabilitiesForCommandRunner(commandRunner, state.capabilities); const executor = new RemoteWorkspaceExecutor({ deviceId: state.deviceId, roots: state.roots.map(root => ({ id: root.id, path: root.path })), commandRunner, }); const socket = (options.webSocketFactory ?? defaultWebSocketFactory)(state.agentUrl, { authorization: `Bearer ${state.deviceToken}`, }); let agent: RemoteWorkspaceExecutorAgentConnection | null = null; let opened = false; let presenceAccepted = false; let stopped = false; let settleConnected!: () => void; let rejectConnected!: (error: Error) => void; let settleClosed!: () => void; const connected = new Promise<void>((resolve, reject) => { settleConnected = resolve; rejectConnected = reject; }); const closed = new Promise<void>(resolve => { settleClosed = resolve; }); let queue = Promise.resolve(); let heartbeat: ReturnType<typeof setInterval> | null = null; let presenceTimer: ReturnType<typeof setTimeout> | null = null; const acceptPresence = () => { if (stopped) return; if (presenceAccepted) return; presenceAccepted = true; if (presenceTimer) clearTimeout(presenceTimer); presenceTimer = null; settleConnected(); }; socket.addEventListener("open", () => { if (stopped) { try { socket.close(1000, "remote workspace agent stopped"); } catch { /* already closed */ } return; } opened = true; presenceTimer = setTimeout(() => { rejectConnected(new Error("remote workspace Hub did not acknowledge executor capabilities")); socket.close(1008, "remote workspace presence timed out"); }, 10_000); agent = new RemoteWorkspaceExecutorAgentConnection({ deviceId: state.deviceId, deviceIdentity: state.deviceIdentity, hubPublicKey: state.hubPublicKey, executor, capabilities, onPresenceAccepted: acceptPresence, socket: { send: value => socket.send(value), close: (code, reason) => socket.close(code, reason), }, }); socket.send(serializeRemoteWorkspaceAgentMessage({ version: REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION, type: "presence", capabilities, })); heartbeat = setInterval(() => { if (socket.readyState !== 1) return; socket.send(serializeRemoteWorkspaceAgentMessage({ version: REMOTE_WORKSPACE_AGENT_PROTOCOL_VERSION, type: "heartbeat", nonce: randomUUID(), })); }, 20_000); }); socket.addEventListener("message", event => { if (stopped || !(event instanceof MessageEvent) || !agent) return; queue = queue.then(async () => agent?.receive(await messageBytes(event))).catch(() => { socket.close(1008, "remote workspace protocol error"); }); }); socket.addEventListener("error", () => { if (!stopped && !presenceAccepted) rejectConnected(new Error("remote workspace agent connection failed")); }); socket.addEventListener("close", () => { stopped = true; if (presenceTimer) clearTimeout(presenceTimer); presenceTimer = null; if (heartbeat) clearInterval(heartbeat); heartbeat = null; const currentAgent = agent; agent = null; currentAgent?.close(); if (!presenceAccepted) rejectConnected(new Error( opened ? "remote workspace agent connection closed before presence acknowledgement" : "remote workspace agent connection closed before opening", )); settleClosed(); }); return { connected, closed, stop() { if (stopped) return; stopped = true; if (presenceTimer) clearTimeout(presenceTimer); presenceTimer = null; if (heartbeat) clearInterval(heartbeat); heartbeat = null; const currentAgent = agent; agent = null; currentAgent?.close(); if (!presenceAccepted) rejectConnected(new Error("remote workspace agent stopped")); settleClosed(); try { socket.close(1000, "remote workspace agent stopped"); } catch { /* CONNECTING sockets differ by runtime */ } }, }; } function waitForReconnect(delayMs: number, signal: AbortSignal): Promise<void> { if (signal.aborted) return Promise.resolve(); return new Promise(resolve => { const timer = setTimeout(finish, delayMs); function finish() { clearTimeout(timer); signal.removeEventListener("abort", finish); resolve(); } signal.addEventListener("abort", finish, { once: true }); }); } export async function runRemoteWorkspaceAgent(options: { state: RemoteWorkspaceDeviceState; signal: AbortSignal; webSocketFactory?: RemoteWorkspaceWebSocketFactory; commandRunner?: RemoteWorkspaceCommandRunner | null; onStatus?: (status: RemoteWorkspaceAgentRunStatus) => void; minReconnectMs?: number; maxReconnectMs?: number; random?: () => number; }): Promise<void> { const state = parseRemoteWorkspaceDeviceState(options.state); const minimum = options.minReconnectMs ?? 500; const maximum = options.maxReconnectMs ?? 15_000; if (!Number.isSafeInteger(minimum) || !Number.isSafeInteger(maximum) || minimum < 10 || maximum < minimum) { throw new Error("invalid remote workspace reconnect policy"); } let attempt = 0; let delayMs = minimum; while (!options.signal.aborted) { attempt += 1; options.onStatus?.({ state: "connecting", attempt }); const handle = connectRemoteWorkspaceAgent({ state, ...(options.webSocketFactory ? { webSocketFactory: options.webSocketFactory } : {}), ...(options.commandRunner !== undefined ? { commandRunner: options.commandRunner } : {}), }); const stop = () => handle.stop(); options.signal.addEventListener("abort", stop, { once: true }); try { await handle.connected; delayMs = minimum; options.onStatus?.({ state: "online", attempt }); await handle.closed; } catch (error) { handle.stop(); if (!options.signal.aborted) { options.onStatus?.({ state: "reconnecting", attempt, message: error instanceof Error ? error.message : "remote workspace connection failed", }); } } finally { options.signal.removeEventListener("abort", stop); } if (options.signal.aborted) break; options.onStatus?.({ state: "reconnecting", attempt }); const random = Math.min(1, Math.max(0, (options.random ?? Math.random)())); const jitteredDelay = Math.max(10, Math.round(delayMs * (0.8 + random * 0.4))); await waitForReconnect(jitteredDelay, options.signal); delayMs = Math.min(maximum, delayMs * 2); } options.onStatus?.({ state: "stopped", attempt }); }