@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
889 lines (844 loc) • 38.2 kB
text/typescript
import { chmodSync, lstatSync, readFileSync, writeFileSync } from "node:fs";
import { createHash } from "node:crypto";
import { win32 } from "node:path";
import { winswXmlPath } from "../lib/winsw";
import { hardenSecretPath } from "../lib/windows-secret-acl";
import { parseBakedListenPort } from "./health";
import { windowsServiceScriptPath } from "./state";
import { execFileSync } from "node:child_process";
import { existsSync, mkdirSync, mkdtempSync, rmdirSync, unlinkSync } from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join } from "node:path";
import { getConfigDir } from "../config";
import { OCX_ELEVATED_STAGING_UNREADABLE, runWindowsElevatedScheduledTaskRegistration, WindowsSchtasksError, type StagedWindowsTaskXml } from "../lib/windows-elevation";
import { defaultWinswEntry, installWinswService, statusWinswRaw, uninstallWinswService, WINSW_SERVICE_ID, type WinswStatus } from "../lib/winsw";
import { forgetEphemeralSecretDir, forgetEphemeralSecretPath, hardenElevatedStageDir, hardenElevatedStagePath, hardenSecretDir } from "../lib/windows-secret-acl";
import { recordOwnedConfigPath } from "../lib/config-ownership";
import { killWindowsSchedulerWrappers } from "../lib/windows-service-wrappers";
import { isTestHomeGuardArmed } from "../lib/test-home-guard";
import { writeServiceApiTokenFile } from "./guards";
import type { ServiceStopOutcome } from "./orchestration";
import { TASK, windowsLauncherVbsPath, windowsTaskXmlPath, serviceStatePath, writeServiceInstallState, serviceSourceDir } from "./state";
import { decodeSchtasksOutput, querySchtasks, schtasks, type WindowsSchedulerTaskProbe, schtasksErrorDetail, probeWindowsSchedulerTask, rollbackWindowsSchedulerTaskOwnedByAttempt } from "./windows-scheduler";
import { buildWindowsServiceScript, buildWindowsSchtasksCreateArgs, buildWindowsSchtasksCreateArgsForXml, buildWindowsLauncherVbs, resolvedWindowsTaskSid, buildWindowsTaskXmlDocument, windowsTaskRegistrationOwnedByAttempt, windowsTaskRegistrationHealthy } from "./windows-taskxml";
/** The `--port <n>` baked into the Task Scheduler wrapper. Windows scheduler backend. */
export function windowsListenPort(deps: { readScript?: () => string } = {}): number | null {
return parseBakedListenPort(deps.readScript ?? (() => readFileSync(windowsServiceScriptPath(), "utf8")));
}
/**
* The `--port <n>` baked into the WinSW XML's `<arguments>`. Windows native backend.
*
* Separate from {@link windowsListenPort} rather than one function branching on
* `readServiceBackend()`: the recorded backend can disagree with what is actually on
* disk (the `stale` / `backendStateMismatch` cases `deriveWindowsServiceDiagnostic`
* exists to catch), and a reader that trusted it would then read the wrong file.
* Each returns null when its own artifact is absent, so the chain needs no branch.
*/
export function winswListenPort(deps: { readXml?: () => string } = {}): number | null {
return parseBakedListenPort(deps.readXml ?? (() => readFileSync(winswXmlPath(), "utf8")));
}
/**
* Write a service definition with owner-only permissions.
*
* These files carry the outbound proxy environment (#2107), and a proxy URL routinely
* carries `user:password`. `writeFileSync` without a mode lands at 0644 under the default
* umask, so the credential would be world-readable on a shared host. Every other
* secret-bearing write in this file already uses 0600 — the service API token and the
* install state — and a service definition holding a proxy credential belongs in the same
* class.
*
* The explicit `chmodSync` is not redundant: `mode` only applies when the file is
* created, so an install over a definition left at 0644 by an earlier version would keep
* the loose mode.
*
* On Windows the POSIX bits are advisory, so the ACL is the real boundary — and whether it
* may soft-fail depends on what the definition actually contains. A definition carrying a
* proxy credential is a secret publication and fails closed like the API token and the
* install state do; one carrying only paths and a port is not worth refusing an install
* over, since before #2107 these files had no hardening at all and a failure here would
* regress a user who has no credential to protect.
*/
export function writeServiceDefinitionFile(path: string, content: string, encoding: "utf8" | "utf16le"): void {
writeFileSync(path, content, { encoding, mode: 0o600 });
try { chmodSync(path, 0o600); } catch { /* superseded by the Windows ACL below */ }
if (process.platform === "win32") {
hardenSecretPath(path, { required: definitionCarriesCredential(content) });
}
}
/**
* Does this service definition embed a credential-bearing proxy URL?
*
* Only the userinfo form leaks something: `http://user:pass@host` in any of the four proxy
* variables. A bare `http://127.0.0.1:7890` is not a secret, and treating it as one would
* make an icacls stall fail an install that had nothing to protect.
*
* The scan is over any URL in the rendered definition rather than over a `KEY=value` shape,
* because the three formats render differently — systemd writes `Environment="K=V"`, the
* plist writes `<key>K</key><string>V</string>`, and the Windows wrapper writes
* `set "K=V"`. Keying on the assignment syntax silently missed the plist.
*/
export function definitionCarriesCredential(content: string): boolean {
// A userinfo authority: scheme, then anything that is not a delimiter, then '@'.
return /[a-z][a-z0-9+.-]*:\/\/[^\s"'<>/@]+@/i.test(content);
}
// ── Windows (Task Scheduler) ──
/**
* In-place service-asset write that tolerates the transient EBUSY/EPERM/EACCES Windows
* throws while the just-ended task's cmd.exe (or an AV scanner) still holds the file.
*/
function writeServiceAssetWithRetry(path: string, content: string, encoding: "utf8" | "utf16le"): void {
for (let attempt = 0; ; attempt++) {
try {
writeServiceDefinitionFile(path, content, encoding);
return;
} catch (err) {
const code = (err as NodeJS.ErrnoException).code;
if (attempt >= 2 || (code !== "EBUSY" && code !== "EPERM" && code !== "EACCES")) throw err;
Bun.sleepSync(150);
}
}
}
/**
* Rewrite on-disk scheduler assets (script/VBS/XML) without itself registering the task.
* Fresh install creates it afterwards; repair does so only when the live definition is stale.
*/
export function writeWindowsSchedulerAssets(): void {
if (!existsSync(getConfigDir())) mkdirSync(getConfigDir(), { recursive: true });
writeServiceApiTokenFile();
const script = windowsServiceScriptPath();
writeServiceAssetWithRetry(script, buildWindowsServiceScript(), "utf8");
// UTF-16LE + BOM: a BOM-less UTF-8 VBS mis-decodes non-ASCII (e.g. Korean) profile
// paths on some WSH/codepage combinations — same contract as the task XML below.
writeServiceAssetWithRetry(windowsLauncherVbsPath(), `\uFEFF${buildWindowsLauncherVbs(script)}`, "utf16le");
writeServiceAssetWithRetry(
windowsTaskXmlPath(),
buildWindowsTaskXmlDocument(script, windowsLauncherVbsPath()),
"utf16le",
);
}
const WINDOWS_SCHEDULER_STAGE_PREFIX = "opencodex-service-stage-";
const ownedWindowsSchedulerStages = new Set<string>();
export interface WindowsSchedulerRegistrationStageDeps {
createStageDir?: () => string;
hardenDir?: (path: string) => void;
writeXml?: (path: string, contents: string) => void;
hardenPath?: (path: string) => void;
removeStageDir?: (path: string) => void;
}
function cleanupWindowsSchedulerStage(
stageDir: string,
xmlPath: string,
removeStageDir: (path: string) => void,
): void {
let cleanupError: unknown;
try {
unlinkSync(xmlPath);
forgetEphemeralSecretPath(xmlPath);
} catch (error) {
if ((error as NodeJS.ErrnoException | undefined)?.code === "ENOENT") {
forgetEphemeralSecretPath(xmlPath);
} else {
cleanupError = error;
}
}
try {
removeStageDir(stageDir);
forgetEphemeralSecretDir(stageDir);
} catch (error) {
if ((error as NodeJS.ErrnoException | undefined)?.code === "ENOENT") {
forgetEphemeralSecretDir(stageDir);
} else if (cleanupError) {
throw new AggregateError([cleanupError, error], "Task Scheduler staging cleanup failed.");
} else {
cleanupError = error;
}
}
if (cleanupError) throw cleanupError;
}
/** A staged payload set for one elevated registration, plus the way to remove it. */
export interface StagedElevatedSchedulerRegistration {
readonly xml: StagedWindowsTaskXml;
readonly expectedExisting?: StagedWindowsTaskXml;
/** Remove every staged artifact. Idempotent, so a second call after success is a no-op. */
cleanup(): void;
}
export interface ElevatedSchedulerStagingDeps {
createStageDir?: () => string;
hardenDir?: (path: string) => void;
writePayload?: (path: string, bytes: Buffer) => void;
hardenPath?: (path: string) => void;
inspect?: (path: string) => { isSymbolicLink(): boolean; isFile(): boolean; isDirectory(): boolean };
removeStageDir?: (path: string) => void;
}
/**
* Stage the captured definitions an elevated registration needs, as files rather than
* as command-line payloads (#4692).
*
* A file that an administrator process will read is itself a privilege-escalation
* surface, so three properties have to hold together and none of them is sufficient
* alone:
*
* - **Access.** The directory is created fresh by `mkdtemp`, then ACL-hardened before
* anything is written into it, so no non-administrator account can read or replace
* the payload while the UAC prompt is open. Administrators get read — never write —
* because an over-the-shoulder UAC prompt answered with a different administrator's
* credentials runs the elevated process as that admin (#4779); tamper-evidence does
* not depend on the DACL, it comes from the pinned handles and the digest below.
* Hardening the directory first is what makes the file private from the moment it
* exists.
* - **No reparse point.** Each artifact is inspected with `lstat` and rejected unless it
* is what it claims to be. `wx` already refuses to create over an existing name, which
* is the atomic step here — there is no replace path to race, because every path is
* inside a directory that did not exist a moment ago. The explicit check is what keeps
* that guarantee from depending on a reading of `O_EXCL` semantics.
* - **Pinned namespace and content.** Before UAC, the launcher opens every ancestor and
* payload without following reparse points. Ancestor handles share read/write but
* deny delete, so the namespace cannot be redirected while sibling payloads can
* still be written; payload handles deny write/delete outright. Those handles stay
* open until elevation exits. The digest then verifies the exact,
* length-bounded bytes read by the elevated process.
*
* Payloads are UTF-16LE with no BOM, and the elevated process decodes them straight into
* `Register-ScheduledTask`. What is hashed is therefore exactly what is registered, with
* no trimming step in between that the two sides could disagree about.
*/
export function stageElevatedSchedulerRegistration(
xml: string,
expectedExistingXml?: string,
deps: ElevatedSchedulerStagingDeps = {},
): StagedElevatedSchedulerRegistration {
const createStageDir = deps.createStageDir
?? (() => mkdtempSync(join(tmpdir(), WINDOWS_SCHEDULER_STAGE_PREFIX)));
const hardenDir = deps.hardenDir ?? ((path: string) => { hardenElevatedStageDir(path, { required: true }); });
const writePayload = deps.writePayload ?? ((path: string, bytes: Buffer) => {
writeFileSync(path, bytes, { flag: "wx", mode: 0o600 });
});
const hardenPath = deps.hardenPath ?? ((path: string) => { hardenElevatedStagePath(path, { required: true }); });
const inspect = deps.inspect ?? ((path: string) => lstatSync(path));
const removeStageDir = deps.removeStageDir ?? ((path: string) => { rmdirSync(path); });
const stageDir = createStageDir();
const files: string[] = [];
const cleanup = (): void => {
let failure: unknown;
for (const file of files.splice(0)) {
try {
unlinkSync(file);
forgetEphemeralSecretPath(file);
} catch (error) {
if ((error as NodeJS.ErrnoException | undefined)?.code === "ENOENT") forgetEphemeralSecretPath(file);
else if (failure === undefined) failure = error;
}
}
try {
removeStageDir(stageDir);
forgetEphemeralSecretDir(stageDir);
} catch (error) {
if ((error as NodeJS.ErrnoException | undefined)?.code === "ENOENT") forgetEphemeralSecretDir(stageDir);
else if (failure) throw new AggregateError([failure, error], "Elevated Task Scheduler staging cleanup failed.");
else failure = error;
}
if (failure) throw failure;
};
try {
try { chmodSync(stageDir, 0o700); } catch { /* required Windows ACL is authoritative */ }
const dirStats = inspect(stageDir);
if (dirStats.isSymbolicLink() || !dirStats.isDirectory()) {
throw new Error(`Refusing to stage an elevated Task Scheduler payload under a redirected path: ${stageDir}`);
}
hardenDir(stageDir);
const stage = (name: string, value: string): StagedWindowsTaskXml => {
const path = join(stageDir, name);
const bytes = Buffer.from(value, "utf16le");
writePayload(path, bytes);
files.push(path);
const stats = inspect(path);
if (stats.isSymbolicLink() || !stats.isFile()) {
throw new Error(`Refusing to stage an elevated Task Scheduler payload through a redirected path: ${path}`);
}
hardenPath(path);
return { path, byteLength: bytes.length, sha256: createHash("sha256").update(bytes).digest("hex") };
};
return {
xml: stage("register.xml", xml),
...(expectedExistingXml === undefined
? {}
: { expectedExisting: stage("expected.xml", expectedExistingXml) }),
cleanup,
};
} catch (error) {
try {
cleanup();
} catch (cleanupError) {
throw new AggregateError(
[error, cleanupError],
"Elevated Task Scheduler staging failed and could not be cleaned up.",
);
}
throw error;
}
}
/**
* Turn an elevated registration exit code into something an operator can act on.
*
* The elevated process runs hidden, so nothing it writes survives; only the exit code
* crosses back. That makes an unexplained code the whole user-facing error, which is
* exactly what made the ENAMETOOLONG in #4692 expensive to diagnose. Staging has one
* failure of its own — the elevated process cannot open the payload — and that one
* gets named along with its remedy rather than surfacing as a number.
*/
export function describeElevatedRegistrationFailure(
failureLabel: string,
exitCode: number,
stageDir: string,
): string {
if (exitCode === OCX_ELEVATED_STAGING_UNREADABLE) {
return `${failureLabel}: the elevated process could not read the staged task definition in `
+ `${stageDir}. That directory grants read access to the staging account and to `
+ "administrators, so the hardening did not take effect there or the file was "
+ "replaced. Retry the command; if it keeps failing, run it again from a session "
+ "already elevated as an administrator.";
}
return `${failureLabel} with exit code ${exitCode}.`;
}
/**
* Stage, elevate, and clean up — on every exit, including UAC cancellation and a
* synchronous spawn failure.
*
* A cleanup failure never replaces the registration failure it followed: an operator
* told only that a temp directory could not be removed would have no idea the task was
* never registered.
*/
async function runStagedElevatedSchedulerRegistration(
taskName: string,
xml: string,
replace: boolean,
expectedExistingXml: string | undefined,
failureLabel: string,
): Promise<void> {
const staged = stageElevatedSchedulerRegistration(xml, expectedExistingXml);
let failure: unknown;
try {
const exitCode = await runWindowsElevatedScheduledTaskRegistration(
taskName,
staged.xml,
replace,
staged.expectedExisting,
);
if (exitCode !== 0) {
failure = new Error(describeElevatedRegistrationFailure(failureLabel, exitCode, dirname(staged.xml.path)));
}
} catch (error) {
failure = error;
}
try {
staged.cleanup();
} catch (cleanupError) {
if (failure) {
throw new AggregateError(
[failure, cleanupError],
"Elevated Task Scheduler registration failed and its staging could not be cleaned up.",
);
}
throw cleanupError;
}
if (failure) throw failure;
}
export function stageWindowsSchedulerRegistrationXml(
attemptNonce: string,
deps: WindowsSchedulerRegistrationStageDeps = {},
): string {
const createStageDir = deps.createStageDir
?? (() => mkdtempSync(join(tmpdir(), WINDOWS_SCHEDULER_STAGE_PREFIX)));
const hardenDir = deps.hardenDir
?? ((path: string) => { hardenSecretDir(path, { required: true }); });
const writeXml = deps.writeXml ?? ((path: string, contents: string) => {
writeFileSync(path, contents, { encoding: "utf16le", flag: "wx", mode: 0o600 });
});
const hardenPath = deps.hardenPath
?? ((path: string) => { hardenSecretPath(path, { required: true }); });
const removeStageDir = deps.removeStageDir
?? ((path: string) => { rmdirSync(path); });
let stageDir: string | null = null;
let xmlPath: string | null = null;
try {
stageDir = createStageDir();
try { chmodSync(stageDir, 0o700); } catch { /* required Windows ACL is authoritative */ }
hardenDir(stageDir);
xmlPath = join(stageDir, "task.xml");
// This document points at the canonical launcher but does not publish or rewrite it.
// The hardened private directory prevents another local account from replacing the
// document while UAC is pending; the file harden independently proves its identity.
writeXml(
xmlPath,
buildWindowsTaskXmlDocument(
windowsServiceScriptPath(),
windowsLauncherVbsPath(),
attemptNonce,
resolvedWindowsTaskSid(),
),
);
hardenPath(xmlPath);
ownedWindowsSchedulerStages.add(xmlPath);
return xmlPath;
} catch (error) {
if (stageDir) {
try {
cleanupWindowsSchedulerStage(stageDir, xmlPath ?? join(stageDir, "task.xml"), removeStageDir);
} catch (cleanupError) {
throw new AggregateError(
[error, cleanupError],
"Task Scheduler staging failed and its private temporary directory could not be removed.",
);
}
}
throw error;
}
}
export function removeWindowsSchedulerRegistrationStage(xmlPath: string): void {
if (!ownedWindowsSchedulerStages.has(xmlPath)) {
throw new Error("Refusing to remove an unrecognized Task Scheduler staging path.");
}
const stageDir = dirname(xmlPath);
cleanupWindowsSchedulerStage(
stageDir,
xmlPath,
path => { rmdirSync(path); },
);
if (existsSync(stageDir)) {
throw new Error("The private Task Scheduler staging directory still exists after cleanup.");
}
ownedWindowsSchedulerStages.delete(xmlPath);
}
export interface FreshWindowsSchedulerRegistrationDeps {
create?: (args: string[]) => void;
elevate?: (
taskName: string,
xml: string,
replace: boolean,
expectedExistingXml?: string,
) => Promise<void>;
probe?: () => WindowsSchedulerTaskProbe;
queryXml?: () => string;
readExistingXml?: () => string;
rollback?: () => Promise<string | null>;
}
export async function registerFreshWindowsSchedulerTask(
xmlPath: string,
attemptNonce: string,
deps: FreshWindowsSchedulerRegistrationDeps = {},
expectedExistingXml?: string,
): Promise<void> {
const replace = expectedExistingXml !== undefined;
const readExistingXml = deps.readExistingXml ?? statusWindowsXml;
const assertReplacementPrecondition = (): void => {
if (!replace) return;
if (!expectedExistingXml?.trim()) {
throw new Error("Task Scheduler replacement requires a non-empty captured registration.");
}
let currentXml = "";
try {
currentXml = readExistingXml();
} catch {
throw new Error("Task Scheduler replacement was refused because the current registration could not be read.");
}
if (!windowsSchedulerRegistrationMatchesSnapshot(currentXml, expectedExistingXml)) {
throw new Error("Task Scheduler replacement was refused because the current registration changed.");
}
};
assertReplacementPrecondition();
const args = buildWindowsSchtasksCreateArgsForXml(xmlPath, replace);
// Capture and validate the exact definition before an access-denied attempt can
// cross the UAC boundary. The elevated fallback receives these immutable bytes,
// never the caller-writable staging pathname.
const expectedXml = decodeSchtasksOutput(readFileSync(xmlPath));
if (
!windowsTaskRegistrationHealthy(expectedXml)
|| !windowsTaskRegistrationOwnedByAttempt(expectedXml, attemptNonce)
) {
throw new Error("The staged Task Scheduler registration failed OpenCodex ownership or shape validation.");
}
try {
(deps.create ?? schtasks)(args);
} catch (error) {
if (
!(error instanceof WindowsSchtasksError)
|| error.operation !== "create"
|| error.reason !== "access-denied"
) {
throw error;
}
// Register from the captured XML string inside the elevated process. Another
// same-user process can mutate its own temp files, so the captured bytes are staged
// privately and the elevated script verifies their digest before registering them.
// UAC can remain open for an arbitrary amount of time. Recheck the captured predecessor
// before launch; the elevated helper repeats the same check after consent and before Force.
assertReplacementPrecondition();
const elevate = deps.elevate ?? (async (
taskName: string,
xml: string,
replaceCurrent: boolean,
previousXml?: string,
) => runStagedElevatedSchedulerRegistration(
taskName,
xml,
replaceCurrent,
previousXml,
"Background service install failed",
));
await elevate(TASK, expectedXml, replace, expectedExistingXml);
}
const rollbackTask = deps.rollback ?? (() => rollbackWindowsSchedulerTaskOwnedByAttempt(attemptNonce, TASK));
const probe = (deps.probe ?? (() => probeWindowsSchedulerTask(TASK)))();
if (probe.status === "absent") {
throw new Error("Task Scheduler reported success, but the new registration is absent; no service cleanup was started.");
}
if (probe.status === "unknown") {
const rollback = await rollbackTask();
throw new Error(
`Task Scheduler registration was not verifiably present after create (${probe.detail}).`
+ (rollback ? ` Cleanup also failed: ${rollback}` : " The unverified registration was rolled back."),
);
}
let registeredXml = "";
let queryDetail: string | null = null;
try {
registeredXml = (deps.queryXml ?? (() => querySchtasks(["/query", "/tn", TASK, "/xml"])))();
} catch (error) {
queryDetail = error instanceof Error ? error.message : String(error);
}
if (!registeredXml.trim()) {
const rollback = await rollbackTask();
throw new Error(
"Task Scheduler registration was created, but its live XML could not be verified."
+ (queryDetail ? ` Query failed: ${queryDetail}` : " The query returned an empty document.")
+ (rollback ? ` Cleanup also failed: ${rollback}` : " The unverified registration was rolled back."),
);
}
if (
!windowsTaskRegistrationHealthy(registeredXml)
|| !windowsTaskRegistrationOwnedByAttempt(registeredXml, attemptNonce)
) {
const rollback = await rollbackTask();
throw new Error(
"Task Scheduler registration was created but failed the OpenCodex action/trigger or attempt-ownership verification."
+ (rollback ? ` Cleanup also failed: ${rollback}` : " The invalid registration was rolled back."),
);
}
}
export function recordWindowsSchedulerOwnership(): boolean {
// Ownership claiming is deliberately conservative: a legacy non-empty config root
// without metadata stays unclaimed, but that must not turn a service reinstall into
// an outage after prepareServiceInstall has stopped the previous manager.
return recordOwnedConfigPath(getConfigDir(), serviceStatePath());
}
export interface RemoveNativeWindowsServiceDeps {
status?: () => WinswStatus;
uninstall?: () => void;
sleep?: (ms: number) => void;
settleChecks?: number;
}
export function removeNativeWindowsServiceForScheduler(
deps: RemoveNativeWindowsServiceDeps = {},
): void {
const uninstall = deps.uninstall ?? uninstallWinswService;
// The test home cannot contain SCM. A partially mocked scheduler install must inject
// the native-service mutation too; otherwise it can stop/delete the user's live WinSW
// registration even though every filesystem path points at the isolated test home.
if (isTestHomeGuardArmed() && uninstall === uninstallWinswService) {
throw new Error(
"refusing to mutate the machine-global Windows native service from an armed test process; "
+ "inject the native-service removal instead of calling the live manager.",
);
}
const status = deps.status ?? statusWinswRaw;
const sleep = deps.sleep ?? Bun.sleepSync;
const settleChecks = Math.max(1, deps.settleChecks ?? 20);
// Transactional backend switch: installing the scheduler backend removes a native
// service first — two live managers would both respawn the proxy (conflict).
if (status() !== "nonexistent") {
console.log("🔁 Removing the native (WinSW) service before installing the Task Scheduler backend...");
try {
uninstall();
} catch (err) {
throw new Error(`Cannot remove the native service before switching to Task Scheduler: ${err instanceof Error ? err.message : String(err)}. Remove it manually with 'sc delete ${WINSW_SERVICE_ID}' or retry.`);
}
for (let check = 0; check < settleChecks; check++) {
if (status() === "nonexistent") return;
if (check + 1 < settleChecks) sleep(250);
}
throw new Error(`Native service registration could not be re-verified after the removal attempt — aborting switch. Check 'sc.exe query ${WINSW_SERVICE_ID}' and remove it manually if present.`);
}
}
export function installWindows(): void {
recordWindowsSchedulerOwnership();
removeNativeWindowsServiceForScheduler();
// End a running task BEFORE rewriting the assets it is executing — cmd.exe reading the
// script mid-rewrite runs a torn batch file, and its open handle can fail the write.
try { stopWindows(); } catch { /* not running */ }
writeWindowsSchedulerAssets();
schtasks(buildWindowsSchtasksCreateArgs(windowsServiceScriptPath()));
schtasks(["/run", "/tn", TASK]);
writeServiceInstallState("scheduler");
}
/**
* Re-register an already-installed scheduler task from a freshly staged definition.
*
* Reuses the fresh-install staging and registration path, so the same ownership and shape
* validation applies and an access-denied `schtasks /create` still escalates through the
* existing elevated fallback. The staged XML is removed on every exit.
*/
export async function reregisterWindowsSchedulerTask(
attemptNonce: string,
expectedExistingXml: string,
): Promise<void> {
const stagedXml = stageWindowsSchedulerRegistrationXml(attemptNonce);
try {
await registerFreshWindowsSchedulerTask(stagedXml, attemptNonce, {}, expectedExistingXml);
} finally {
removeWindowsSchedulerRegistrationStage(stagedXml);
}
}
function stageWindowsSchedulerRestoreXml(registeredXml: string): string {
if (!registeredXml.trim()) {
throw new Error("Cannot restore an empty Task Scheduler registration.");
}
const stageDir = mkdtempSync(join(tmpdir(), WINDOWS_SCHEDULER_STAGE_PREFIX));
const xmlPath = join(stageDir, "task.xml");
try {
try { chmodSync(stageDir, 0o700); } catch { /* required Windows ACL is authoritative */ }
hardenSecretDir(stageDir, { required: true });
writeFileSync(
xmlPath,
`\uFEFF${registeredXml.replace(/^\uFEFF/, "")}`,
{ encoding: "utf16le", flag: "wx", mode: 0o600 },
);
hardenSecretPath(xmlPath, { required: true });
ownedWindowsSchedulerStages.add(xmlPath);
return xmlPath;
} catch (error) {
try {
cleanupWindowsSchedulerStage(stageDir, xmlPath, path => { rmdirSync(path); });
} catch (cleanupError) {
throw new AggregateError(
[error, cleanupError],
"Task Scheduler rollback staging failed and could not be cleaned up.",
);
}
throw error;
}
}
/** Compare two live scheduler snapshots conservatively without treating formatting as mutation. */
export function windowsSchedulerRegistrationMatchesSnapshot(currentXml: string, previousXml: string): boolean {
const normalize = (xml: string) => xml
.replace(/^\uFEFF/, "")
.replace(/\r\n?/g, "\n")
.trim();
const current = normalize(currentXml);
const previous = normalize(previousXml);
return current.length > 0 && previous.length > 0 && current === previous;
}
/**
* Restore the captured registration only while the fixed task name is still absent.
*
* Both publication paths deliberately omit force: another writer appearing after the
* absence probe must make this operation fail instead of being overwritten. Exact live
* XML readback is required before the caller may restart the recovered task.
*/
export async function restoreWindowsSchedulerTaskIfAbsent(registeredXml: string): Promise<void> {
const before = probeWindowsSchedulerTask(TASK);
if (before.status !== "absent") {
throw new Error(before.status === "present"
? "A Task Scheduler registration appeared before recovery and was preserved."
: `Task Scheduler absence could not be re-verified before recovery (${before.detail}).`);
}
const stagedXml = stageWindowsSchedulerRestoreXml(registeredXml);
try {
const args = buildWindowsSchtasksCreateArgsForXml(stagedXml, false);
try {
schtasks(args);
} catch (error) {
if (
!(error instanceof WindowsSchtasksError)
|| error.operation !== "create"
|| error.reason !== "access-denied"
) {
throw error;
}
await runStagedElevatedSchedulerRegistration(
TASK,
registeredXml,
false,
undefined,
"Task Scheduler rollback failed",
);
}
const recoveredXml = statusWindowsXml();
if (!windowsSchedulerRegistrationMatchesSnapshot(recoveredXml, registeredXml)) {
throw new Error("The recovered Task Scheduler registration did not match the captured definition.");
}
} finally {
removeWindowsSchedulerRegistrationStage(stagedXml);
}
}
/**
* Opt-in native backend (`ocx service install --native`). Transactional: removes the
* scheduler backend first; on failure the machine is left with NO service (explicitly
* reported) — never a silent fallback to the scheduler.
*/
/** Refuse WinSW when the interactive user is a Microsoft account (SCM cannot authenticate it). */
export function assertWindowsNativeServiceAccountSupported(): void {
if (process.platform !== "win32") return;
const source = readWindowsPrincipalSource();
if (source?.toLowerCase() === "microsoftaccount") {
throw new Error(
"The native (WinSW) service backend cannot run under a Microsoft-account Windows login. "
+ "Keep the Task Scheduler backend (`ocx service install`) or sign in with a local/domain account before `ocx service install --native`.",
);
}
}
function readWindowsPrincipalSource(): string | null {
if (process.platform !== "win32") return null;
const ps = join(process.env.SystemRoot ?? "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
if (!existsSync(ps)) return null;
try {
const out = execFileSync(ps, [
"-NoLogo",
"-NoProfile",
"-NonInteractive",
"-Command",
"(Get-LocalUser -Name $env:USERNAME -ErrorAction SilentlyContinue).PrincipalSource",
], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], windowsHide: true }).trim();
return out || null;
} catch {
return null;
}
}
export async function installWindowsNative(): Promise<void> {
assertWindowsNativeServiceAccountSupported();
recordOwnedConfigPath(getConfigDir(), serviceStatePath());
if (!existsSync(getConfigDir())) mkdirSync(getConfigDir(), { recursive: true });
writeServiceApiTokenFile();
let hadScheduler = false;
try {
hadScheduler = schtasks(["/query", "/tn", TASK]).includes(TASK);
} catch { /* task absent */ }
if (hadScheduler) {
console.log("🔁 Removing the Task Scheduler backend before installing the native (WinSW) service...");
try { stopWindows(); } catch { /* not running */ }
try {
uninstallWindows();
} catch (err) {
throw new Error(`Cannot remove the Task Scheduler backend before switching to native: ${err instanceof Error ? err.message : String(err)}`);
}
// Verify removal — schtasks /delete can silently fail if UAC or policy blocks it.
try {
if (schtasks(["/query", "/tn", TASK]).includes(TASK)) {
throw new Error("Task Scheduler backend still present after removal — aborting switch.");
}
} catch (e) {
if (e instanceof Error && e.message.includes("still present")) throw e;
/* query failure = task absent, which is what we want */
}
}
try {
await installWinswService(defaultWinswEntry(serviceSourceDir));
} catch (err) {
if (hadScheduler) console.error("⚠️ Native install failed AFTER removing the Task Scheduler backend — no service is installed now. Run `ocx service install` to restore the scheduler backend, or retry `--native`.");
throw err;
}
writeServiceInstallState("native");
}
export function startWindows(): void { schtasks(["/run", "/tn", TASK]); }
export function isWindowsSchedulerEndBenign(error: unknown): boolean {
const detail = schtasksErrorDetail(error).toLowerCase();
return detail.includes("no running instance")
|| detail.includes("not currently running")
|| detail.includes("0x41330");
}
/**
* End the scheduler task. "Already stopped" is success; other `/end` failures are
* swallowed so callers can still run tracked-proxy + live-proxy cleanup.
*
* Do not key a restart-window wait on `/end` failure: the #764 case is an `/end`
* that *succeeds* while the wrapper survives and respawns. That verification lives
* on the stop-verification path (poll across the restart window), not here.
*/
export function stopWindows(): void {
try {
schtasks(["/end", "/tn", TASK]);
} catch (error) {
if (isWindowsSchedulerEndBenign(error)) return;
}
}
/**
* `stopWindows` for callers that need to know whether it worked.
*
* The void form swallows a non-benign `/end` failure, which is right for best-effort
* teardown and wrong for deciding whether an update may replace files: a scheduler that
* refused to stop can respawn the proxy on top of a half-written install (#3008).
*/
export function stopWindowsChecked(): boolean {
try {
schtasks(["/end", "/tn", TASK]);
return true;
} catch (error) {
return isWindowsSchedulerEndBenign(error);
}
}
export function statusWindows(): string { try { return schtasks(["/query", "/tn", TASK]); } catch { return ""; } }
export function statusWindowsXml(): string { try { return schtasks(["/query", "/tn", TASK, "/xml"]); } catch { return ""; } }
/**
* Best-effort termination of surviving Windows scheduler launcher/wrapper processes.
* `schtasks /end` ends the task instance but often leaves wscript/cmd running the
* `:loop` batch, which brings the proxy back during a stop or restart.
*
* The matching rule — canonical paths of THIS installation, as complete
* command-line tokens — lives in lib/windows-service-wrappers so the update job
* cannot drift away from it again.
*/
export function killWindowsServiceWrapperProcesses(): void {
killWindowsSchedulerWrappers({
scriptPath: windowsServiceScriptPath(),
launcherPath: windowsLauncherVbsPath(),
});
}
export function uninstallWindows(): void {
const probe = probeWindowsSchedulerTask(TASK);
if (probe.status === "present") {
try {
schtasks(["/delete", "/tn", TASK, "/f"]);
} catch (error) {
throw new Error(`Failed to delete Task Scheduler task ${TASK}: ${error instanceof Error ? error.message : String(error)}`);
}
const afterDelete = probeWindowsSchedulerTask(TASK);
if (afterDelete.status === "present") {
throw new Error(`Task Scheduler task ${TASK} is still present after delete — refusing to remove service assets. Retry from an elevated shell.`);
}
if (afterDelete.status === "unknown") {
throw new Error(`Task Scheduler task ${TASK} presence could not be verified after delete — refusing to remove service assets.`);
}
} else if (probe.status === "unknown") {
throw new Error(`Task Scheduler task ${TASK} presence could not be verified — refusing to remove service assets.`);
}
if (existsSync(windowsServiceScriptPath())) unlinkSync(windowsServiceScriptPath());
if (existsSync(windowsLauncherVbsPath())) unlinkSync(windowsLauncherVbsPath());
if (existsSync(windowsTaskXmlPath())) unlinkSync(windowsTaskXmlPath());
}
/**
* Collapse the Windows backend observations into one outcome.
*
* Extracted so the precedence is testable by calling it. The rule that matters: a readable
* failure outranks an unreadable state, and an unreadable state outranks success — a
* scheduler we cannot see may still respawn the proxy.
*/
export function classifyWindowsServiceStop(o: {
stopped: boolean;
failed: boolean;
schedulerStopped: boolean;
stateUnknown: boolean;
}): ServiceStopOutcome {
if (o.failed) return "failed";
if (o.stateUnknown) return "state-unknown";
if (o.stopped) return o.schedulerStopped ? "stopped-respawnable" : "stopped";
return "absent";
}