Files
reverse-engineering-anything/src/windows/WindowsPrivateRuntime.ts
T
Saim Shafiqueandmorluto 731049ab9c fix(windows): gate transient writes on runtimeWriteTransient capability (#10607)
* fix(windows): gate transient writes on runtimeWriteTransient capability

A source checkout and the published 6.8.0 addon share package version
and native ABI 1, so the loader admits the older addon. JavaScript
staging then fails at source-transfer with Win32 87 because the addon
has no runtime_write_transient operation.

Native inspection now advertises runtimeWriteTransient, the loader
accepts it only as literal true, and writeTransientFile refuses before
dispatch with a typed nonretryable error pointing at an exact-source
rebuild. Older addons stay admitted for the controls they support.
Recovery text no longer presents a same-version tarball as enough for
an unreleased checkout.

Fixes #9286

* test(ghidra): expect the new native-authority remediation wording

The #9286 fix changed the doctor recovery text so a same-version
tarball is no longer presented as enough for an unreleased checkout;
the pinned expectation still asserted the old wording.

---------

Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
2026-11-18 15:28:36 -05:00

359 lines
12 KiB
TypeScript

import { win32 } from "node:path";
import { setTimeout as delay } from "node:timers/promises";
import { z } from "zod";
import {
ArtifactReaderFailure,
AnalysisCleanupLease,
} from "../resources/index.js";
import { PrivateRuntimeRootUnavailableError } from "../domain/privateRuntimeRootUnavailableError.js";
import { RuntimeControlUnavailableError } from "../domain/runtimeControlUnavailableError.js";
import {
requireWindowsNativeAuthority,
windowsFileIdentitySchema,
windowsHandleSchema,
type WindowsNativeAuthority,
} from "./WindowsNativeLoader.js";
import { errorMessage } from "../kernel/errorMessage.js";
const runtimeSchema = windowsFileIdentitySchema.extend({
path: z.string(),
handle: windowsHandleSchema,
privateDacl: z.literal(true),
});
const snapshotSchema = z.strictObject({
sha256: z.string().regex(/^[a-f0-9]{64}$/u),
source: windowsFileIdentitySchema,
snapshot: windowsFileIdentitySchema,
});
const fileSchema = windowsFileIdentitySchema.extend({
handle: windowsHandleSchema,
});
const runtimes = new Map<string, WindowsPrivateRuntime>();
// Retry only a proven pre-allocation sharing/lock conflict, never opaque text
// or an operation that may already own an unpublished runtime directory.
const transientRuntimeAdmissionSchema = z.object({
code: z.literal("ERR_REA_WINDOWS_NATIVE"),
win32Code: z.union([z.literal(32), z.literal(33)]),
runtimeAllocation: z.literal("not-started"),
});
const transientRuntimeCleanupSchema = z.object({
code: z.literal("ERR_REA_WINDOWS_NATIVE"),
win32Code: z.union([z.literal(32), z.literal(33)]),
});
const snapshotCancellationSchema = z.object({
code: z.literal("ERR_REA_WINDOWS_NATIVE"),
win32Code: z.literal(995),
});
/** A native snapshot acknowledged cancellation, with the caller reason retained. */
export class WindowsSnapshotCancelledError extends Error {
constructor(
readonly reason: unknown,
cause: unknown,
) {
super("Windows snapshot cancelled", { cause });
this.name = "WindowsSnapshotCancelledError";
}
}
/** A staged file must not fall back to an immutable lease or path-based write. */
export class WindowsRuntimeWriteTransientUnavailableError extends RuntimeControlUnavailableError {
readonly code = "windows-native-control-unavailable";
readonly control = "runtime-write-transient";
constructor() {
super(
"The Windows native artifact does not support transient private-runtime writes required by this source checkout.",
{
remediationAction:
"Matching package version alone is insufficient for a source checkout. Build the Windows native artifact from this exact source checkout using native/windows/README.md, or use the matching published release's source and artifact together. Repeating this request with the unchanged artifact will not succeed.",
},
);
this.name = "WindowsRuntimeWriteTransientUnavailableError";
}
}
const RUNTIME_CLEANUP_ATTEMPTS = 10;
const RUNTIME_CLEANUP_RETRY_DELAY_MS = 100;
/** Retain private DACL and path handles until native recursive cleanup settles. */
export class WindowsPrivateRuntime {
// One native snapshot can own cancellation for this runtime at a time. A
// second request throws ERROR_BUSY before #pending or its abort listener is
// replaced, so aborting a rejected request cannot cancel the accepted copy.
#pending: Promise<unknown> | undefined;
#closed = false;
#closing = false;
#closePromise: Promise<void> | undefined;
// Admitted files whose close failed. Removal retries these wrappers before
// the native tree walk. Dropping them leaves ancestor handles until GC, and
// those handles can make runtime_close fail with a sharing violation.
#unreleasedFiles: AnalysisCleanupLease[] = [];
private constructor(
readonly observation: z.infer<typeof runtimeSchema>,
private readonly authority: WindowsNativeAuthority,
) {}
/** Create a new directory with its private DACL installed at creation. */
static create(parent: string, prefix: string): WindowsPrivateRuntime {
const authority = requireWindowsNativeAuthority();
let observed: unknown;
try {
observed = authority.call("runtime_create", [parent, prefix]);
} catch (cause: unknown) {
if (
cause instanceof Error &&
transientRuntimeAdmissionSchema.safeParse(cause).success
)
throw new PrivateRuntimeRootUnavailableError(cause.message, {
cause,
retryable: true,
});
throw cause;
}
const observation = runtimeSchema.parse(observed);
const runtime = new WindowsPrivateRuntime(observation, authority);
runtimes.set(windowsRuntimeIdentityKey(observation), runtime);
return runtime;
}
/** Open a private child directory through retained, verified parent handles. */
mkdir(relativePath: string): void {
this.#assertOpen();
this.authority.call("runtime_mkdir", [
this.observation.handle,
relativePath,
]);
}
/** Write a new private file once and retain its immutable handle. */
writeFile(relativePath: string, content: string): void {
this.#assertOpen();
this.authority.call("runtime_write", [
this.observation.handle,
relativePath,
Buffer.from(content),
]);
}
/**
* Write a new private file once, flush, and close the writer without retaining
* it in `immutableFiles`. Use for staged job inputs that a child must read and
* the parent must later `rm` while the runtime lease stays open.
*/
writeTransientFile(relativePath: string, content: string): void {
this.#assertOpen();
if (this.authority.inspection.runtimeWriteTransient !== true)
throw new WindowsRuntimeWriteTransientUnavailableError();
this.authority.call("runtime_write_transient", [
this.observation.handle,
relativePath,
Buffer.from(content),
]);
}
/** Copy admitted source bytes and digest the bytes actually written. */
async snapshot(
sourcePath: string,
relativePath: string,
signal?: AbortSignal,
): Promise<z.infer<typeof snapshotSchema>> {
this.#assertOpen();
// Admission is synchronous; record ownership only after native acceptance.
const pending = Promise.resolve(
this.authority.call("runtime_snapshot", [
this.observation.handle,
sourcePath,
relativePath,
]),
);
this.#pending = pending;
const cancel = (): void => {
this.authority.call("runtime_snapshot_cancel", [this.observation.handle]);
};
signal?.addEventListener("abort", cancel, { once: true });
if (signal?.aborted === true) cancel();
try {
return snapshotSchema.parse(await pending);
} catch (cause: unknown) {
if (
signal?.aborted === true &&
snapshotCancellationSchema.safeParse(cause).success
)
throw new WindowsSnapshotCancelledError(signal.reason, cause);
throw cause;
} finally {
signal?.removeEventListener("abort", cancel);
if (this.#pending === pending) this.#pending = undefined;
}
}
/** Read a private endpoint from an opened file, without re-opening its path. */
readFile(relativePath: string, maximumBytes: number): string {
this.#assertOpen();
const file = fileSchema.parse(
this.authority.call("runtime_open", [
this.observation.handle,
relativePath,
]),
);
let text: string | undefined;
let primary: { readonly cause: unknown } | undefined;
let closeFailure:
| { readonly cause: unknown; readonly lease: AnalysisCleanupLease }
| undefined;
try {
if (file.size > maximumBytes)
throw new ArtifactReaderFailure(
"limit",
`Private runtime file exceeds its ${String(maximumBytes)}-byte bound`,
);
const chunks: Buffer[] = [];
for (let offset = 0; offset < file.size;) {
const value = z
.instanceof(Buffer)
.parse(
this.authority.call("read", [
file.handle,
offset,
Math.min(65_536, file.size - offset),
]),
);
if (value.length === 0)
throw new Error(
"Private runtime file ended before its observed size",
);
offset += value.length;
chunks.push(value);
}
text = Buffer.concat(chunks).toString("utf8");
} catch (cause: unknown) {
primary = { cause };
} finally {
try {
this.authority.call("close", [file.handle]);
} catch (cause: unknown) {
const lease = new AnalysisCleanupLease(async () => {
this.authority.call("close", [file.handle]);
}, [file.requestedPath]);
this.#unreleasedFiles.push(lease);
closeFailure = { cause, lease };
}
}
if (closeFailure !== undefined)
throw ArtifactReaderFailure.withCleanup(
primary === undefined ? closeFailure.cause : primary.cause,
{
reason: errorMessage(closeFailure.cause),
resources: [file.requestedPath],
},
undefined,
[closeFailure.lease],
);
if (primary !== undefined) throw primary.cause;
if (text === undefined)
throw new Error("Private runtime read completed without text");
return text;
}
/** Remove owned objects by handle, unlinking reparse entries without traversal. */
close(): Promise<void> {
this.#closing = true;
this.#closePromise ??= this.#remove().catch((cause: unknown) => {
this.#closePromise = undefined;
throw cause;
});
return this.#closePromise;
}
#assertOpen(): void {
if (this.#closing)
throw new Error(
"Windows private runtime cleanup is in progress or complete",
);
}
async #remove(): Promise<void> {
if (this.#closed) return;
if (this.#pending !== undefined)
this.authority.call("runtime_snapshot_cancel", [this.observation.handle]);
await this.#pending?.catch(() => undefined);
await this.#closeRuntime();
this.#closed = true;
runtimes.delete(windowsRuntimeIdentityKey(this.observation));
}
/** Close admitted files that survived readFile before walking the tree. */
async #releaseAdmittedFiles(): Promise<void> {
const pending = this.#unreleasedFiles.splice(0);
let failure: unknown;
for (const lease of pending) {
try {
await lease.release();
} catch (cause: unknown) {
this.#unreleasedFiles.push(lease);
failure ??= cause;
}
}
if (failure !== undefined) throw failure;
}
async #closeRuntime(): Promise<void> {
for (let attempt = 1; ; attempt++) {
try {
await this.#releaseAdmittedFiles();
this.authority.call("runtime_close", [this.observation.handle]);
return;
} catch (cause: unknown) {
if (
attempt >= RUNTIME_CLEANUP_ATTEMPTS ||
!transientRuntimeCleanupSchema.safeParse(cause).success
)
throw cause;
// Native cleanup retains the same owned root and permits only another
// close after a failed walk. Retry that owner operation briefly when
// Windows reports a sharing/lock conflict; other errors remain final.
await delay(RUNTIME_CLEANUP_RETRY_DELAY_MS);
}
}
}
}
/** File id returned by the OS. Path spelling is not part of the lease key. */
const windowsRuntimeIdentityKey = (identity: {
readonly volumeSerial: string;
readonly fileId: string;
}): string => `${identity.volumeSerial}:${identity.fileId}`;
/**
* Select an already-owned runtime. Only the observed `path` or `finalPath`
* matches, character for character. A case variant fails closed.
*/
export const windowsPrivateRuntime = (
rootPath: string,
): WindowsPrivateRuntime => {
const matches = [...runtimes.values()].filter(
(runtime) =>
runtime.observation.finalPath === rootPath ||
runtime.observation.path === rootPath,
);
const runtime = matches[0];
if (matches.length !== 1 || runtime === undefined)
throw new Error(`No native private runtime owns ${rootPath}`);
return runtime;
};
/** Read a runtime endpoint using the lease that owns its parent directory. */
export const readWindowsPrivateRuntimeFile = (
path: string,
maximumBytes: number,
): string => {
const parent = win32.dirname(path);
return windowsPrivateRuntime(parent).readFile(
win32.basename(path),
maximumBytes,
);
};