@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
299 lines (281 loc) • 14.9 kB
text/typescript
/** Opt-in consistency guard for a desktop-approved stop. Not a consent proof. */
import { waitForExit } from "../lib/process-control";
import { waitForPortAvailable } from "../server/ports";
import { probeEndpointLiveness, probeHostname } from "../server/proxy-liveness";
import type { GuardedManagerTarget } from "../service/guarded-manager-target";
import type { ResolveJson } from "./resolve";
import { STOP_SUMMARY_SCHEMA, stopReasonFields, type StopOutcome, type StopRunRecord, type StopServiceOutcome, type StopServiceReason } from "./stop-report";
type MaybePromise<T> = T | Promise<T>;
export interface StopApproval {
pid: number;
port: number;
hostname: string;
configHome: string;
cliVersion: string;
compatibilityToken: string;
}
export interface GuardedStopSnapshot {
approval: StopApproval;
manager: Exclude<GuardedManagerTarget, { kind: "unknown" }>;
}
/**
* What the tracked-record check can report: the verified target, null when the
* caller cannot name a cause (the pre-diagnostics shape), or the fixed cause of
* the single check that failed. The cause is a fixed sentence fragment from the
* inspection probe -- it carries no path, command line, stderr, or token.
*/
export type TrackedRuntimeCheck =
| { pid: number; port: number; hostname: string | undefined }
| { untracked: string }
| null;
function sameGuardedManager(
expected: GuardedStopSnapshot["manager"],
current: GuardedManagerTarget,
): boolean {
if (expected.kind === "absent") return current.kind === "absent";
if (expected.kind === "bound-stray") {
// The bound wrapper set is the identity (#7771): same PIDs with the same creation times.
if (current.kind !== "bound-stray" || current.pid !== expected.pid) return false;
const key = (set: { pid: number; startTime: number }[]) =>
set.map(wrapper => `${wrapper.pid}@${wrapper.startTime}`).sort().join(",");
return key(current.wrappers) === key(expected.wrappers);
}
return current.kind === "bound" && current.pid === expected.pid
&& current.managerPid === expected.managerPid && current.backend === expected.backend;
}
export type StopApprovalParse =
| { ok: true; json: boolean; approval: StopApproval | null; deadlineMs: number | null }
| { ok: false };
/**
* --deadline-ms <n> (#7771): a positive decimal number of milliseconds, measured from this
* process's start; at most once, anywhere in the argument list. Removed here so the
* approval grammar below stays exactly what it was.
*/
function takeStopDeadline(argv: string[]): { argv: string[]; deadlineMs: number | null } | null {
const at = argv.indexOf("--deadline-ms");
if (at < 0) return { argv, deadlineMs: null };
if (argv.indexOf("--deadline-ms", at + 1) >= 0) return null;
const raw = argv[at + 1];
if (raw === undefined || !/^\d+$/.test(raw)) return null;
const value = Number(raw);
if (!Number.isSafeInteger(value) || value <= 0) return null;
return { argv: [...argv.slice(0, at), ...argv.slice(at + 2)], deadlineMs: value };
}
export function parseStopApproval(input: string[]): StopApprovalParse {
const taken = takeStopDeadline(input);
if (!taken) return { ok: false };
const { argv, deadlineMs } = taken;
if (argv.length === 0) return { ok: true, json: false, approval: null, deadlineMs };
if (argv.every(arg => arg === "--json")) return { ok: true, json: true, approval: null, deadlineMs };
const names = ["--expect-pid", "--expect-port", "--expect-hostname",
"--expect-config-home", "--expect-cli-version", "--expect-compatibility-token"];
if (argv.filter(arg => arg === "--json").length !== 1) return { ok: false };
const values = new Map<string, string>();
for (let index = 0; index < argv.length; index += 1) {
const flag = argv[index]!;
if (flag === "--json") continue;
if (!names.includes(flag) || values.has(flag) || index + 1 >= argv.length) return { ok: false };
values.set(flag, argv[++index]!);
}
if (values.size !== names.length) return { ok: false };
const integer = (value: string | undefined, max: number): number | null => {
if (!value || !/^\d+$/.test(value)) return null;
const parsed = Number(value);
return Number.isSafeInteger(parsed) && parsed > 0 && parsed <= max ? parsed : null;
};
const pid = integer(values.get("--expect-pid"), Number.MAX_SAFE_INTEGER);
const port = integer(values.get("--expect-port"), 65535);
const compatibilityToken = values.get("--expect-compatibility-token") ?? "";
const configHome = values.get("--expect-config-home") ?? "";
const cliVersion = values.get("--expect-cli-version") ?? "";
if (pid === null || port === null || !/^[a-f0-9]{64}$/.test(compatibilityToken)
|| !configHome || !cliVersion) return { ok: false };
return { ok: true, json: true, deadlineMs, approval: {
pid, port, hostname: values.get("--expect-hostname") ?? "",
configHome, cliVersion, compatibilityToken,
} };
}
export function matchesStopApproval(expected: StopApproval, now: ResolveJson): boolean {
return stopApprovalMismatch(expected, now) === null;
}
/**
* The single guard fact that no longer holds, or null when everything still matches.
* The guarded stop collapses every re-verification into one `approval-changed` outcome;
* without the specific check, a desktop log cannot tell a genuine ownership or token
* drift from a transient probe failure on an unchanged runtime.
*/
export function stopApprovalMismatch(expected: StopApproval, now: ResolveJson): string | null {
if (now.schema !== "ocx-resolve/1") return "the resolve contract changed";
if (now.liveness.status !== "live") return `the approved runtime is no longer live (${now.liveness.status})`;
if (now.liveness.pid !== expected.pid) {
return `the live PID is now ${now.liveness.pid ?? "unverified"} (approved ${expected.pid})`;
}
if (now.liveness.port !== expected.port) return `the live port is now ${now.liveness.port} (approved ${expected.port})`;
if (now.port.effective !== expected.port) return `the effective port is now ${now.port.effective} (approved ${expected.port})`;
if ((now.liveness.hostname ?? "") !== expected.hostname) return "the bind hostname changed";
if (now.liveness.role === "client") return "the runtime now routes as a client";
if (now.configHome !== expected.configHome) return "the config home changed";
if (now.cliVersion !== expected.cliVersion) return `the resolving CLI is now ${now.cliVersion} (approved ${expected.cliVersion})`;
if (now.ownership.kind === "unknown") return "the ownership claim could not be re-verified";
if (now.takeover.kind !== "supported") {
return `takeover compatibility is now blocked (${now.takeover.reason})`;
}
if (now.takeover.token !== expected.compatibilityToken) return "the compatibility fingerprint changed";
return null;
}
export function approvalChanged(detail?: string, serviceStopReason?: StopServiceReason): StopOutcome {
return { ok: false, summary: {
schema: STOP_SUMMARY_SCHEMA, ok: false, outcome: "approval-changed", exitCode: 1,
runtimeDown: false, service: "absent", proxy: "unknown", sharedTeardown: "skipped",
...(detail ? { detail } : {}),
...stopReasonFields({ serviceStopReason }),
message: `The approved runtime or managing CLI changed${detail ? `: ${detail}` : ""}; no stop was attempted.`,
} };
}
export function managerStillActive(
service: StopServiceOutcome,
record?: Pick<StopRunRecord, "proxy" | "sharedTeardown" | "serviceStopReason" | "portHeldByForeign">,
): StopOutcome {
return { ok: false, summary: {
schema: STOP_SUMMARY_SCHEMA, ok: false, outcome: "manager-still-active", exitCode: 1,
runtimeDown: false, service,
proxy: record?.proxy ?? "unknown", sharedTeardown: record?.sharedTeardown ?? "skipped",
...stopReasonFields(record ?? {}),
message: "The approved runtime and service manager could not both be confirmed stopped.",
} };
}
export async function runApprovedStop(
expected: StopApproval,
read: () => Promise<ResolveJson | null>,
tracked: () => TrackedRuntimeCheck,
managerTarget: () => MaybePromise<GuardedManagerTarget>,
stop: (snapshot: GuardedStopSnapshot) => Promise<StopOutcome>,
): Promise<StopOutcome> {
let snapshot: GuardedStopSnapshot | null = null;
try {
const now = await read();
const target = tracked();
const manager = await managerTarget();
if (now === null) return approvalChanged("the runtime could not be re-resolved");
const mismatch = stopApprovalMismatch(expected, now);
if (mismatch !== null) return approvalChanged(mismatch);
if (target === null) return approvalChanged("the tracked runtime record could not be verified");
if ("untracked" in target) {
return approvalChanged(`the tracked runtime record could not be verified (${target.untracked})`);
}
if (target.pid !== expected.pid || target.port !== expected.port
|| (target.hostname === undefined ? expected.hostname !== "127.0.0.1" : target.hostname !== expected.hostname)) {
return approvalChanged("the tracked runtime record changed");
}
if (manager.kind === "unknown") {
return approvalChanged(`the service manager could not be re-verified (${manager.reason})`, manager.stopReason);
}
if ((manager.kind === "bound" || manager.kind === "bound-stray") && manager.pid !== expected.pid) {
return approvalChanged("a different manager owns the approved runtime");
}
snapshot = { approval: expected, manager };
} catch { return approvalChanged(); }
return snapshot ? stop(snapshot) : approvalChanged();
}
const GUARDED_SETTLE_MS = 5_000;
/** Compose the existing bounded PID/port waiters, then prove health absence. */
export async function settleApprovedTarget(
approved: StopApproval,
io: {
now?: () => number;
waitExit?: (pid: number, timeoutMs: number) => boolean;
waitPort?: typeof waitForPortAvailable;
probe?: typeof probeEndpointLiveness;
} = {},
): Promise<boolean> {
const now = io.now ?? Date.now;
const deadline = now() + GUARDED_SETTLE_MS;
const remaining = () => Math.max(0, deadline - now());
if (!(io.waitExit ?? waitForExit)(approved.pid, remaining()) || remaining() <= 0) return false;
const hostname = probeHostname(approved.hostname || undefined);
if (!await (io.waitPort ?? waitForPortAvailable)(approved.port, hostname,
{ timeoutMs: remaining(), intervalMs: 50 }) || remaining() <= 0) return false;
const verdict = await (io.probe ?? probeEndpointLiveness)(
{ port: approved.port, hostname: approved.hostname || undefined },
{ timeoutMs: Math.min(250, remaining()) },
);
return verdict === "dead" && now() <= deadline;
}
export async function runGuardedManagerStep(
snapshot: GuardedStopSnapshot,
io: {
revalidateManager: () => MaybePromise<GuardedManagerTarget>;
/** Async on every platform; on Windows it is Part A of the checked stop (#7771). */
stopManager: () => MaybePromise<StopServiceOutcome>;
signalApproved: () => Promise<boolean>;
settle: () => Promise<boolean>;
/**
* Windows Part B after settle (#7771): the approved endpoint stays free for the hold
* and no wrapper of this home came back. Runs only where stopManager ran.
*/
confirmFreed?: () => Promise<boolean>;
managerState: () => Promise<"inactive" | "active" | "unknown">;
},
): Promise<{ service: StopServiceOutcome; effect: "stopped" | "approval-changed" | "manager-still-active" | "failed";
proxy: "stopped" | "unknown"; handledByProxy: boolean; detail?: string; stopReason?: StopServiceReason }> {
try {
const current = await io.revalidateManager();
if (!sameGuardedManager(snapshot.manager, current)) {
// An unprovable manager is not a proven change: name the observation failure,
// not a swap, or the stop log loses why the revalidation could not answer.
const detail = current.kind === "unknown"
? `the service manager could not be re-verified (${current.reason})`
: "the service manager changed between approval and stop";
return { service: "absent", effect: "approval-changed", proxy: "unknown", handledByProxy: false, detail,
...(current.kind === "unknown" && current.stopReason ? { stopReason: current.stopReason } : {}) };
}
} catch {
return { service: "absent", effect: "approval-changed", proxy: "unknown", handledByProxy: false,
detail: "the service manager could not be re-validated" };
}
// The order is the #7771 contract: the manager and its wrappers end first (nothing can
// relaunch the child), then the approved PID gets its graceful signal and receipt.
const managed = snapshot.manager.kind !== "absent";
const service = managed ? await io.stopManager() : "absent";
if (managed
&& service !== "stopped" && service !== "stopped-respawnable") {
return { service, effect: "manager-still-active", proxy: "unknown", handledByProxy: false };
}
let handledByProxy = false;
// A bound manager whose stop cascades to the child needs no signal: launchd and
// systemd end the job's whole process tree. A bound Task Scheduler or WinSW
// manager does not — schtasks /end can leave both the wrapper and the approved
// PID alive (#764) — so those get the same graceful signal the absent path uses,
// run AFTER the manager stop so the proxy's respawn-refusal sees the manager
// already ended (the deferral receipt still bypasses it as before).
const needsApprovedSignal = snapshot.manager.kind === "absent"
|| snapshot.manager.childNeedsSeparateStop;
if (needsApprovedSignal) {
try { handledByProxy = await io.signalApproved(); }
catch { return { service, effect: "failed", proxy: "unknown", handledByProxy }; }
}
if (!await io.settle()) {
return { service, effect: "manager-still-active", proxy: "unknown", handledByProxy };
}
if (managed && io.confirmFreed) {
try {
if (!await io.confirmFreed()) return { service, effect: "manager-still-active", proxy: "unknown", handledByProxy };
} catch { return { service, effect: "manager-still-active", proxy: "unknown", handledByProxy }; }
}
try {
if (await io.managerState() !== "inactive") {
return { service, effect: "manager-still-active", proxy: "unknown", handledByProxy };
}
} catch { return { service, effect: "manager-still-active", proxy: "unknown", handledByProxy }; }
return { service, effect: "stopped", proxy: "stopped", handledByProxy };
}
export async function guardFinalStopSummary(
record: StopRunRecord,
managerState: () => Promise<"inactive" | "active" | "unknown">,
finish: () => StopOutcome,
): Promise<StopOutcome> {
try {
if (await managerState() !== "inactive") return managerStillActive(record.service, record);
} catch { return managerStillActive(record.service, record); }
return finish();
}