UNPKG

@bitkyc08/opencodex

Version:

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

904 lines (825 loc) • 38.2 kB
import { spawn, type ChildProcess, type SpawnOptions } from "node:child_process"; import { existsSync } from "node:fs"; import { isAbsolute, join, relative, resolve as resolvePath, sep } from "node:path"; import { dlopen, ptr, type Pointer } from "bun:ffi"; import { isTestHomeGuardArmed } from "./test-home-guard"; type ElevationSpawn = ( command: string, args: ReadonlyArray<string>, options: SpawnOptions, ) => ChildProcess; let elevationSpawn: ElevationSpawn = spawn; /** Test-only seam for the elevated PowerShell launcher. */ export function setWindowsElevationSpawnForTests(next: ElevationSpawn | null): void { elevationSpawn = next ?? spawn; } type GetSystemDirectoryW = (buffer: Pointer, size: number) => number; type TrustedSystemDirectoryResolver = () => string; type IsUserAnAdmin = () => number; type WindowsElevationProbe = () => boolean | null; export class WindowsSystemDirectoryFfiUnavailableError extends Error { constructor() { super("Failed to load GetSystemDirectoryW from kernel32.dll."); this.name = "WindowsSystemDirectoryFfiUnavailableError"; } } let getSystemDirectoryWFn: GetSystemDirectoryW | null | undefined; let trustedSystemDirectoryResolverForTests: TrustedSystemDirectoryResolver | null = null; let isUserAnAdminFn: (() => boolean) | null | undefined; let windowsElevationProbeForTests: WindowsElevationProbe | null = null; /** Test-only seam to replace GetSystemDirectoryW-backed resolution. */ export function setTrustedWindowsSystemDirectoryResolverForTests( next: TrustedSystemDirectoryResolver | null, ): void { trustedSystemDirectoryResolverForTests = next; } /** Test-only seam for the locale-independent current-token elevation probe. */ export function setWindowsElevationProbeForTests(next: WindowsElevationProbe | null): void { windowsElevationProbeForTests = next; } function loadIsUserAnAdmin(): (() => boolean) | null { if (isUserAnAdminFn !== undefined) return isUserAnAdminFn; if (process.platform !== "win32") { isUserAnAdminFn = null; return null; } try { const lib = dlopen("shell32.dll", { IsUserAnAdmin: { args: [], // Win32 BOOL is a signed 32-bit integer, not C/C++ bool. returns: "i32", }, }); const isUserAnAdmin = lib.symbols.IsUserAnAdmin as IsUserAnAdmin; isUserAnAdminFn = () => isUserAnAdmin() !== 0; } catch { isUserAnAdminFn = null; } return isUserAnAdminFn; } /** * Probe the effective Windows token without parsing localized command output. * `null` fails closed: callers must retain the original scheduler error rather * than infer that an unknown token state needs elevation. */ export function isCurrentWindowsProcessElevated(): boolean | null { if (windowsElevationProbeForTests) return windowsElevationProbeForTests(); const isUserAnAdmin = loadIsUserAnAdmin(); if (!isUserAnAdmin) return null; try { return isUserAnAdmin(); } catch { return null; } } function loadGetSystemDirectoryW(): GetSystemDirectoryW | null { if (getSystemDirectoryWFn !== undefined) return getSystemDirectoryWFn; if (process.platform !== "win32") { getSystemDirectoryWFn = null; return null; } try { const lib = dlopen("kernel32.dll", { GetSystemDirectoryW: { args: ["ptr", "u32"], returns: "u32", }, }); getSystemDirectoryWFn = (buffer, size) => lib.symbols.GetSystemDirectoryW(buffer, size) as number; } catch { getSystemDirectoryWFn = null; } return getSystemDirectoryWFn; } function decodeWideCString(buf: Uint16Array, length: number): string { return String.fromCharCode(...buf.subarray(0, length)); } /** * Resolve the real Windows system directory via GetSystemDirectoryW. * Must never trust process.env.SystemRoot / WINDIR — those are caller-controlled and * must not select binaries for UAC elevation. */ export function resolveTrustedWindowsSystemDirectory(): string { if (trustedSystemDirectoryResolverForTests) { return trustedSystemDirectoryResolverForTests(); } if (process.platform !== "win32") { throw new Error("Trusted Windows system directory resolution is only supported on Windows."); } const getSystemDirectoryW = loadGetSystemDirectoryW(); if (!getSystemDirectoryW) { throw new WindowsSystemDirectoryFfiUnavailableError(); } let size = 260; for (let attempt = 0; attempt < 4; attempt += 1) { const buf = new Uint16Array(size); const written = getSystemDirectoryW(ptr(buf.buffer), size); if (written === 0) { throw new Error("GetSystemDirectoryW failed while resolving the trusted system directory."); } // When the buffer is too small, the return value is the required size including NUL. if (written >= size) { size = written + 1; continue; } const directory = decodeWideCString(buf, written).replace(/[/\\]+$/, ""); if (!directory || !existsSync(directory)) { throw new Error("GetSystemDirectoryW returned an unusable system directory."); } return resolvePath(directory); } throw new Error("GetSystemDirectoryW required a system directory path larger than expected."); } /** * True when `candidatePath` is the trusted directory itself, or a contained child. * Uses path.relative so containment works with host-native separators (Linux/macOS CI * hosts fake win32 with `/tmp/...` paths; a literal `\\` prefix check rejects them). */ function isPathInsideTrustedDirectory(trustedDirectory: string, candidatePath: string): boolean { const relativePath = relative(trustedDirectory, candidatePath); return ( relativePath === "" || (!isAbsolute(relativePath) && relativePath !== ".." && !relativePath.startsWith(`..${sep}`)) ); } function assertTrustedSystemExecutable(candidate: string, label: string): string { const systemDir = resolveTrustedWindowsSystemDirectory(); const resolved = resolvePath(candidate); if (!isPathInsideTrustedDirectory(systemDir, resolved)) { throw new Error(`${label} resolved outside the trusted Windows system directory.`); } if (!existsSync(resolved)) { throw new Error(`Trusted ${label} was not found at ${resolved}.`); } return resolved; } /** Test-only access to the trusted-path containment check. */ export function assertTrustedSystemExecutableForTests(candidate: string, label: string): string { return assertTrustedSystemExecutable(candidate, label); } type ElevationExeOverrides = { powershell?: string; schtasks?: string; taskkill?: string; icacls?: string }; let elevationExeOverridesForTests: ElevationExeOverrides | null = null; /** * Test-only absolute executable overrides for Linux CI (which fakes win32 but has * no kernel32/System32). Production resolution never consults this seam. */ export function setTrustedWindowsElevationExecutablesForTests( next: ElevationExeOverrides | null, ): void { elevationExeOverridesForTests = next; } /** Absolute path to System32\\WindowsPowerShell\\v1.0\\powershell.exe from a trusted system directory. */ export function resolveTrustedWindowsPowerShellExe(): string { if (elevationExeOverridesForTests?.powershell) { return elevationExeOverridesForTests.powershell; } const candidate = join( resolveTrustedWindowsSystemDirectory(), "WindowsPowerShell", "v1.0", "powershell.exe", ); return assertTrustedSystemExecutable(candidate, "PowerShell"); } /** Absolute path to System32\\schtasks.exe from a trusted system directory. */ export function resolveTrustedWindowsSchtasksExe(): string { if (elevationExeOverridesForTests?.schtasks) { return elevationExeOverridesForTests.schtasks; } const candidate = join(resolveTrustedWindowsSystemDirectory(), "schtasks.exe"); return assertTrustedSystemExecutable(candidate, "schtasks.exe"); } /** Absolute path to System32\\taskkill.exe from a trusted system directory. */ export function resolveTrustedWindowsTaskkillExe(): string { if (elevationExeOverridesForTests?.taskkill) { return elevationExeOverridesForTests.taskkill; } const candidate = join(resolveTrustedWindowsSystemDirectory(), "taskkill.exe"); return assertTrustedSystemExecutable(candidate, "taskkill.exe"); } /** Absolute path to System32\\icacls.exe from a trusted system directory. */ export function resolveTrustedWindowsIcaclsExe(): string { if (elevationExeOverridesForTests?.icacls) { return elevationExeOverridesForTests.icacls; } const candidate = join(resolveTrustedWindowsSystemDirectory(), "icacls.exe"); return assertTrustedSystemExecutable(candidate, "icacls.exe"); } /** Stable machine-readable marker for a denied `schtasks /create`. Crosses the CLI→proxy boundary. */ export const WINDOWS_SCHTASKS_CREATE_ACCESS_DENIED_MARKER = "OCX_ERROR_CODE=WINDOWS_SCHTASKS_CREATE_ACCESS_DENIED"; /** * Reserved elevated-scheduler protocol exit codes. * These are OpenCodex-owned values returned by the elevated PowerShell transaction. * They must never collide with UAC cancellation (1223). * * The elevated script never exits with raw schtasks codes — only these protocol values — * so the parent can classify the transaction without a user-controlled result file. */ export const OCX_ELEVATED_SUCCESS = 0; export const OCX_ELEVATED_CREATE_FAILED = 10; export const OCX_ELEVATED_RUN_FAILED_ROLLED_BACK = 11; export const OCX_ELEVATED_RUN_FAILED_ROLLBACK_FAILED = 12; export const OCX_ELEVATED_PROTOCOL_FAILED = 13; /** Windows ERROR_CANCELLED — reserved for UAC denial; never emitted by the elevated script. */ export const OCX_ELEVATED_UAC_CANCELLED = 1223; /** * The elevated process could not read a staged payload (#4692). * * The staged ACL grants the staging account plus read for SYSTEM and * BUILTIN\Administrators (#4779), so both a split-token elevation and an * over-the-shoulder one answered with a different administrator's credentials * can open it. A residual read failure means the hardening did not take effect * or the payload was replaced. The elevated side cannot explain that itself: it * runs hidden, so its stderr goes nowhere and only the exit code survives the * boundary. Without a code of its own the operator would be told "exit code 1" * for a cause that names its own remedy — the same undiagnosable failure this * change set exists to remove. * * Deliberately outside OCX_ELEVATED_PROTOCOL_CODES: that list is the create-and-run * transaction's alphabet, and this code belongs to the registration path. */ export const OCX_ELEVATED_STAGING_UNREADABLE = 14; export const OCX_ELEVATED_PROTOCOL_CODES = [ OCX_ELEVATED_SUCCESS, OCX_ELEVATED_CREATE_FAILED, OCX_ELEVATED_RUN_FAILED_ROLLED_BACK, OCX_ELEVATED_RUN_FAILED_ROLLBACK_FAILED, OCX_ELEVATED_PROTOCOL_FAILED, ] as const; export type WindowsSchtasksOperation = "create" | "run" | "query" | "delete" | "end" | "other"; export type WindowsSchtasksFailureReason = "access-denied" | "other"; export type WindowsElevationFailureReason = | "cancelled" | "timeout" | "launch-failed" | "child-failed" | "terminated"; export type ElevatedSchedulerOutcome = | "success" | "create-failed" | "run-failed-rolled-back" | "run-failed-rollback-failed" | "protocol-failed"; const ELEVATION_OUTPUT_LIMIT = 256 * 1024; function windowsAccessDeniedText(text: string): boolean { const normalized = text.toLowerCase(); return normalized.includes("access denied") || normalized.includes("access is denied") || normalized.includes("denied access") || normalized.includes("zugriff verweigert"); } function windowsUacCancelledText(text: string): boolean { const normalized = text.toLowerCase(); return normalized.includes("operation was canceled by the user") || normalized.includes("operation was cancelled by the user") || normalized.includes("the operation was canceled") || normalized.includes("the operation was cancelled") || normalized.includes("vom benutzer abgebrochen") || normalized.includes("durch den benutzer abgebrochen"); } /** True when a captured stderr/stdout/message indicates Windows access denial. */ export function isWindowsAccessDenied(detail: string): boolean { return windowsAccessDeniedText(detail); } /** True when a thrown exec error looks like Windows access denial. */ export function isWindowsAccessDeniedError(error: unknown): boolean { if (error instanceof WindowsSchtasksError) return error.reason === "access-denied"; if (!(error instanceof Error)) return isWindowsAccessDenied(String(error)); const exec = error as NodeJS.ErrnoException & { stderr?: string | Buffer; stdout?: string | Buffer }; const parts = [error.message, exec.stderr, exec.stdout] .map(part => (typeof part === "string" ? part : part ? String(part) : "")); return parts.some(part => windowsAccessDeniedText(part)); } /** True only for a structured Task Scheduler `/create` access-denied failure. */ export function isWindowsSchtasksCreateAccessDenied(detail: string): boolean { return detail.includes(WINDOWS_SCHTASKS_CREATE_ACCESS_DENIED_MARKER); } export function schtasksOperationFromArgs(args: string[]): WindowsSchtasksOperation { const flag = (args[0] ?? "").toLowerCase(); if (flag === "/create") return "create"; if (flag === "/run") return "run"; if (flag === "/query") return "query"; if (flag === "/delete") return "delete"; if (flag === "/end") return "end"; return "other"; } function schedulerExitStatus(error: unknown): number | null { if (!error || typeof error !== "object") return null; const status = (error as { status?: unknown }).status; return typeof status === "number" && Number.isInteger(status) ? status : null; } /** * The owned scheduler install has a fixed shape. Restrict the locale-independent * fallback to that shape so unrelated schtasks failures cannot request elevation. */ function isOwnedSchedulerCreate(args: string[]): boolean { const normalized = args.map(arg => arg.toLowerCase()); const taskIndex = normalized.indexOf("/tn"); const xmlIndex = normalized.indexOf("/xml"); return normalized[0] === "/create" && normalized[taskIndex + 1] === "opencodex-proxy" && taskIndex > 0 && xmlIndex > 0 && Boolean(args[xmlIndex + 1]) && normalized.includes("/f"); } function isWindowsSchtasksAccessDeniedError(error: unknown, args: string[]): boolean { if (!isOwnedSchedulerCreate(args)) return false; return isWindowsAccessDeniedError(error) || (schedulerExitStatus(error) === 1 && isCurrentWindowsProcessElevated() === false); } /** Structured Task Scheduler failure that survives formatting and process boundaries. */ export class WindowsSchtasksError extends Error { readonly code = "WINDOWS_SCHTASKS_ERROR" as const; constructor( readonly operation: WindowsSchtasksOperation, readonly reason: WindowsSchtasksFailureReason, message: string, ) { super(message); this.name = "WindowsSchtasksError"; } get machineMarker(): string | null { return this.operation === "create" && this.reason === "access-denied" ? WINDOWS_SCHTASKS_CREATE_ACCESS_DENIED_MARKER : null; } } export class WindowsElevationError extends Error { readonly code = "WINDOWS_ELEVATION_ERROR" as const; constructor( readonly reason: WindowsElevationFailureReason, message: string, ) { super(message); this.name = "WindowsElevationError"; } } /** Replace raw schtasks access-denied output with dashboard-friendly guidance. */ export function formatWindowsSchtasksError(error: unknown, args: string[]): string { const operation = schtasksOperationFromArgs(args); const ownedCreateAccessDenied = isWindowsSchtasksAccessDeniedError(error, args); const accessDenied = ownedCreateAccessDenied || isWindowsAccessDeniedError(error); if (!accessDenied) { return error instanceof Error ? error.message : String(error); } const argsText = args.map(arg => (/\s/.test(arg) ? `"${arg}"` : arg)).join(" "); const guidance = [ "Windows access denied while running Task Scheduler.", `Command: schtasks ${argsText}`, "The OpenCodex task definition is scoped to the installing account and normally registers without elevation, so this denial is not fixed by approving a UAC prompt. Check `ocx service status`: if an existing `opencodex-proxy` task belongs to a different account, remove it from that account and retry `ocx service install`.", ].join(" "); if (operation === "create" && ownedCreateAccessDenied) { return `${guidance}\n${WINDOWS_SCHTASKS_CREATE_ACCESS_DENIED_MARKER}`; } return guidance; } export function toWindowsSchtasksError(error: unknown, args: string[]): WindowsSchtasksError { if (error instanceof WindowsSchtasksError) return error; const operation = schtasksOperationFromArgs(args); const reason: WindowsSchtasksFailureReason = isWindowsSchtasksAccessDeniedError(error, args) ? "access-denied" : "other"; return new WindowsSchtasksError(operation, reason, formatWindowsSchtasksError(error, args)); } /** * Quote one argument for Win32 CommandLineToArgvW / Start-Process -ArgumentList. * Handles empty args, spaces, embedded quotes, and trailing backslashes. */ export function windowsCmdQuote(value: string): string { if (value.length === 0) return '""'; if (!/[\s"]/.test(value)) return value; let result = '"'; let numBackslashes = 0; for (const ch of value) { if (ch === "\\") { numBackslashes += 1; continue; } if (ch === '"') { result += "\\".repeat(numBackslashes * 2 + 1) + '"'; numBackslashes = 0; continue; } result += "\\".repeat(numBackslashes) + ch; numBackslashes = 0; } result += "\\".repeat(numBackslashes * 2) + '"'; return result; } /** Build one Win32 argument-list string for Start-Process -ArgumentList. */ export function buildWindowsElevatedArgumentList(args: string[]): string { return args.map(windowsCmdQuote).join(" "); } /** Classify an elevated-process exit code into a stable scheduler outcome. */ export function classifyElevatedSchedulerExitCode(exitCode: number): ElevatedSchedulerOutcome { if (exitCode === OCX_ELEVATED_SUCCESS) return "success"; if (exitCode === OCX_ELEVATED_CREATE_FAILED) return "create-failed"; if (exitCode === OCX_ELEVATED_RUN_FAILED_ROLLED_BACK) return "run-failed-rolled-back"; if (exitCode === OCX_ELEVATED_RUN_FAILED_ROLLBACK_FAILED) return "run-failed-rollback-failed"; // Malformed / unexpected / missing-ExitCode-normalized codes fail closed. return "protocol-failed"; } function windowsPowerShell(): string { return resolveTrustedWindowsPowerShellExe(); } function psSingleQuote(value: string): string { return `'${value.replace(/'/g, "''")}'`; } function appendBounded(current: string, chunk: string, limit = ELEVATION_OUTPUT_LIMIT): string { if (current.length >= limit) return current; const remaining = limit - current.length; return current + chunk.slice(0, remaining); } export interface WindowsElevationResult { exitCode: number; stdout: string; stderr: string; } export interface WindowsElevationExecution { /** Settles only on launcher close/error — never killed by a request-level timeout. */ completion: Promise<WindowsElevationResult>; launcherPid: number | null; } /** Request-facing wait for elevation; process observation continues separately. */ export const ELEVATION_REQUEST_TIMEOUT_MS = 120_000; /** * Wait for `promise` up to `timeoutMs` without cancelling it. * On timeout the original promise remains active for late settlement. */ export function raceWithTimeout<T>( promise: Promise<T>, timeoutMs: number, ): Promise<{ status: "completed"; value: T } | { status: "timed-out" }> { return new Promise((resolve, reject) => { let settled = false; const timer = setTimeout(() => { if (settled) return; settled = true; resolve({ status: "timed-out" }); }, timeoutMs); promise.then( value => { if (settled) return; settled = true; clearTimeout(timer); resolve({ status: "completed", value }); }, error => { if (settled) return; settled = true; clearTimeout(timer); reject(error); }, ); }); } /** * Spawn non-elevated PowerShell to run a -Command script. * Does not kill the launcher on any timeout — callers race a separate request timeout. */ export function startPowerShellCommand(commandScript: string): WindowsElevationExecution { if (process.platform !== "win32") { return { launcherPid: null, completion: Promise.reject(new WindowsElevationError( "launch-failed", "Windows elevation is only supported on Windows.", )), }; } // HOME isolation cannot contain UAC children or other machine-global effects. Keep the // final process boundary closed while the real launcher is installed; explicitly injected // launchers remain available to tests that exercise the elevation protocol in memory. if (isTestHomeGuardArmed() && elevationSpawn === spawn) { return { launcherPid: null, completion: Promise.reject(new WindowsElevationError( "launch-failed", "Refusing to launch a live Windows elevation process from an armed test process; inject the elevation launcher instead.", )), }; } let child: ChildProcess; try { child = elevationSpawn( windowsPowerShell(), ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", commandScript], { windowsHide: true, stdio: ["ignore", "pipe", "pipe"], }, ); } catch (error) { return { launcherPid: null, completion: Promise.reject(new WindowsElevationError( "launch-failed", error instanceof Error ? error.message : String(error), )), }; } const completion = new Promise<WindowsElevationResult>((resolve, reject) => { let settled = false; let stdout = ""; let stderr = ""; const settle = (fn: () => void) => { if (settled) return; settled = true; fn(); }; child.stdout?.setEncoding?.("utf8"); child.stderr?.setEncoding?.("utf8"); child.stdout?.on("data", (chunk: string | Buffer) => { stdout = appendBounded(stdout, typeof chunk === "string" ? chunk : chunk.toString("utf8")); }); child.stderr?.on("data", (chunk: string | Buffer) => { stderr = appendBounded(stderr, typeof chunk === "string" ? chunk : chunk.toString("utf8")); }); child.once("error", (error: NodeJS.ErrnoException) => { settle(() => reject(new WindowsElevationError( "launch-failed", error.code === "ENOENT" ? "Windows PowerShell was not found for elevation." : (error.message || "Windows elevation failed to launch."), ))); }); child.once("close", (code, signal) => { const detail = [stderr.trim(), stdout.trim()].filter(Boolean).join("\n"); if (typeof code === "number") { // Only treat UAC-cancellation text as cancelled when the process did not succeed. if ( code === OCX_ELEVATED_UAC_CANCELLED || (code !== 0 && windowsUacCancelledText(detail)) ) { settle(() => reject(new WindowsElevationError( "cancelled", "Windows administrator approval was required, but the UAC prompt was cancelled or denied.", ))); return; } settle(() => resolve({ exitCode: code, stdout, stderr })); return; } // Launcher terminated without an exit code — elevated child may still exist. settle(() => reject(new WindowsElevationError( "terminated", `Windows elevation terminated by ${signal ?? "unknown signal"}.`, ))); }); }); return { completion, launcherPid: child.pid ?? null }; } /** * Launch a file with UAC elevation and wait for it to exit. * Throws WindowsElevationError for cancellation, launch failure, or signal termination. * Returns the elevated process exit code for completed launches (including non-zero). */ export function runWindowsElevated(file: string, args: string[]): Promise<number> { const argumentList = buildWindowsElevatedArgumentList(args); // Touch .Handle so Windows PowerShell 5.1 keeps a process handle; ExitCode can // otherwise stay $null after -Wait and `exit $null` becomes exit 0 (false success). const script = [ `$p = Start-Process -FilePath ${psSingleQuote(file)}`, argumentList.length > 0 ? ` -ArgumentList ${psSingleQuote(argumentList)}` : "", " -Verb RunAs -WindowStyle Hidden -PassThru -Wait;", `if ($null -eq $p) { exit ${OCX_ELEVATED_UAC_CANCELLED} }`, "$null = $p.Handle;", // Missing ExitCode is a protocol failure for single-file elevation (not success). `if ($null -eq $p.ExitCode) { exit ${OCX_ELEVATED_PROTOCOL_FAILED} }`, "exit $p.ExitCode", ].join(""); return startPowerShellCommand(script).completion.then(result => result.exitCode); } /** * A task definition staged for the elevated process. * * Before elevation, the launcher pins the file and every ancestor with non-reparse * handles: payload files deny write/delete sharing, ancestor directories deny delete * sharing only (writes inside them stay possible so the stage can be populated). * The elevated script additionally bounds and * hashes the exact bytes it decodes. */ export interface StagedWindowsTaskXml { /** Path inside the caller's hardened staging directory. */ readonly path: string; /** Exact byte length, checked before the elevated process allocates or reads. */ readonly byteLength: number; /** Lowercase hex SHA-256 of the staged bytes (UTF-16LE, no BOM). */ readonly sha256: string; } /** * Read a staged payload, prove it is the one that was validated, and decode it. * * One bounded read: the bytes that are hashed are the same array that is decoded and * registered. The unelevated launcher keeps the namespace and files pinned throughout. */ const READ_STAGED_TASK_XML = "function Read-OcxStagedTaskXml([string]$path, [long]$expectedLength, [string]$expectedHash) {" // An unreadable payload is a diagnosable condition, not a generic throw: a hidden // elevated process has nowhere to print, so the cause has to ride the exit code. + " try { $stream = [IO.File]::Open($path, 'Open', 'Read', 'Read');" + " if ($stream.Length -ne $expectedLength) { throw 'Task Scheduler staged payload has an invalid length.' };" + " $bytes = [byte[]]::new($expectedLength); $offset = 0;" + " while ($offset -lt $bytes.Length) { $read = $stream.Read($bytes, $offset, $bytes.Length - $offset); if ($read -eq 0) { throw 'Task Scheduler staged payload ended early.' }; $offset += $read } }" + " catch [System.UnauthorizedAccessException] { exit " + OCX_ELEVATED_STAGING_UNREADABLE + " }" + " catch [System.Security.SecurityException] { exit " + OCX_ELEVATED_STAGING_UNREADABLE + " } finally { if ($null -ne $stream) { $stream.Dispose() } };" + " $sha = [Security.Cryptography.SHA256]::Create();" + " try { $actual = [BitConverter]::ToString($sha.ComputeHash($bytes)).Replace('-', '').ToLowerInvariant() } finally { $sha.Dispose() };" + " if ($actual -cne $expectedHash) { throw 'Task Scheduler staged payload failed its integrity check.' };" + " return [Text.Encoding]::Unicode.GetString($bytes) }"; /** * Register one scheduled-task definition from staged, digest-verified bytes. * * The payloads used to be embedded as base64(utf16le) inside an inner PowerShell script * that was itself base64(utf16le)-encoded into `-EncodedCommand`. Two layers of base64 * over UTF-16 cost about 14.2 command-line characters per XML character, and a * replacement carries two payloads, so a ~2 KB task definition pushed the outer command * past the Windows limit and the spawn failed with ENAMETOOLONG before UAC ever * appeared (#4692). On a host where the trigger scope exports as an account name the * re-register path runs on every repair, so repair could never succeed. * * The command now carries two paths and two 64-character digests, so its length no * longer depends on the size of the XML at all. * * The unelevated launcher opens every ancestor and payload with OPEN_REPARSE_POINT, * validates its type, and holds them until the elevated process exits: ancestors deny * delete sharing (read/write stay shared, so sibling files can still be staged) and * each payload denies write/delete sharing. * Thus the privileged open cannot be redirected during UAC; the length and digest are * defense in depth for the bytes read from the pinned regular file. * * The replacement precondition is unchanged: the elevated process still re-queries the * live registration and compares it to the captured predecessor before passing -Force. */ export function runWindowsElevatedScheduledTaskRegistration( taskName: string, xml: StagedWindowsTaskXml, replace = false, expectedExisting?: StagedWindowsTaskXml, ): Promise<number> { if (replace && !expectedExisting) { throw new Error("Elevated Task Scheduler replacement requires a captured existing definition."); } for (const payload of [xml, expectedExisting].filter((value): value is StagedWindowsTaskXml => value !== undefined)) { if (!Number.isSafeInteger(payload.byteLength) || payload.byteLength < 0 || !/^[0-9a-f]{64}$/.test(payload.sha256)) { throw new Error("Elevated Task Scheduler staging metadata is invalid."); } } const powerShellPath = windowsPowerShell(); const powerShellDirectory = powerShellPath.replace(/[\\/][^\\/]+$/, ""); const scheduledTasksModule = `${powerShellDirectory}\\Modules\\ScheduledTasks\\ScheduledTasks.psd1`; const parentDirectory = (path: string) => path.replace(/[\\/][^\\/]+$/, ""); const stageDirectory = parentDirectory(xml.path); // The pin only covers the staging directory itself: a payload nested deeper // would sit inside a folder nobody locked, so each file must name the staging // directory as its immediate parent rather than merely carrying its prefix. // Traversal segments are rejected on either separator before the parent is // compared, and a bare filename has no parent directory at all. const stagedDirectlyInside = (path: string) => !path.split(/[\\/]+/).includes("..") && parentDirectory(path) === stageDirectory && parentDirectory(path) !== path; if ( !stagedDirectlyInside(xml.path) || (expectedExisting && !stagedDirectlyInside(expectedExisting.path)) ) { throw new Error("Elevated Task Scheduler payloads must share one staging directory."); } const inner = [ `$taskName = ${psSingleQuote(taskName)}`, READ_STAGED_TASK_XML, `$xml = Read-OcxStagedTaskXml ${psSingleQuote(xml.path)} ${xml.byteLength} ${psSingleQuote(xml.sha256)}`, `$module = Microsoft.PowerShell.Core\\Import-Module -Name ${psSingleQuote(scheduledTasksModule)} -PassThru -Force -ErrorAction Stop`, "$registerTask = $module.ExportedCommands['Register-ScheduledTask']", "if ($null -eq $registerTask) { throw 'Trusted ScheduledTasks module does not export Register-ScheduledTask.' }", ...(replace ? [ `$expectedXml = Read-OcxStagedTaskXml ${psSingleQuote(expectedExisting!.path)} ${expectedExisting!.byteLength} ${psSingleQuote(expectedExisting!.sha256)}`, `$schtasks = ${psSingleQuote(resolveTrustedWindowsSchtasksExe())}`, "$currentXml = & $schtasks /query /tn $taskName /xml 2>$null | Out-String", "if ($LASTEXITCODE -ne 0) { throw 'Task Scheduler replacement precondition could not be read.' }", "function Normalize-OcxTaskXml([string]$value) { return (($value.TrimStart([char]0xFEFF) -replace \"`r`n?\", \"`n\").Trim()) }", "if ((Normalize-OcxTaskXml $currentXml) -cne (Normalize-OcxTaskXml $expectedXml)) { throw 'Task Scheduler replacement precondition changed.' }", ] : []), `& $registerTask -TaskName $taskName -Xml $xml${replace ? " -Force" : ""} -ErrorAction Stop | Out-Null`, ].join("; "); const encodedCommand = Buffer.from(inner, "utf16le").toString("base64"); const script = [ "Add-Type -TypeDefinition 'using System; using System.Runtime.InteropServices; public static class OcxStageLock { [StructLayout(LayoutKind.Sequential)] public struct TagInfo { public uint Attributes; public uint Tag; } [DllImport(\"kernel32.dll\", CharSet=CharSet.Unicode, SetLastError=true)] public static extern Microsoft.Win32.SafeHandles.SafeFileHandle CreateFile(string p, uint a, uint s, IntPtr q, uint c, uint f, IntPtr t); [DllImport(\"kernel32.dll\", SetLastError=true)] public static extern bool GetFileInformationByHandleEx(Microsoft.Win32.SafeHandles.SafeFileHandle h, int c, out TagInfo i, uint n); }';", "$locks = @();", "function Lock-OcxStage([string]$path, [bool]$directory) { $flags = 0x00200000; $share = 1; if ($directory) { $flags = $flags -bor 0x02000000; $share = 3 }; $h = [OcxStageLock]::CreateFile($path, 0x80000000, $share, [IntPtr]::Zero, 3, $flags, [IntPtr]::Zero); if ($h.IsInvalid) { throw 'Task Scheduler staging lock failed.' }; $info = [OcxStageLock+TagInfo]::new(); if (![OcxStageLock]::GetFileInformationByHandleEx($h, 9, [ref]$info, 8) -or (($info.Attributes -band 0x400) -ne 0) -or $directory -ne (($info.Attributes -band 0x10) -ne 0)) { $h.Dispose(); throw 'Task Scheduler staging path is redirected or has the wrong type.' }; $script:locks += $h };", `$dir = [IO.DirectoryInfo]::new(${psSingleQuote(stageDirectory)}); $dirs = @(); while ($null -ne $dir) { $dirs += $dir.FullName; $dir = $dir.Parent }; [array]::Reverse($dirs); $dirs | ForEach-Object { Lock-OcxStage $_ $true };`, `Lock-OcxStage ${psSingleQuote(xml.path)} $false;`, ...(expectedExisting ? [`Lock-OcxStage ${psSingleQuote(expectedExisting.path)} $false;`] : []), "try {", `$p = Start-Process -FilePath ${psSingleQuote(powerShellPath)}`, ` -ArgumentList ${psSingleQuote(buildWindowsElevatedArgumentList([ "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-EncodedCommand", encodedCommand, ]))}`, " -Verb RunAs -WindowStyle Hidden -PassThru -Wait;", `if ($null -eq $p) { exit ${OCX_ELEVATED_UAC_CANCELLED} }`, "$null = $p.Handle;", `if ($null -eq $p.ExitCode) { exit ${OCX_ELEVATED_PROTOCOL_FAILED} }`, "$code = $p.ExitCode } finally { $locks | ForEach-Object { $_.Dispose() } }; exit $code", ].join(""); return startPowerShellCommand(script).completion.then(result => result.exitCode); } /** * Build the elevated (post-UAC) script: create → run → optional delete rollback. * Returns only OpenCodex protocol exit codes (never raw schtasks codes, never 1223). * Does not write through any user-controlled pathname. */ export function buildElevatedSchtasksCreateAndRunScript( schtasksPath: string, createArgs: string[], runArgs: string[], deleteArgs: string[], ): string { const createList = buildWindowsElevatedArgumentList(createArgs); const runList = buildWindowsElevatedArgumentList(runArgs); const deleteList = buildWindowsElevatedArgumentList(deleteArgs); return [ `$schtasks = ${psSingleQuote(schtasksPath)}`, "function Invoke-OcxSchtasks([string]$ArgList) {", " $p = Start-Process -FilePath $schtasks -ArgumentList $ArgList -Wait -PassThru -WindowStyle Hidden", " if ($null -eq $p) { return 1 }", " $null = $p.Handle", " if ($null -eq $p.ExitCode) { return 1 }", " return [int]$p.ExitCode", "}", `$createCode = Invoke-OcxSchtasks ${psSingleQuote(createList)}`, `if ($createCode -ne 0) { exit ${OCX_ELEVATED_CREATE_FAILED} }`, `$runCode = Invoke-OcxSchtasks ${psSingleQuote(runList)}`, `if ($runCode -eq 0) { exit ${OCX_ELEVATED_SUCCESS} }`, `$deleteCode = Invoke-OcxSchtasks ${psSingleQuote(deleteList)}`, `if ($deleteCode -eq 0) { exit ${OCX_ELEVATED_RUN_FAILED_ROLLED_BACK} }`, `exit ${OCX_ELEVATED_RUN_FAILED_ROLLBACK_FAILED}`, ].join("; "); } export interface ElevatedSchtasksCreateAndRunResult { outcome: ElevatedSchedulerOutcome; exitCode: number; stdout: string; stderr: string; } export interface ElevatedSchtasksCreateAndRunExecution { completion: Promise<ElevatedSchtasksCreateAndRunResult>; launcherPid: number | null; } /** * Start create/run/rollback inside one elevated PowerShell process (one UAC prompt). * The completion promise outlives any request-level timeout — do not kill the launcher. */ export function startElevatedSchtasksCreateAndRun( schtasksPath: string, createArgs: string[], runArgs: string[], deleteArgs: string[], ): ElevatedSchtasksCreateAndRunExecution { const inner = buildElevatedSchtasksCreateAndRunScript(schtasksPath, createArgs, runArgs, deleteArgs); const launcher = [ `$p = Start-Process -FilePath ${psSingleQuote(windowsPowerShell())}`, ` -ArgumentList ${psSingleQuote(buildWindowsElevatedArgumentList([ "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", inner, ]))}`, " -Verb RunAs -WindowStyle Hidden -PassThru -Wait;", `if ($null -eq $p) { exit ${OCX_ELEVATED_UAC_CANCELLED} }`, "$null = $p.Handle;", `if ($null -eq $p.ExitCode) { exit ${OCX_ELEVATED_PROTOCOL_FAILED} }`, "exit $p.ExitCode", ].join(""); const started = startPowerShellCommand(launcher); return { launcherPid: started.launcherPid, completion: started.completion.then(result => ({ outcome: classifyElevatedSchedulerExitCode(result.exitCode), exitCode: result.exitCode, stdout: result.stdout, stderr: result.stderr, })), }; } /** * Create, run, and (on /run failure) roll back the scheduler task inside one elevated * PowerShell process — one UAC prompt, no user-controlled result file. * Waits for the full elevated transaction (no request-timeout kill). */ export function runElevatedSchtasksCreateAndRun( schtasksPath: string, createArgs: string[], runArgs: string[], deleteArgs: string[], ): Promise<ElevatedSchtasksCreateAndRunResult> { return startElevatedSchtasksCreateAndRun(schtasksPath, createArgs, runArgs, deleteArgs).completion; }