Add docs, fix some review comments

Author: timokoessler

docs/esm.md

@@ -0,0 +1,44 @@
+# Adding Zen to an ESM application
+
+> [!WARNING]  
+> The new instrumentation system with ESM support is still under active development and not suitable for production use.
+
+Modify the start command of your application to include the Zen firewall:
+
+```sh
+node -r @aikidosec/firewall/instrument your-app.js
+```
+
+Alternatively, you can set the `NODE_OPTIONS` environment variable to include the Zen firewall:
+
+```sh
+export NODE_OPTIONS='-r @aikidosec/firewall/instrument'
+```
+
+> [!IMPORTANT]  
+> Please also check the documentation on how to integrate Zen with your used web framework.
+
+## Blocking mode
+
+By default, the firewall will run in non-blocking mode. When it detects an attack, the attack will be reported to Aikido if the environment variable `AIKIDO_TOKEN` is set and continue executing the call.
+
+You can enable blocking mode by setting the environment variable `AIKIDO_BLOCK` to `true`:
+
+```sh
+AIKIDO_BLOCK=true node app.js
+```
+
+It's recommended to enable this on your staging environment for a considerable amount of time before enabling it on your production environment (e.g. one week).
+
+## Known issues
+
+- The app might crash on startup if used together with some packages that use the Node.js Asynchronous Module Customization Hooks, like the tapjs test runner, due to bugs in Node.js itself.
+- Zen can not protect ESM sub-dependencies of a ESM package. For example if a ESM package `foo` imports a sub-dependency `bar` that is also an ESM package, Zen will not be able to protect the code in `bar`. This is because the V8 engine does not allow Node.js to observe the evaluation of inner ESM packages (yet).
+
+Relevant links:
+
+- [ERR_INVALID_RETURN_PROPERTY_VALUE when using module.register and module.registerHooks (#57327)](https://github.com/nodejs/node/issues/57327)
+- [module.registerHooks() tracking issue (#56241)](https://github.com/nodejs/node/issues/56241)
+- [TypeError when json file is required in hook and in the imported file (#57358)](https://github.com/nodejs/node/issues/57358)
+- [ERR_INTERNAL_ASSERTION: Unexpected module status 3 (#58515)](https://github.com/nodejs/node/issues/58515)
+- [Adding an evaluation hook for v8::Module](https://issues.chromium.org/u/1/issues/384413088)

library/agent/hooks/instrumentation/wrapBuiltinExports.ts

@@ -23,7 +23,7 @@ export function wrapBuiltinExports(id: string, exports: unknown): unknown {
     try {
       const returnVal = interceptor(exports, pkgInfo);
       // If the interceptor returns a value, we want to use this value as the new exports
-      if (typeof returnVal !== "undefined") {
+      if (returnVal !== undefined) {
         exports = returnVal;
       }
     } catch (error) {

library/agent/hooks/wrapRequire.ts

@@ -287,7 +287,7 @@ function executeInterceptors(
     try {
       const returnVal = interceptor(exports, wrapPackageInfo);
       // If the interceptor returns a value, we want to use this value as the new exports
-      if (typeof returnVal !== "undefined") {
+      if (returnVal !== undefined) {
         exports = returnVal;
       }
     } catch (error) {

scripts/build.js

@@ -8,7 +8,20 @@ const {
   verifyFileHash,
   extractTar,
 } = require("./helpers/internals");
-const execAsync = promisify(exec);
+
+// Helper to run exec async and pipe stdout/stderr
+async function execAsyncWithPipe(command, options) {
+  const child = exec(command, options);
+  child.stdout && child.stdout.pipe(process.stdout);
+  child.stderr && child.stderr.pipe(process.stderr);
+  return new Promise((resolve, reject) => {
+    child.on("close", (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`Command failed: ${command} (exit code ${code})`));
+    });
+    child.on("error", reject);
+  });
+}
 
 // Zen Internals configuration
 const INTERNALS_VERSION = "v0.1.41";
@@ -37,7 +50,7 @@ async function main() {
   await dlZenInternals();
   await buildInstrumentationWasm();
 
-  await execAsync(`npm run build`, {
+  await execAsyncWithPipe(`npm run build`, {
     cwd: libDir,
   });
 
@@ -134,7 +147,7 @@ async function modifyDtsFilesAfterBuild() {
 
 async function buildInstrumentationWasm() {
   // Build Instrumentation WASM
-  await execAsync(
+  await execAsyncWithPipe(
     `wasm-pack build --release --target nodejs --out-dir ${instrumentationWasmOutDir}`,
     {
       cwd: instrumentationWasmDir,