@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
531 lines (501 loc) • 23.4 kB
text/typescript
/**
* Windows manager-to-proxy binding for consent-bound desktop stops.
*
* guarded-manager-target probes launchd and systemd registrations and proves the
* running manager owns the approved PID through its parent chain. Windows had no
* such proof: any registered Task Scheduler task or WinSW service made the whole
* platform "unknown", so a consent-bound stop always answered approval-changed
* while resolve still reported takeover supported — a promise the stop path could
* not keep. This module performs the Windows half of the same contract: prove the
* manager, or say exactly why it cannot be proven.
*
* The evidence mirrors what a careful operator checks by hand:
*
* - Task Scheduler: the task must be present, its registered definition must be a
* recognized OpenCodex layout (current healthy or the exact legacy shape — never
* a hand-edited or foreign task under the fixed name), it must be RUNNING, and
* the approved PID's ancestor chain must contain a wrapper process whose command
* line carries this home's canonical launcher/script path as a complete token.
* - WinSW: the service must be started, its registered binary path must be this
* installation's WinSW executable, and the SCM-reported service PID must be an
* ancestor of the approved PID.
* - Anything unreadable stays unknown: a manager that cannot be proven stays
* untouchable, exactly like a launchd job whose state cannot be read.
*/
import { execFileSync } from "node:child_process";
import { resolveTrustedWindowsPowerShellExe } from "../lib/windows-elevation";
import { cachedCurrentWindowsIdentity, resolveCurrentWindowsPrincipal, WINDOWS_PRINCIPAL_LOOKUP_TIMEOUT_MS } from "../lib/windows-user-principal";
import { statusWinswRaw, winswExePath, WINSW_SERVICE_ID, type WinswStatus } from "../lib/winsw";
import type { GuardedManagerStopped, GuardedManagerTarget } from "./guarded-manager-target";
import { TASK, windowsLauncherVbsPath, windowsServiceScriptPath } from "./state";
import { probeWindowsSchedulerTask, querySchtasks, windowsWscript, type WindowsSchedulerTaskProbe } from "./windows-scheduler";
import { windowsTaskRegistrationHealthy, windowsTaskRegistrationRefreshableLegacy } from "./windows-taskxml";
/** Runtime table of one Win32 process; a null parent means the chain is unreadable. */
export interface WindowsProcessEntry {
pid: number;
parentPid: number | null;
name: string | null;
commandLine: string | null;
}
/** Get-ScheduledTask State, collapsed to what the stop decision needs. */
export type WindowsTaskState = "running" | "not-running" | "unknown";
/** SCM view of the WinSW service registration and its live process. */
export interface WindowsWinswServiceInfo {
state: string;
pid: number | null;
pathName: string | null;
}
/**
* Injectable seams for the Windows probes. Tests pass hermetic substitutes;
* production callers leave everything unset so the live queries below run. Every
* default implementation exits early off win32, mirroring probeWindowsSchedulerTask.
*/
export interface WindowsGuardedManagerDeps {
winProcs?: () => WindowsProcessEntry[] | null;
winTaskXml?: () => string;
winTaskState?: () => WindowsTaskState;
winService?: () => WindowsWinswServiceInfo | null;
winRegistrationOurs?: (xml: string, expectedUserIds: readonly string[] | null) => boolean;
winTaskUserIds?: () => readonly string[] | null;
winScriptPath?: () => string;
winLauncherPath?: () => string;
winWinswExePath?: () => string;
}
type ResolvedWindowsDeps = Required<WindowsGuardedManagerDeps>;
const POWERSHELL_TIMEOUT_MS = 5_000;
const PROCESS_SNAPSHOT_BUFFER = 16 * 1024 * 1024;
const ANCESTOR_DEPTH_LIMIT = 32;
function runPowerShell(command: string): string {
return execFileSync(resolveTrustedWindowsPowerShellExe(), [
"-NoProfile", "-NoLogo", "-NonInteractive", "-Command", command,
], {
encoding: "utf8",
stdio: ["ignore", "pipe", "pipe"],
timeout: POWERSHELL_TIMEOUT_MS,
windowsHide: true,
maxBuffer: PROCESS_SNAPSHOT_BUFFER,
});
}
/**
* One Win32_Process snapshot covering every identity question in this module:
* parent chains for the bound proof, and names and command lines for the wrapper scan.
* A null return means the enumeration itself could not run — callers fail closed,
* because an unreadable process table is not evidence that no wrapper survives.
*/
export function windowsProcessList(): WindowsProcessEntry[] | null {
if (process.platform !== "win32") return null;
try {
const output = runPowerShell(
"Get-CimInstance Win32_Process | Select-Object ProcessId,ParentProcessId,Name,CommandLine | ConvertTo-Json -Compress",
);
const trimmed = output.trim();
if (!trimmed) return [];
const parsed: unknown = JSON.parse(trimmed);
const rows = Array.isArray(parsed) ? parsed : [parsed];
const entries: WindowsProcessEntry[] = [];
for (const row of rows) {
if (typeof row !== "object" || row === null) continue;
const record = row as { ProcessId?: unknown; ParentProcessId?: unknown; Name?: unknown; CommandLine?: unknown };
const pid = Number(record.ProcessId);
const parent = Number(record.ParentProcessId);
if (!Number.isSafeInteger(pid) || pid <= 0) continue;
entries.push({
pid,
parentPid: Number.isSafeInteger(parent) && parent > 0 ? parent : null,
name: typeof record.Name === "string" ? record.Name : null,
commandLine: typeof record.CommandLine === "string" ? record.CommandLine : null,
});
}
return entries;
} catch {
return null;
}
}
/**
* The registered task's RUNNING state, read through Get-ScheduledTask whose State
* values are enum names and therefore locale-independent — parsing schtasks table
* output was rejected earlier because its values are localized.
*/
export function windowsScheduledTaskState(taskName = TASK): WindowsTaskState {
if (process.platform !== "win32") return "unknown";
try {
const output = runPowerShell(
"(Get-ScheduledTask -TaskName '" + taskName.replace(/'/g, "''") + "' -ErrorAction Stop).State",
).trim();
if (/^running$/i.test(output)) return "running";
if (/^(ready|disabled)$/i.test(output)) return "not-running";
return "unknown";
} catch {
return "unknown";
}
}
/** The registered task XML, decoded exactly like every other scheduler reader. */
export function windowsScheduledTaskXml(taskName = TASK): string {
return querySchtasks(["/query", "/tn", taskName, "/xml"]);
}
/**
* The WinSW service's SCM row. state "absent" means the query ran and the service
* is genuinely not installed; a null return means the query itself failed — the
* difference between "no manager" and "unproven manager".
*/
export function windowsWinswServiceInfo(serviceName = WINSW_SERVICE_ID): WindowsWinswServiceInfo | null {
if (process.platform !== "win32") return null;
try {
const output = runPowerShell(
"Get-CimInstance Win32_Service | Where-Object { $_.Name -eq '" + serviceName.replace(/'/g, "''") + "' } "
+ "| Select-Object ProcessId,State,PathName | ConvertTo-Json -Compress",
).trim();
if (!output) return { state: "absent", pid: null, pathName: null };
const parsed: unknown = JSON.parse(output);
const record = (Array.isArray(parsed) ? parsed[0] : parsed) as {
ProcessId?: unknown; State?: unknown; PathName?: unknown;
} | null | undefined;
if (typeof record !== "object" || record === null) return null;
const pid = Number(record.ProcessId);
return {
state: typeof record.State === "string" && record.State.trim() ? record.State.trim() : "unknown",
pid: Number.isSafeInteger(pid) && pid > 0 ? pid : null,
pathName: typeof record.PathName === "string" && record.PathName.trim() ? record.PathName.trim() : null,
};
} catch {
return null;
}
}
/** The two OpenCodex task shapes this stop may legitimately end. */
export function windowsTaskRegistrationIsOurs(
xml: string,
expectedUserIds: readonly string[] | null,
launcher = windowsLauncherVbsPath(),
): boolean {
if (expectedUserIds === null) return false;
return windowsTaskRegistrationHealthy(xml, windowsWscript(), launcher, expectedUserIds)
|| windowsTaskRegistrationRefreshableLegacy(xml, windowsWscript(), launcher);
}
export function currentWindowsTaskUserIds(): readonly string[] | null {
try {
let identity = cachedCurrentWindowsIdentity();
if (!identity) {
resolveCurrentWindowsPrincipal(WINDOWS_PRINCIPAL_LOOKUP_TIMEOUT_MS);
identity = cachedCurrentWindowsIdentity();
}
return identity ? [identity.sid, identity.name] : null;
} catch {
return null;
}
}
/**
* True when path appears in commandLine as a COMPLETE token — the same boundary
* rule the windows-service-wrappers kill list uses, ported so the read-only proof
* cannot accept a substring hit. A quoted path inside an argument string counts;
* a suffix or prefix glued to it does not.
*/
export function commandLineHasPathToken(commandLine: string | null | undefined, path: string): boolean {
if (!commandLine || !path) return false;
const haystack = commandLine.toLowerCase();
const needle = path.toLowerCase();
const boundary = (ch: string | undefined): boolean => ch === undefined || /[\s"']/.test(ch);
let index = 0;
for (;;) {
index = haystack.indexOf(needle, index);
if (index < 0) return false;
const end = index + needle.length;
if (boundary(haystack[index - 1]) && boundary(haystack[end])) return true;
index = end;
}
}
function resolveWindowsDeps(deps: WindowsGuardedManagerDeps, live: boolean): ResolvedWindowsDeps {
// "live" is false whenever the caller simulated platform win32 (tests or a future
// cross-platform probe): every unset probe then returns its least-proving answer
// instead of silently querying the host the simulation did not mean to touch.
return {
winProcs: deps.winProcs ?? (live ? windowsProcessList : () => null),
winTaskXml: deps.winTaskXml ?? (live ? () => windowsScheduledTaskXml() : () => {
throw new Error("Windows task query is unavailable in this context");
}),
winTaskState: deps.winTaskState ?? (live ? () => windowsScheduledTaskState() : () => "unknown"),
winService: deps.winService ?? (live ? () => windowsWinswServiceInfo() : () => null),
winRegistrationOurs: deps.winRegistrationOurs ?? ((xml, expectedUserIds) =>
windowsTaskRegistrationIsOurs(xml, expectedUserIds, (deps.winLauncherPath ?? windowsLauncherVbsPath)())),
winTaskUserIds: deps.winTaskUserIds ?? (live ? currentWindowsTaskUserIds : () => null),
winScriptPath: deps.winScriptPath ?? windowsServiceScriptPath,
winLauncherPath: deps.winLauncherPath ?? windowsLauncherVbsPath,
winWinswExePath: deps.winWinswExePath ?? winswExePath,
};
}
function wrapperPaths(io: ResolvedWindowsDeps): string[] {
return [io.winLauncherPath(), io.winScriptPath()];
}
/** Ancestor chain via the snapshot table — same depth cap as the POSIX walk. */
export function isDescendantOf(
ancestorPid: number,
pid: number,
processes: readonly WindowsProcessEntry[],
): boolean {
const parents = new Map(processes.map(entry => [entry.pid, entry.parentPid]));
let current = pid;
const seen = new Set<number>();
for (let depth = 0; depth < ANCESTOR_DEPTH_LIMIT; depth += 1) {
if (current === ancestorPid) return true;
if (seen.has(current)) return false;
seen.add(current);
const parent = parents.get(current);
if (parent === undefined || parent === null || parent <= 0) return false;
current = parent;
}
return false;
}
/**
* Every ancestor of pid whose own command line carries a canonical wrapper path,
* nearest first. A hit means the wscript/cmd supervision chain between the task
* action and the proxy is intact for THIS home — not just that some OpenCodex
* process exists somewhere on the box.
*/
export function ancestorWrapperPids(
pid: number,
processes: readonly WindowsProcessEntry[],
canonicalPaths: readonly string[],
): number[] {
const byPid = new Map(processes.map(entry => [entry.pid, entry]));
const found: number[] = [];
const seen = new Set<number>();
let current = pid;
for (let depth = 0; depth < ANCESTOR_DEPTH_LIMIT; depth += 1) {
const entry = byPid.get(current);
if (!entry || seen.has(current)) break;
seen.add(current);
const parent = entry.parentPid;
if (parent === null || parent <= 0) break;
const parentEntry = byPid.get(parent);
if (parentEntry?.commandLine
&& canonicalPaths.some(path => commandLineHasPathToken(parentEntry.commandLine, path))) {
found.push(parent);
}
current = parent;
}
return found;
}
/**
* Any live process whose command line carries a canonical wrapper path. A wrapper
* that survived schtasks /end keeps respawning the proxy, so the post-stop probe
* treats one as an ACTIVE manager even when the task itself reports not running.
* The enumerating probe cannot match itself — the patterns are compared in
* TypeScript, never embedded in the PowerShell text — but excluding the current
* process costs nothing if that ever changes.
*/
export function wrapperProcessesAlive(
processes: readonly WindowsProcessEntry[],
canonicalPaths: readonly string[],
): number[] {
return processes
.filter(entry => entry.pid !== process.pid && entry.commandLine
&& canonicalPaths.some(path => commandLineHasPathToken(entry.commandLine, path)))
.map(entry => entry.pid);
}
/**
* A wscript/cscript/cmd process whose command line could not be read. It may be this home's
* wrapper, and nothing can prove otherwise. Only processes tied to the approved proxy by
* ancestry count: a non-admin CIM query returns no command line for other users' and elevated
* processes, so treating every unreadable cmd.exe on the machine as a wrapper would make the
* guarded stop unreachable on an ordinary desktop.
*/
function isUnreadableWrapperCandidate(entry: WindowsProcessEntry): boolean {
return !entry.commandLine?.trim() && /^(?:wscript|cscript|cmd)\.exe$/i.test(entry.name ?? "");
}
/** Unreadable wrapper candidates among pid's ancestors, nearest first. */
export function unreadableAncestorWrapperPids(pid: number, processes: readonly WindowsProcessEntry[]): number[] {
const byPid = new Map(processes.map(entry => [entry.pid, entry]));
const found: number[] = [];
const seen = new Set<number>();
let current = pid;
for (let depth = 0; depth < ANCESTOR_DEPTH_LIMIT; depth += 1) {
const entry = byPid.get(current);
if (!entry || seen.has(current)) break;
seen.add(current);
const parent = entry.parentPid;
if (parent === null || parent <= 0) break;
const parentEntry = byPid.get(parent);
if (parentEntry && isUnreadableWrapperCandidate(parentEntry)) found.push(parent);
current = parent;
}
return found;
}
/**
* Unreadable wrapper candidates that are the former manager process or descend from it. After
* the approved child exits, such a survivor can still respawn it, so post-stop it is unknown.
*/
export function unreadableWrappersOfManager(managerPid: number, processes: readonly WindowsProcessEntry[]): number[] {
const byPid = new Map(processes.map(entry => [entry.pid, entry]));
return processes.filter(entry => {
if (!isUnreadableWrapperCandidate(entry)) return false;
let current: number | null = entry.pid;
for (let depth = 0; current !== null && current > 0 && depth < ANCESTOR_DEPTH_LIMIT; depth += 1) {
if (current === managerPid) return true;
current = byPid.get(current)?.parentPid ?? null;
}
return false;
}).map(entry => entry.pid);
}
function unknown(reason: string): GuardedManagerTarget {
return { kind: "unknown", reason };
}
function inspectWindowsSchedulerManager(
approvedPid: number,
io: ResolvedWindowsDeps,
): GuardedManagerTarget {
let xml: string;
try {
xml = io.winTaskXml();
} catch {
return unknown("the Task Scheduler registration could not be read");
}
const processes = io.winProcs();
if (processes === null) return unknown("the Windows process list could not be read");
const paths = wrapperPaths(io);
const ancestors = ancestorWrapperPids(approvedPid, processes, paths);
const strays = wrapperProcessesAlive(processes, paths);
if (unreadableAncestorWrapperPids(approvedPid, processes).length > 0) {
return unknown("a possible scheduler wrapper has an unreadable command line");
}
const state = io.winTaskState();
if (state === "unknown") return unknown("the registered task's running state could not be proven");
if (state === "not-running") {
// A task with no running instance owes nothing ONLY when no wrapper survives.
// A live wrapper outside a task instance — whether it parents the approved
// PID or not — is unaccounted supervision: schtasks /end would report success
// on the inert task while the wrapper stayed alive to respawn the proxy.
return strays.length === 0
? { kind: "absent" }
: unknown("a surviving scheduler wrapper could not be tied to the registered task");
}
if (!io.winRegistrationOurs(xml, io.winTaskUserIds())) {
return unknown("the registered task is not a recognized OpenCodex definition");
}
if (ancestors.length === 0) {
return unknown(strays.length === 0
? "the scheduler task is running but does not own the approved process"
: "a surviving scheduler wrapper does not own the approved process");
}
// schtasks /end does not reliably cascade to the wrapper's child, so the bound
// manager stop cannot be trusted to end the proxy — the approved PID still gets
// its own graceful signal afterwards.
return {
kind: "bound", pid: approvedPid, managerPid: ancestors[0]!,
backend: "scheduler", childNeedsSeparateStop: true,
};
}
function inspectWindowsWinswManager(
approvedPid: number,
io: ResolvedWindowsDeps,
): GuardedManagerTarget {
const info = io.winService();
if (info === null) return unknown("the native service could not be queried");
if (info.state !== "Running" && info.state !== "Started") {
return unknown("the native service is registered but not running (" + info.state + ")");
}
if (!info.pathName || !commandLineHasPathToken(info.pathName, io.winWinswExePath())) {
return unknown("the native service binary is not this installation's WinSW executable");
}
if (info.pid === null) return unknown("the native service PID could not be proven");
const processes = io.winProcs();
if (processes === null) return unknown("the Windows process list could not be read");
return isDescendantOf(info.pid, approvedPid, processes)
? {
kind: "bound", pid: approvedPid, managerPid: info.pid,
backend: "winsw", childNeedsSeparateStop: true,
}
: unknown("the native service does not own the approved process");
}
/**
* Windows half of inspectGuardedManagerTarget. The "live" flag tells the default
* probes whether the platform is real Windows: a simulated win32 must never fire a
* real schtasks/PowerShell query at the host, so absent probes then degrade to
* their least-proving answer — the same fail-closed shape the platform showed
* before this module existed.
*/
export function inspectWindowsGuardedManager(
approvedPid: number,
scheduler: WindowsSchedulerTaskProbe,
native: WinswStatus,
deps: WindowsGuardedManagerDeps,
live: boolean,
): GuardedManagerTarget {
const io = resolveWindowsDeps(deps, live);
if (scheduler.status === "unknown") {
return unknown("the Task Scheduler state could not be read (" + scheduler.detail + ")");
}
if (native === "unknown") {
return unknown("the native WinSW service state could not be read");
}
if (scheduler.status === "present" && native !== "nonexistent") {
// Same dual-backend conflict the install verification already refuses: either
// manager could respawn the proxy, so neither may be stopped by name alone.
return unknown("the Task Scheduler task and the native WinSW service are both registered");
}
if (scheduler.status === "present") {
return inspectWindowsSchedulerManager(approvedPid, io);
}
if (native === "started") {
return inspectWindowsWinswManager(approvedPid, io);
}
if (native === "stopped") {
// A stopped service cannot respawn anything, but a detached wrapper can.
const processes = io.winProcs();
if (processes === null) return unknown("the Windows process list could not be read");
if (unreadableAncestorWrapperPids(approvedPid, processes).length > 0) {
return unknown("a possible scheduler wrapper has an unreadable command line");
}
return wrapperProcessesAlive(processes, wrapperPaths(io)).length === 0
? { kind: "absent" }
: unknown("a surviving scheduler wrapper could not be tied to an installed manager");
}
// scheduler absent + winsw nonexistent — still have to rule out a detached wrapper.
const processes = io.winProcs();
if (processes === null) return unknown("the Windows process list could not be read");
if (unreadableAncestorWrapperPids(approvedPid, processes).length > 0) {
return unknown("a possible scheduler wrapper has an unreadable command line");
}
return wrapperProcessesAlive(processes, wrapperPaths(io)).length === 0
? { kind: "absent" }
: unknown("a surviving scheduler wrapper could not be tied to an installed manager");
}
export interface WindowsGuardedStopDeps {
scheduler?: () => WindowsSchedulerTaskProbe;
winsw?: () => WinswStatus;
winProcs?: () => WindowsProcessEntry[] | null;
winTaskState?: () => WindowsTaskState;
winScriptPath?: () => string;
winLauncherPath?: () => string;
/** The bound manager process the pre-stop proof tied to the approved proxy, when there was one. */
formerManagerPid?: number;
}
/**
* Post-stop manager check for Windows. Registration PRESENCE is the wrong question —
* schtasks /end leaves the task registered forever — so inactivity means: the task
* is not running, no wrapper process carrying this home's canonical paths survives,
* and no WinSW service is started. An unreadable probe is unknown, never inactive.
*/
export function observeWindowsGuardedManagerStopped(
deps: WindowsGuardedStopDeps = {},
live = process.platform === "win32",
): GuardedManagerStopped {
const scheduler = (deps.scheduler ?? probeWindowsSchedulerTask)();
const native = (deps.winsw ?? statusWinswRaw)();
if (scheduler.status === "unknown" || native === "unknown") return "unknown";
const procs = (deps.winProcs ?? (live ? windowsProcessList : () => null))();
if (procs === null) return "unknown";
const paths = [
(deps.winLauncherPath ?? windowsLauncherVbsPath)(),
(deps.winScriptPath ?? windowsServiceScriptPath)(),
];
if (wrapperProcessesAlive(procs, paths).length > 0) return "active";
if (native === "started") return "active";
if (scheduler.status === "present") {
const state = (deps.winTaskState ?? (live ? () => windowsScheduledTaskState() : () => "unknown"))();
if (state === "unknown") return "unknown";
if (state === "running") return "active";
}
if (deps.formerManagerPid !== undefined && unreadableWrappersOfManager(deps.formerManagerPid, procs).length > 0) {
return "unknown";
}
return "inactive";
}