feat(instrumentor): apply function hooks to ESM modules via MessagePort

Establishes a MessagePort channel between the main thread and the ESM
loader thread.  After bug detectors register their hooks and
finalizeHooks() completes, sendHooksToLoader() serializes the hook
metadata (type, target, pkg, async, id) and posts it to the loader.

The loader uses receiveMessageOnPort() — a synchronous, non-blocking
read — to drain the message queue at the start of each instrumentModule()
call.  Received hooks are registered as stubs (with no-op functions) in
the loader's own hookManager singleton, which the functionHooks Babel
plugin reads from.  At runtime, the instrumented code calls
HookManager.callHook(id, ...) on the main-thread global, where the real
hook functions live.

Explicit hook IDs in the serialization format guard against index
mismatches between threads; the loader asserts that each stub's position
matches the main thread's.  The MessagePort requires Node >= 20.11
(transferList in module.register); older 20.x builds gracefully degrade
to ESM instrumentation without function hooks.

Author: oetr

packages/core/core.ts

@@ -125,6 +125,12 @@ export async function initFuzzing(
 		getJazzerJsGlobal<vm.Context>("vmContext") ?? globalThis,
 	);
 
+	// Send the finalized hook definitions to the ESM loader thread
+	// so it can apply function-hook transforms to user modules.
+	// This must happen after finalizeHooks (hooks are complete) and
+	// before loadFuzzFunction (user modules are imported).
+	instrumentor.sendHooksToLoader();
+
 	return instrumentor;
 }
 

packages/instrumentor/esm-loader.mts

@@ -27,6 +27,7 @@
 import type { PluginItem } from "@babel/core";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
+import { receiveMessageOnPort, type MessagePort } from "node:worker_threads";
 
 // Load CJS-compiled Babel plugins via createRequire so we don't
 // depend on Node.js CJS-named-export detection (varies by version).
@@ -39,6 +40,14 @@ const { compareHooks } =
 	require("./plugins/compareHooks.js") as typeof import("./plugins/compareHooks.js");
 const { sourceCodeCoverage } =
 	require("./plugins/sourceCodeCoverage.js") as typeof import("./plugins/sourceCodeCoverage.js");
+const { functionHooks } =
+	require("./plugins/functionHooks.js") as typeof import("./plugins/functionHooks.js");
+
+// The loader thread has its own CJS module cache, so this is a
+// separate HookManager instance from the main thread's.  We populate
+// it with stub hooks from the serialized data we receive via the port.
+const { hookManager: loaderHookManager } =
+	require("@jazzer.js/hooking") as typeof import("@jazzer.js/hooking");
 
 // Already-instrumented code contains this marker.
 const INSTRUMENTATION_MARKER = "Fuzzer.coverageTracker.incrementCounter";
@@ -50,12 +59,17 @@ interface LoaderConfig {
 	includes: string[];
 	excludes: string[];
 	coverage: boolean;
+	port?: MessagePort;
 }
 
 let config: LoaderConfig;
+let loaderPort: MessagePort | null = null;
 
 export function initialize(data: LoaderConfig): void {
 	config = data;
+	if (data.port) {
+		loaderPort = data.port;
+	}
 }
 
 interface LoadResult {
@@ -109,6 +123,8 @@ export const load: LoadFn = async function load(url, context, nextLoad) {
 // ── Instrumentation ──────────────────────────────────────────────
 
 function instrumentModule(code: string, filename: string): string | null {
+	drainHookUpdates();
+
 	const fuzzerCoverage = esmCodeCoverage();
 
 	const plugins: PluginItem[] = [fuzzerCoverage.plugin, compareHooks];
@@ -121,6 +137,14 @@ function instrumentModule(code: string, filename: string): string | null {
 		plugins.push(sourceCodeCoverage(filename));
 	}
 
+	// Apply function hooks if the main thread has sent hook definitions
+	// and any of them target functions in this file.  The instrumented
+	// code calls HookManager.callHook(id, ...) at runtime, which
+	// resolves to the real hook function on the main thread.
+	if (loaderHookManager.hasFunctionsToHook(filename)) {
+		plugins.push(functionHooks(filename));
+	}
+
 	let transformed: ReturnType<typeof transformSync>;
 	try {
 		transformed = transformSync(code, {
@@ -168,6 +192,55 @@ function instrumentModule(code: string, filename: string): string | null {
 	return preambleLines.join("\n") + "\n" + transformed.code;
 }
 
+// ── Function hooks from the main thread ──────────────────────────
+
+interface SerializedHook {
+	id: number;
+	type: number;
+	target: string;
+	pkg: string;
+	async: boolean;
+}
+
+const noop = () => {};
+
+/**
+ * Synchronously drain any hook-definition messages from the main
+ * thread.  Uses receiveMessageOnPort — a non-blocking, synchronous
+ * read — so we never have to await or restructure the load() flow.
+ *
+ * The main thread sends hook data after finalizeHooks() and before
+ * user modules are loaded, so the message is always available by the
+ * time we process user code.
+ */
+function drainHookUpdates(): void {
+	if (!loaderPort) return;
+
+	let msg;
+	while ((msg = receiveMessageOnPort(loaderPort))) {
+		const hooks = msg.message.hooks as SerializedHook[];
+		for (const h of hooks) {
+			const stub = loaderHookManager.registerHook(
+				h.type,
+				h.target,
+				h.pkg,
+				h.async,
+				noop,
+			);
+			// Sanity check: the stub's index in the loader must match the
+			// main thread's index so that runtime HookManager.callHook(id)
+			// invokes the correct hook function.
+			const actualId = loaderHookManager.hookIndex(stub);
+			if (actualId !== h.id) {
+				throw new Error(
+					`ESM hook ID mismatch: expected ${h.id}, got ${actualId} ` +
+						`for ${h.target} in ${h.pkg}`,
+				);
+			}
+		}
+	}
+}
+
 // ── Include / exclude filtering ──────────────────────────────────
 
 function shouldInstrument(filepath: string): boolean {

packages/instrumentor/esmFunctionHooks.test.ts

@@ -0,0 +1,206 @@
+/*
+ * Copyright 2026 Code Intelligence GmbH
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { transformSync } from "@babel/core";
+import { HookType, hookManager } from "@jazzer.js/hooking";
+
+import { Instrumentor, SerializedHook } from "./instrument";
+import { functionHooks } from "./plugins/functionHooks";
+
+/**
+ * These tests verify the ESM function-hook wiring: serialization of
+ * hooks on the main thread, registration of stubs in a simulated
+ * loader hookManager, and correct Babel output with matching IDs.
+ *
+ * We cannot spawn a real loader thread in a unit test, so we exercise
+ * the same logic inline: register stub hooks in the global hookManager
+ * (which the functionHooks plugin reads from) and verify the output.
+ */
+
+afterEach(() => {
+	hookManager.clearHooks();
+});
+
+describe("ESM function hook serialization", () => {
+	it("should serialize hooks with explicit IDs", () => {
+		hookManager.registerHook(
+			HookType.Before,
+			"execSync",
+			"child_process",
+			false,
+			() => {},
+		);
+		hookManager.registerHook(
+			HookType.Replace,
+			"fetch",
+			"node-fetch",
+			true,
+			() => {},
+		);
+
+		const serialized: SerializedHook[] = hookManager.hooks.map(
+			(hook, index) => ({
+				id: index,
+				type: hook.type,
+				target: hook.target,
+				pkg: hook.pkg,
+				async: hook.async,
+			}),
+		);
+
+		expect(serialized).toEqual([
+			{
+				id: 0,
+				type: HookType.Before,
+				target: "execSync",
+				pkg: "child_process",
+				async: false,
+			},
+			{
+				id: 1,
+				type: HookType.Replace,
+				target: "fetch",
+				pkg: "node-fetch",
+				async: true,
+			},
+		]);
+	});
+
+	it("should round-trip through JSON (MessagePort serialization)", () => {
+		hookManager.registerHook(HookType.After, "readFile", "fs", false, () => {});
+
+		const serialized: SerializedHook[] = hookManager.hooks.map(
+			(hook, index) => ({
+				id: index,
+				type: hook.type,
+				target: hook.target,
+				pkg: hook.pkg,
+				async: hook.async,
+			}),
+		);
+
+		// structuredClone simulates what MessagePort does
+		const received = structuredClone(serialized);
+		expect(received).toEqual(serialized);
+		expect(received[0].type).toBe(HookType.After);
+	});
+});
+
+describe("ESM function hook stub registration", () => {
+	it("should produce matching IDs when stubs are registered in order", () => {
+		// Simulate the main thread registering real hooks
+		const realHook1 = hookManager.registerHook(
+			HookType.Before,
+			"execSync",
+			"child_process",
+			false,
+			() => {},
+		);
+		const realHook2 = hookManager.registerHook(
+			HookType.Replace,
+			"connect",
+			"net",
+			false,
+			() => {},
+		);
+
+		const mainId1 = hookManager.hookIndex(realHook1);
+		const mainId2 = hookManager.hookIndex(realHook2);
+
+		// Serialize
+		const serialized: SerializedHook[] = hookManager.hooks.map(
+			(hook, index) => ({
+				id: index,
+				type: hook.type,
+				target: hook.target,
+				pkg: hook.pkg,
+				async: hook.async,
+			}),
+		);
+
+		// Clear and re-register as the loader thread would
+		hookManager.clearHooks();
+		for (const h of serialized) {
+			const stub = hookManager.registerHook(
+				h.type,
+				h.target,
+				h.pkg,
+				h.async,
+				() => {},
+			);
+			expect(hookManager.hookIndex(stub)).toBe(h.id);
+		}
+
+		// IDs in the loader match the original main-thread IDs
+		expect(hookManager.hookIndex(hookManager.hooks[0])).toBe(mainId1);
+		expect(hookManager.hookIndex(hookManager.hooks[1])).toBe(mainId2);
+	});
+});
+
+describe("ESM function hook Babel output", () => {
+	it("should insert HookManager.callHook with the correct hook ID", () => {
+		hookManager.registerHook(
+			HookType.Before,
+			"processInput",
+			"target-pkg",
+			false,
+			() => {},
+		);
+
+		const result = transformSync(
+			"function processInput(data) { return data.trim(); }",
+			{
+				filename: "/app/node_modules/target-pkg/index.js",
+				plugins: [functionHooks("/app/node_modules/target-pkg/index.js")],
+			},
+		);
+
+		expect(result?.code).toContain("HookManager.callHook(0,");
+		expect(result?.code).toContain("this, [data]");
+	});
+
+	it("should not hook functions in non-matching files", () => {
+		hookManager.registerHook(
+			HookType.Before,
+			"dangerous",
+			"target-pkg",
+			false,
+			() => {},
+		);
+
+		const result = transformSync("function dangerous(x) { return x; }", {
+			filename: "/app/node_modules/other-pkg/lib.js",
+			plugins: [functionHooks("/app/node_modules/other-pkg/lib.js")],
+		});
+
+		expect(result?.code).not.toContain("HookManager.callHook");
+	});
+
+	it("should use sendHooksToLoader to serialize from Instrumentor", () => {
+		hookManager.registerHook(
+			HookType.Before,
+			"exec",
+			"child_process",
+			false,
+			() => {},
+		);
+
+		const instrumentor = new Instrumentor();
+
+		// Without a port, sendHooksToLoader is a no-op (no crash)
+		expect(() => instrumentor.sendHooksToLoader()).not.toThrow();
+	});
+});