UNPKG

@bitkyc08/opencodex

Version:

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

460 lines (433 loc) • 22.8 kB
/** * A Remote Link Child's view of its Home (#6957): the Home's name for refusal and status text, * the Home's OpenCodex-owned Codex settings, and authenticated read-only management reads. * * Every read goes through the connection-bound link relay (`fetchBoundLinkRelay`): the link key * is sent only after the listener on the tunnel port proves it holds the same link identity, so a * process that took the tunnel port never sees the key. */ import { chmodSync, lstatSync, mkdirSync, readFileSync, unlinkSync } from "node:fs"; import { dirname, join } from "node:path"; import { parseHomeRouteIntentDocument, parseRouteClientOutcomes, ROUTE_CLIENT_IDS, routeIntentDigest, routeClientOutcomesForPeer, type HomeRouteIntentDocument, type RouteClientOutcome } from "../link/route-intent"; import { atomicWriteFile, isMissingPathError } from "../config/atomic-write"; import { readBoundedResponseBytes } from "../lib/bounded-body"; import { assertNotRealHomeUnderTest } from "../lib/test-home-guard"; import { hardenSecretDir } from "../lib/windows-secret-acl"; import { codexSettingsDigest, parseHomeCodexSettingsDocument, type HomeCodexSettingsDocument, } from "../link/codex-settings"; import { LINK_CHILD_PARITY_PATH, type LinkChildParityReport } from "../link/child-parity"; import { LINK_CODEX_SETTINGS_PATH, LINK_ROUTE_INTENT_PATH, LINK_MANAGEMENT_PREFIX, linkManagementReadAllowed, } from "../link/management-routes"; import { linkDir } from "../link/paths"; import type { OcxClientConnectionConfig } from "../types"; import { withClientLifecycle } from "./lifecycle-lock"; import { fetchBoundLinkRelay } from "./link-relay-transport"; import { readClientLinkState, type ClientLinkState } from "./link-state"; const RECORD_MAX_BYTES = 64 * 1024; function isIsoTimestamp(value: unknown): value is string { if (typeof value !== "string" || value.length !== 24) return false; const parsed = Date.parse(value); return Number.isFinite(parsed) && new Date(parsed).toISOString() === value; } const SETTINGS_MAX_BYTES = 64 * 1024; const READ_TIMEOUT_MS = 10_000; export interface LinkHomeDeps { /** Trusted complete-send test seam; production uses the connection-bound transport. */ fetchImpl?: typeof fetch; timeoutMs?: number; } /** The connection fields a Home read needs; connect calls these before its state is committed. */ export type LinkHomeConnection = Pick<OcxClientConnectionConfig, "transport" | "link" | "apiKeyId">; export interface HomeCodexSettingsRecord { linkId: string; fetchedAt: string; /** * When this Child first applied these settings (OCX-6, P5). A re-apply of the same digest for * the same link keeps it, so an idempotent `ocx sync` never makes a fresh runtime look stale. */ appliedAt: string; document: HomeCodexSettingsDocument; } export function homeCodexSettingsPath(): string { return join(linkDir(), "home-codex-settings.json"); } function linkTarget(connection: LinkHomeConnection, admissionKey: string) { if (connection.transport !== "link" || !connection.link) throw new Error("not a Remote Link Child"); return { tunnelPort: connection.link.tunnelPort, linkId: connection.link.linkId, apiKeyId: connection.apiKeyId, admissionKey, }; } /** The last applied Home settings for this link, or null when absent, malformed or another link's. */ export function readHomeCodexSettingsRecord(linkId: string, path = homeCodexSettingsPath()): HomeCodexSettingsRecord | null { try { const stat = lstatSync(path); if (!stat.isFile() || stat.size > RECORD_MAX_BYTES) return null; const raw = JSON.parse(readFileSync(path, "utf8")) as unknown; if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null; const record = raw as Record<string, unknown>; if (record.linkId !== linkId || typeof record.fetchedAt !== "string" || Number.isNaN(Date.parse(record.fetchedAt))) return null; const document = parseHomeCodexSettingsDocument(record.document); // Records written before OCX-6 carry no apply time; their read time is the closest one. const appliedAt = isIsoTimestamp(record.appliedAt) ? record.appliedAt : record.fetchedAt; return document ? { linkId, fetchedAt: record.fetchedAt, appliedAt, document } : null; } catch { return null; } } export function writeHomeCodexSettingsRecord(record: HomeCodexSettingsRecord, path = homeCodexSettingsPath()): void { const dir = linkDir(); assertNotRealHomeUnderTest(join(dir, "..")); mkdirSync(dir, { recursive: true, mode: 0o700 }); if (process.platform === "win32") hardenSecretDir(dir, { required: true }); else chmodSync(dir, 0o700); atomicWriteFile(path, `${JSON.stringify(record, null, 2)}\n`); if (process.platform !== "win32") chmodSync(path, 0o600); } export function clearHomeCodexSettingsRecord(path = homeCodexSettingsPath()): void { try { unlinkSync(path); } catch (error) { if (!isMissingPathError(error)) throw error; } } /** * The record an apply of `document` produces: the apply time is `appliedAt` unless the previous * record is for the same link and the same settings digest, in which case it is kept. */ export function homeCodexSettingsReceipt( linkId: string, document: HomeCodexSettingsDocument, fetchedAt: string, appliedAt: string, previous: HomeCodexSettingsRecord | null = readHomeCodexSettingsRecord(linkId), ): HomeCodexSettingsRecord { const unchanged = previous !== null && previous.linkId === linkId && codexSettingsDigest(previous.document.settings) === codexSettingsDigest(document.settings); return { linkId, fetchedAt, appliedAt: unchanged ? previous.appliedAt : appliedAt, document }; } export function linkApplyLockPath(): string { return join(linkDir(), "apply-lock.sqlite"); } /** * Before an apply writes settings that differ from the recorded ones, withdraw the record, so a * failed injection or record write reads as "no recorded apply" instead of the previous digest * (OCX-6). Re-applying the same settings keeps it. Returns whether the record was withdrawn. */ export function withdrawChangingHomeCodexSettingsRecord(linkId: string, document: HomeCodexSettingsDocument): boolean { const previous = readHomeCodexSettingsRecord(linkId); if (!previous || codexSettingsDigest(previous.document.settings) === codexSettingsDigest(document.settings)) return false; clearHomeCodexSettingsRecord(); return true; } /** The apply lock is held by another apply or a link connect in flight; nothing ran. */ export class LinkApplyBusyError extends Error { readonly code = "link_apply_busy"; constructor() { super("another Home settings apply is in progress on this machine; retry when it finishes"); this.name = "LinkApplyBusyError"; } } /** * Serialize applies of the Home's settings on this Child, from the Home read through the Codex * injection to the record write, so a receipt always names the settings the injection wrote. * Outermost in the client lock order (before N, L and C); a second apply fails fast. */ export async function withLinkApply<T>(work: () => Promise<T>, lockPath: string = linkApplyLockPath()): Promise<T> { const dir = linkDir(); assertNotRealHomeUnderTest(join(dir, "..")); // Only a refusal of the apply lock itself means "another apply"; an error from inside `work` // (including a busy ordinary lifecycle lock) passes through as itself. let entered = false; try { return await withClientLifecycle(() => { entered = true; return work(); }, { lockPath }); } catch (error) { if (!entered && error instanceof Error && error.message === "client_lifecycle_busy") { throw new LinkApplyBusyError(); } throw error; } } /** * The Home's name as this Child knows it: the SSH alias of a Child-initiated link, else the * host name the Home published with its Codex settings, else null ("its Home"). */ export function linkHomeName( connection: OcxClientConnectionConfig, readSidecar: () => ClientLinkState | null = readClientLinkState, ): string | null { const linkId = connection.link?.linkId; if (!linkId) return null; try { const sidecar = readSidecar(); if (sidecar && sidecar.linkId === linkId) return sidecar.alias; } catch { /* an unreadable sidecar names nothing */ } return readHomeCodexSettingsRecord(linkId)?.document.home.name ?? null; } /** "Home home-box" or "its Home": the phrase every link Child message uses. */ export function linkHomePhrase( connection: OcxClientConnectionConfig, readSidecar?: () => ClientLinkState | null, ): string { const name = linkHomeName(connection, readSidecar); return name ? `Home ${name}` : "its Home"; } /** * A `fetch` for the existing data-plane reads (`/v1/hub-state`, `/v1/usage`) that sends each * request through the connection-bound link relay, so the link key reaches only the Home. */ export function linkBoundFetch(connection: LinkHomeConnection, admissionKey: string): typeof fetch { const target = linkTarget(connection, admissionKey); return ((input: RequestInfo | URL, init?: RequestInit) => { // A Request keeps its method, headers and signal unless init overrides them. const request = input instanceof Request ? input : null; const url = request ? request.url : String(input); return fetchBoundLinkRelay(target, url, { ...(request ? { method: request.method, headers: request.headers, signal: request.signal } : {}), ...(init ?? {}), redirect: "manual", }); }) as typeof fetch; } /** * One authenticated, read-only management read on the Home. `path` is a Home management path * with an optional query (`/api/providers`); anything outside the shared allowlist throws before * a request is built. */ export async function fetchLinkHomeManagement( connection: LinkHomeConnection, admissionKey: string, path: string, init: { method?: "GET" | "HEAD"; signal?: AbortSignal } = {}, deps: LinkHomeDeps = {}, ): Promise<Response> { const method = init.method ?? "GET"; const local = new URL(path, "http://link.invalid"); if (local.origin !== "http://link.invalid" || !linkManagementReadAllowed(method, local.pathname, local.searchParams)) { throw new Error("path is not readable over the Remote Link"); } const target = linkTarget(connection, admissionKey); const destination = `http://127.0.0.1:${target.tunnelPort}${LINK_MANAGEMENT_PREFIX}${local.pathname}${local.search}`; const signal = init.signal ? AbortSignal.any([init.signal, AbortSignal.timeout(deps.timeoutMs ?? READ_TIMEOUT_MS)]) : AbortSignal.timeout(deps.timeoutMs ?? READ_TIMEOUT_MS); const request: RequestInit = { method, headers: { accept: "application/json", authorization: `Bearer ${admissionKey}` }, redirect: "manual", signal, }; return deps.fetchImpl ? deps.fetchImpl(destination, request) : fetchBoundLinkRelay(target, destination, request); } export type HomeCodexSettingsFetch = | { kind: "fresh"; document: HomeCodexSettingsDocument } | { kind: "unsupported" } | { kind: "failed"; reason: string }; export async function fetchHomeCodexSettings( connection: LinkHomeConnection, admissionKey: string, deps: LinkHomeDeps = {}, ): Promise<HomeCodexSettingsFetch> { let response: Response; try { const target = linkTarget(connection, admissionKey); const destination = `http://127.0.0.1:${target.tunnelPort}${LINK_CODEX_SETTINGS_PATH}`; const request: RequestInit = { method: "GET", headers: { accept: "application/json", authorization: `Bearer ${admissionKey}` }, redirect: "manual", signal: AbortSignal.timeout(deps.timeoutMs ?? READ_TIMEOUT_MS), }; response = deps.fetchImpl ? await deps.fetchImpl(destination, request) : await fetchBoundLinkRelay(target, destination, request); } catch (error) { return { kind: "failed", reason: error instanceof Error && error.name === "LinkRelayAuthenticationError" ? error.message : "the Home is unreachable" }; } if (response.status === 404) { try { await response.body?.cancel(); } catch { /* best effort */ } return { kind: "unsupported" }; } if (!response.ok) { try { await response.body?.cancel(); } catch { /* best effort */ } return { kind: "failed", reason: `the Home answered HTTP ${response.status}` }; } try { const result = await readBoundedResponseBytes(response, { maxBytes: SETTINGS_MAX_BYTES, signal: AbortSignal.timeout(deps.timeoutMs ?? READ_TIMEOUT_MS) }); if (result.oversized) return { kind: "failed", reason: "the Home's settings exceeded the allowed size" }; const document = parseHomeCodexSettingsDocument(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(result.bytes))); return document ? { kind: "fresh", document } : { kind: "failed", reason: "the Home returned an unreadable settings document" }; } catch { return { kind: "failed", reason: "the Home returned an unreadable settings document" }; } } export type HomeCodexSettingsSource = | { source: "home"; document: HomeCodexSettingsDocument; fetchedAt: string } | { source: "cached"; document: HomeCodexSettingsDocument; fetchedAt: string; reason: string } | { source: "local"; reason: string }; /** * The settings a sync applies. A failed read reuses the last record for this link so a brief * outage never flips the Child back to its local values; a Home that predates the route leaves * the Child's local values in place and says so. A fresh read is NOT recorded here: the caller * records it with `recordHomeCodexSettings` only after the injection that applies it succeeds, * because `ocx status` reads the record as "applied". */ export async function resolveHomeCodexSettings( connection: LinkHomeConnection, admissionKey: string, deps: LinkHomeDeps & { now?: () => Date; withWriteGuard?: <T>(write: () => T) => T } = {}, ): Promise<HomeCodexSettingsSource> { const linkId = connection.link?.linkId; if (!linkId) return { source: "local", reason: "not a Remote Link Child" }; const fetched = await fetchHomeCodexSettings(connection, admissionKey, deps); if (fetched.kind === "fresh") { return { source: "home", document: fetched.document, fetchedAt: (deps.now ?? (() => new Date()))().toISOString() }; } if (fetched.kind === "unsupported") { if (deps.withWriteGuard) deps.withWriteGuard(clearHomeCodexSettingsRecord); else clearHomeCodexSettingsRecord(); return { source: "local", reason: "the Home does not publish Codex settings; upgrade the Home" }; } const cached = readHomeCodexSettingsRecord(linkId); return cached ? { source: "cached", document: cached.document, fetchedAt: cached.fetchedAt, reason: fetched.reason } : { source: "local", reason: fetched.reason }; } /** * Record settings a successful injection applied and return the committed record; null when the * source was not a fresh Home read. A write failure throws: the caller reports it, because * `ocx status` and the Home read this record as the proof of what was applied. */ export function recordHomeCodexSettings( linkId: string, settings: HomeCodexSettingsSource, now: () => Date = () => new Date(), ): HomeCodexSettingsRecord | null { if (settings.source !== "home") return null; const record = homeCodexSettingsReceipt(linkId, settings.document, settings.fetchedAt, now().toISOString()); writeHomeCodexSettingsRecord(record); return record; } /** * Tell the Home what this Child last applied and when its runtime started (OCX-6). Resolves to * `"accepted"`, `"unsupported"` for a Home that predates the route, `"schema-rejected"` * for a payload/schema refusal, or `"failed"` for every other refusal/transport failure. */ export async function sendLinkChildParityReport( connection: LinkHomeConnection, admissionKey: string, report: LinkChildParityReport, deps: LinkHomeDeps = {}, ): Promise<"accepted" | "unsupported" | "schema-rejected" | "failed"> { let response: Response; try { const target = linkTarget(connection, admissionKey); const destination = `http://127.0.0.1:${target.tunnelPort}${LINK_CHILD_PARITY_PATH}`; const body = JSON.stringify({ ...report, ...(report.routeClientOutcomes === undefined ? {} : { routeClientOutcomes: routeClientOutcomesForPeer(report.routeClientOutcomes), }) }); const request: RequestInit = { method: "POST", headers: { accept: "application/json", authorization: `Bearer ${admissionKey}`, "content-type": "application/json", "content-length": String(Buffer.byteLength(body)), }, body, redirect: "manual", signal: AbortSignal.timeout(deps.timeoutMs ?? READ_TIMEOUT_MS), }; response = deps.fetchImpl ? await deps.fetchImpl(destination, request) : await fetchBoundLinkRelay(target, destination, request); } catch { return "failed"; } try { await response.body?.cancel(); } catch { /* best effort */ } if (response.status === 404) return "unsupported"; if ([400, 413, 422].includes(response.status)) return "schema-rejected"; return response.status === 204 ? "accepted" : "failed"; } export interface HomeRouteIntentRecord { linkId: string; fetchedAt: string; appliedAt: string; document: HomeRouteIntentDocument; appliedRouteIntentDigest: string | null; routeClientOutcomes: RouteClientOutcome[]; } export function homeRouteIntentPath(): string { return join(linkDir(), "home-route-intent.json"); } function completedRouteIntentDigest(document: HomeRouteIntentDocument, outcomes: RouteClientOutcome[]): string | null { return outcomes.length === ROUTE_CLIENT_IDS.length && new Set(outcomes.map(row => row.client)).size === ROUTE_CLIENT_IDS.length && outcomes.every(row => row.outcome === "current" && !(row.source === "local" && document.clients[row.client].enabled)) ? routeIntentDigest(document) : null; } function parseHomeRouteIntentRecord(value: unknown, linkId: string): HomeRouteIntentRecord | null { if (!value || typeof value !== "object" || Array.isArray(value)) return null; const raw = value as Record<string, unknown>; const fields = ["linkId", "fetchedAt", "appliedAt", "document", "appliedRouteIntentDigest", "routeClientOutcomes"]; if (Object.keys(raw).length !== fields.length || Object.keys(raw).some(key => !fields.includes(key)) || raw.linkId !== linkId || !/^lnk_[0-9a-f]{16}$/.test(linkId) || !isIsoTimestamp(raw.fetchedAt) || !isIsoTimestamp(raw.appliedAt)) return null; const document = parseHomeRouteIntentDocument(raw.document); const outcomes = parseRouteClientOutcomes(raw.routeClientOutcomes); if (!document || !outcomes || raw.appliedRouteIntentDigest !== completedRouteIntentDigest(document, outcomes)) return null; return { linkId, fetchedAt: raw.fetchedAt, appliedAt: raw.appliedAt, document, appliedRouteIntentDigest: raw.appliedRouteIntentDigest as string | null, routeClientOutcomes: outcomes }; } export function readHomeRouteIntentRecord(linkId: string, path = homeRouteIntentPath()): HomeRouteIntentRecord | null { try { const stat = lstatSync(path); if (!stat.isFile() || stat.size > RECORD_MAX_BYTES) return null; return parseHomeRouteIntentRecord(JSON.parse(readFileSync(path, "utf8")), linkId); } catch { return null; } } export function writeHomeRouteIntentRecord(record: HomeRouteIntentRecord, path = homeRouteIntentPath()): void { const parsed = parseHomeRouteIntentRecord(record, record.linkId); if (!parsed) throw new Error("invalid Home route intent receipt"); const dir = dirname(path); assertNotRealHomeUnderTest(dir); const body = `${JSON.stringify(parsed, null, 2)}\n`; if (Buffer.byteLength(body) > RECORD_MAX_BYTES) throw new Error("Home route intent receipt too large"); mkdirSync(dir, { recursive: true, mode: 0o700 }); if (process.platform === "win32") hardenSecretDir(dir, { required: true }); else chmodSync(dir, 0o700); atomicWriteFile(path, body); if (process.platform !== "win32") chmodSync(path, 0o600); } export function clearHomeRouteIntentRecord(path = homeRouteIntentPath()): void { assertNotRealHomeUnderTest(dirname(path)); try { unlinkSync(path); } catch (error) { if (!isMissingPathError(error)) throw error; } } /** Call only after the materializer has collected the outcomes; partial apply never claims the digest. */ export function homeRouteIntentReceipt( linkId: string, document: HomeRouteIntentDocument, fetchedAt: string, appliedAt: string, routeClientOutcomes: RouteClientOutcome[], previous: HomeRouteIntentRecord | null = readHomeRouteIntentRecord(linkId), ): HomeRouteIntentRecord { const digest = completedRouteIntentDigest(document, routeClientOutcomes); const unchanged = digest !== null && previous?.linkId === linkId && previous.appliedRouteIntentDigest === digest; return { linkId, document, fetchedAt, appliedAt: unchanged ? previous.appliedAt : appliedAt, appliedRouteIntentDigest: digest, routeClientOutcomes }; } export type HomeRouteIntentFetch = { kind: "fresh"; document: HomeRouteIntentDocument } | { kind: "unsupported" } | { kind: "failed"; reason: string }; export async function fetchHomeRouteIntent(connection: LinkHomeConnection, admissionKey: string, deps: LinkHomeDeps = {}): Promise<HomeRouteIntentFetch> { let response: Response; try { const target = linkTarget(connection, admissionKey); const destination = `http://127.0.0.1:${target.tunnelPort}${LINK_ROUTE_INTENT_PATH}`; const request: RequestInit = { method: "GET", headers: { accept: "application/json", authorization: `Bearer ${admissionKey}` }, redirect: "manual", signal: AbortSignal.timeout(deps.timeoutMs ?? READ_TIMEOUT_MS) }; response = deps.fetchImpl ? await deps.fetchImpl(destination, request) : await fetchBoundLinkRelay(target, destination, request); } catch { return { kind: "failed", reason: "the Home route intent is unreachable" }; } if (!response.ok) { try { await response.body?.cancel(); } catch { /* best effort */ } return response.status === 404 ? { kind: "unsupported" } : { kind: "failed", reason: `the Home answered HTTP ${response.status}` }; } try { const read = await readBoundedResponseBytes(response, { maxBytes: SETTINGS_MAX_BYTES, signal: AbortSignal.timeout(deps.timeoutMs ?? READ_TIMEOUT_MS) }); if (read.oversized) return { kind: "failed", reason: "the Home route intent exceeded the allowed size" }; const document = parseHomeRouteIntentDocument(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(read.bytes))); return document ? { kind: "fresh", document } : { kind: "failed", reason: "the Home returned an unreadable route intent document" }; } catch { return { kind: "failed", reason: "the Home returned an unreadable route intent document" }; } }