fix: Various improvements.

Signed-off-by: Paolo Insogna <paolo@cowtech.it>
nodejs · cjihrig · Feb 25, 2026 · Mar 12, 2026 · Mar 17, 2026 · Mar 19, 2026
commit 55a94dfcf80c72f9cbeb0cabd40484c89c162a9c
diff --git a/.github/workflows/tools.yml b/.github/workflows/tools.yml
@@ -26,6 +26,7 @@ on:
           - histogram
           - icu
           - inspector_protocol
+          - libffi
           - libuv
           - llhttp
           - minimatch
@@ -161,6 +162,14 @@ jobs:
               cat temp-output
               tail -n1 temp-output | grep "NEW_VERSION=" >> "$GITHUB_ENV" || true
               rm temp-output
+          - id: libffi
+            subsystem: deps
+            label: dependencies, ffi
+            run: |
+              ./tools/dep_updaters/update-libffi.sh > temp-output
+              cat temp-output
+              tail -n1 temp-output | grep "NEW_VERSION=" >> "$GITHUB_ENV" || true
+              rm temp-output
           - id: libuv
             subsystem: deps
             label: dependencies

diff --git a/configure.py b/configure.py
@@ -2214,8 +2214,8 @@ def without_sqlite_error(option):
 
 def bundled_ffi_supported(os_name, target_arch):
   supported = {
-    'freebsd': {'arm', 'arm64', 'ia32', 'x64'},
-    'linux': {'arm', 'arm64', 'ia32', 'x64'},
+    'freebsd': {'arm', 'arm64', 'x64'},
+    'linux': {'arm', 'arm64', 'x64'},
     'mac': {'arm64', 'x64'},
     'win': {'arm', 'arm64', 'x64'},
   }

diff --git a/deps/libffi/generate-headers.py b/deps/libffi/generate-headers.py
@@ -11,19 +11,14 @@
 TARGETS = {
     ('freebsd', 'arm'): ('ARM', 'arm'),
     ('freebsd', 'arm64'): ('AARCH64', 'aarch64'),
-    ('freebsd', 'ia32'): ('X86_FREEBSD', 'x86'),
     ('freebsd', 'x64'): ('X86_64', 'x86'),
-    ('freebsd', 'x86'): ('X86_FREEBSD', 'x86'),
     ('linux', 'arm'): ('ARM', 'arm'),
     ('linux', 'arm64'): ('AARCH64', 'aarch64'),
-    ('linux', 'ia32'): ('X86', 'x86'),
     ('linux', 'x64'): ('X86_64', 'x86'),
-    ('linux', 'x86'): ('X86', 'x86'),
     ('mac', 'arm64'): ('AARCH64', 'aarch64'),
     ('mac', 'x64'): ('X86_64', 'x86'),
     ('win', 'arm'): ('ARM_WIN32', 'arm'),
     ('win', 'arm64'): ('ARM_WIN64', 'aarch64'),
-    ('win', 'ia32'): ('X86', 'x86'),
     ('win', 'x64'): ('X86_WIN64', 'x86'),
 }
 

diff --git a/deps/libffi/libffi.gyp b/deps/libffi/libffi.gyp
@@ -47,12 +47,6 @@
             ],
           },
         }],
-        ['target_arch == "ia32" or target_arch == "x86"', {
-          # Windows x86 is not supported by libffi
-          'variables': {
-            'libffi_arch_sources': [],
-          },
-        }],
       ],
     }],
     ['OS == "linux" or OS == "freebsd"', {
@@ -65,14 +59,6 @@
             ],
           },
         }],
-        ['target_arch == "ia32" or target_arch == "x86"', {
-          'variables': {
-            'libffi_arch_sources': [
-              'src/x86/ffi.c',
-              'src/x86/sysv.S',
-            ],
-          },
-        }],
         ['target_arch == "arm"', {
           'variables': {
             'libffi_arch_sources': [

diff --git a/doc/api/cli.md b/doc/api/cli.md
@@ -202,7 +202,8 @@ added: REPLACEME
 When using the [Permission Model][], the process will not be able to use FFI
 APIs by default. Attempts to use FFI APIs will throw an `ERR_ACCESS_DENIED`
 exception unless the user explicitly passes the `--allow-ffi` flag when
-starting Node.js.
+starting Node.js. The [`node:ffi`][] module also requires the
+`--experimental-ffi` flag and is only available in builds with FFI support.
 
 Example:
 
@@ -1185,6 +1186,8 @@ added: REPLACEME
 
 Enable the experimental [`node:ffi`][] module.
 
+This flag is only available in builds with FFI support.
+
 ### `--experimental-import-meta-resolve`
 
 <!-- YAML
@@ -1996,6 +1999,8 @@ added: REPLACEME
 
 Disable the experimental [`node:ffi`][] module.
 
+This flag is only available in builds with FFI support.
+
 ### `--no-experimental-sqlite`
 
 <!-- YAML

diff --git a/doc/api/ffi.md b/doc/api/ffi.md
@@ -27,8 +27,8 @@ import ffi from 'node:ffi';
 const ffi = require('node:ffi');
 ```
 
-This module is only available under the `node:` scheme and is gated by the
-`--experimental-ffi` flag.
+This module is only available under the `node:` scheme in builds with FFI
+support and is gated by the `--experimental-ffi` flag.
 
 When using the [Permission Model][], FFI APIs are restricted unless the
 [`--allow-ffi`][] flag is provided.
@@ -69,6 +69,12 @@ Supported type names:
 Pointer-like types (`pointer`, `string`, `buffer`, `arraybuffer`, and
 `function`) are all passed through the native layer as pointers.
 
+The `char` type follows the platform C ABI. On platforms where plain C `char`
+is signed it behaves like `i8`; otherwise it behaves like `u8`.
+
+The `bool` type is marshaled as an 8-bit unsigned integer. Pass numeric values
+such as `0` and `1`; JavaScript `true` and `false` are not accepted.
+
 ## Signature objects
 
 Functions and callbacks are described with signature objects.

diff --git a/doc/api/permissions.md b/doc/api/permissions.md
@@ -71,7 +71,8 @@ using the [`--allow-child-process`][] and [`--allow-worker`][] respectively.
 To allow network access, use [`--allow-net`][] and for allowing native addons
 when using permission model, use the [`--allow-addons`][]
 flag. For WASI, use the [`--allow-wasi`][] flag. For FFI, use the
-[`--allow-ffi`][] flag.
+[`--allow-ffi`][] flag. The [`node:ffi`][] module also requires the
+`--experimental-ffi` flag and is only available in builds with FFI support.
 
 #### Runtime API
 

diff --git a/doc/contributing/maintaining/maintaining-dependencies.md b/doc/contributing/maintaining/maintaining-dependencies.md
@@ -20,6 +20,7 @@ This a list of all the dependencies:
 * [histogram][]
 * [icu-small][]
 * [inspector\_protocol][inspector_protocol]
+* [libffi][]
 * [libuv][]
 * [llhttp][]
 * [minimatch][]
@@ -279,6 +280,11 @@ The [inspector\_protocol](https://chromium.googlesource.com/deps/inspector_proto
 is Chromium's of code generators and templates for the inspector protocol.
 See [this doc](../../../tools/inspector_protocol/README.md) for more information.
 
+### libffi
+
+The [libffi](https://github.com/libffi/libffi) dependency is a portable foreign
+function interface library used by `node:ffi`.
+
 ### libuv
 
 The [libuv](https://github.com/libuv/libuv) dependency is a
@@ -418,6 +424,7 @@ according to [RFC 8878](https://datatracker.ietf.org/doc/html/rfc8878).
 [histogram]: #histogram
 [icu-small]: #icu-small
 [inspector_protocol]: #inspector_protocol
+[libffi]: #libffi
 [libuv]: #libuv
 [llhttp]: #llhttp
 [maintaining-V8]: ./maintaining-V8.md

diff --git a/doc/node-config-schema.json b/doc/node-config-schema.json
@@ -24,7 +24,7 @@
         },
         "allow-ffi": {
           "type": "boolean",
-          "description": "allow use of FFI when any permissions are set"
+          "description": "allow use of FFI when any permissions are set (only in builds with FFI support)"
         },
         "allow-fs-read": {
           "oneOf": [
@@ -176,7 +176,7 @@
         },
         "experimental-ffi": {
           "type": "boolean",
-          "description": "experimental node:ffi module"
+          "description": "experimental node:ffi module (only in builds with FFI support)"
         },
         "experimental-global-navigator": {
           "type": "boolean",
@@ -774,7 +774,7 @@
         },
         "allow-ffi": {
           "type": "boolean",
-          "description": "allow use of FFI when any permissions are set"
+          "description": "allow use of FFI when any permissions are set (only in builds with FFI support)"
         },
         "allow-child-process": {
           "type": "boolean",

diff --git a/lib/ffi.js b/lib/ffi.js
@@ -8,6 +8,7 @@ const {
 } = require('internal/errors');
 const permission = require('internal/process/permission');
 const {
+  validateInteger,
   validateString,
 } = require('internal/validators');
 
@@ -45,7 +46,9 @@ function checkFFIPermission() {
     return;
   }
 
-  throw new ERR_ACCESS_DENIED('Access to this API has been restricted', 'FFI');
+  throw new ERR_ACCESS_DENIED(
+    'Access to this API has been restricted. Use --allow-ffi to manage permissions.',
+    'FFI');
 }
 
 function dlopen(path, definitions) {
@@ -58,6 +61,7 @@ function dlopen(path, definitions) {
 }
 
 function dlclose(handle) {
+  checkFFIPermission();
   handle.close();
 }
 
@@ -70,8 +74,9 @@ function exportString(str, data, len, encoding = 'utf8') {
   checkFFIPermission();
   validateString(str, 'string');
   validateString(encoding, 'encoding');
+  validateInteger(len, 'len', 0);
 
-  if (len <= 0) {
+  if (len === 0) {
     return;
   }
 
@@ -90,7 +95,9 @@ function exportBuffer(buffer, data, len) {
     throw new ERR_INVALID_ARG_TYPE('buffer', 'Buffer', buffer);
   }
 
-  if (len <= 0) {
+  validateInteger(len, 'len', 0);
+
+  if (len === 0) {
     return;
   }
 

diff --git a/lib/internal/process/permission.js b/lib/internal/process/permission.js
@@ -10,6 +10,7 @@ const { Buffer } = require('buffer');
 const { isBuffer } = Buffer;
 
 let _permission;
+const hasFFI = Boolean(process.config.variables.node_use_ffi);
 
 module.exports = ObjectFreeze({
   __proto__: null,
@@ -34,16 +35,21 @@ module.exports = ObjectFreeze({
     return permission.has(scope, reference);
   },
   availableFlags() {
-    return [
+    const flags = [
       '--allow-fs-read',
       '--allow-fs-write',
       '--allow-addons',
       '--allow-child-process',
-      '--allow-ffi',
       '--allow-net',
       '--allow-inspector',
       '--allow-wasi',
       '--allow-worker',
     ];
+
+    if (hasFFI) {
+      flags.splice(4, 0, '--allow-ffi');
+    }
+
+    return flags;
   },
 });
diff --git a/lib/internal/process/pre_execution.js b/lib/internal/process/pre_execution.js
@@ -665,11 +665,13 @@ function initializePermission() {
     const warnFlags = [
       '--allow-addons',
       '--allow-child-process',
-      '--allow-ffi',
       '--allow-inspector',
       '--allow-wasi',
       '--allow-worker',
     ];
+    if (process.config.variables.node_use_ffi) {
+      warnFlags.splice(2, 0, '--allow-ffi');
+    }
     for (const flag of warnFlags) {
       if (getOptionValue(flag)) {
         process.emitWarning(

diff --git a/node.gni b/node.gni
@@ -44,10 +44,11 @@ declare_args() {
   node_use_sqlite = true
 
   # Build node with FFI support.
-  # Disabled in GN builds until libffi is wired up there.
+  # Disabled in GN builds. The unofficial GN build does not support node:ffi.
   node_use_ffi = false
 
   # Link against a shared libffi when FFI support is enabled.
+  # Unsupported in GN builds.
   node_shared_ffi = false
 
   # Use the specified path to system CA (PEM format) in addition to