Files
codex-security/plugins/codex-security/native/README.md

15 KiB

Native OS primitives

These internal bindings supply OS operations that Node does not expose. The resolve-security-md helper uses native account lookup on Unix and native path, file, and directory operations on Windows.

Package inputs

For universal builds, SDK tests, or Docker builds, select a successful run for the checkout's native sources. You can run native-artifacts manually on a pushed branch. From the repository root, substitute the run ID and the full artifact name shown on that run. Pull request artifacts use the tested merge commit.

gh run download RUN_ID --name native-universal-COMMIT --dir plugins/codex-security/native/prebuilt

The ignored prebuilt directory must contain all eight platform directories and the shared notices. Refresh it after changing the native source or build toolchain. Missing payloads fail the build, including on hosts that only load one of them. Installed-package checks load the matching artifact with an empty PATH.

The native-artifacts workflow calls all three platform workflows and combines their eight verified payloads into native-universal-<commit>. PR validation jobs share one artifact assembled by node-ci; release and standalone validation runs assemble their own. By default, the standalone MCP builder and npm package include the same complete mcp/native tree with the default --native universal option; neither compiles nor downloads code at runtime.

The GNU x64 job also runs notices.mjs against the locked Cargo metadata. It collects crate licenses and the pinned Rust standard-library notices for both package surfaces. The NAPI crates omit license files from their registry archives, so licenses/napi.txt preserves their pinned upstream license. Review that override when upgrading those dependencies.

Build the standalone plugin for this host

Install the pinned Rust toolchain, then build the plugin from the repository root:

pnpm --dir plugins/codex-security/mcp-app install --frozen-lockfile
node plugins/codex-security/mcp-app/scripts/build_native.mjs
node plugins/codex-security/mcp-app/scripts/build_mcp_app.mjs --output plugins/codex-security/mcp --native host

build_native.mjs uses the MCP app's dependencies to compile the TypeScript tools, fetches the locked Cargo dependencies, and writes the host binary and license notices to native/dist. --native host packages those files for the current platform and architecture under mcp/, where the plugin launcher expects them. CI tests this build without the SDK on Linux, macOS, and Windows.

Build and verify the native bindings

The Unix Node-API 8 binding is typed in binding.mts. userHome looks up raw username bytes through the operating system and returns raw home-directory bytes or a missing result, without Git. unixEnvironment reads one named environment value as raw bytes, preserving the distinction between empty and unset values. This keeps configured filesystem locations such as CODEX_HOME intact when Node would replace undecodable bytes.

With the pinned Rust toolchain installed, build and verify the Unix binding from the repository root:

pnpm --dir plugins/codex-security/mcp-app install --frozen-lockfile
node plugins/codex-security/mcp-app/scripts/build_native.mjs
node plugins/codex-security/native/proof.mjs
(cd plugins/codex-security/native && cargo fmt --check && cargo clippy --locked -- -D warnings)

The proof runs without Python. It checks current and named account lookup, missing accounts, and embedded-NUL rejection. A shell-launched child verifies raw environment bytes, empty values and missing values. CI invokes it with an empty PATH.

Build outputs stay under ignored target and dist directories. Linux output directories include the C runtime: linux-x64-gnu, linux-arm64-gnu, linux-x64-musl, and linux-arm64-musl. The dependency-free platform.mts helper distinguishes glibc from musl using the Node diagnostic report header, without a subprocess. macOS and Windows retain their platform and architecture directories. Source, Cargo registry, and compiler paths are remapped before compilation; actual payload bytes are checked for private paths. Before an artifact is uploaded, run:

node plugins/codex-security/native/check.mjs

GNU Linux artifacts must import no glibc version newer than 2.28. Musl artifacts must be ELF images for the current architecture, depend on that architecture's musl library, and have no version requirements from glibc. GCC's own GLIBC_2.0 compatibility exports are attributed to libgcc_s.so.1, not the C library. Musl has no glibc-style symbol version floor, so its runtime compatibility also requires the load proofs below. macOS artifacts must declare a deployment target of 11.0 or earlier. A build from a newer GNU Linux workstation can pass the behavioral proof and still fail this distribution check.

The native-unix workflow builds Linux artifacts in digest-pinned manylinux 2.28 images. It mounts the pinned Rust toolchain and fetched Cargo registry, builds offline, and blocks Python commands during compilation. macOS builds set MACOSX_DEPLOYMENT_TARGET=11.0. CI verifies separate x64 and arm64 artifacts on both platforms using Node 20.0.0 and 22.13.0.

The native-musl workflow uses native x64 and arm64 Ubuntu workers with digest-pinned Rust 1.97.1 Alpine compiler images. Musl builds disable static CRT linkage so Node can load the shared library. After the ELF and private-path checks, each unchanged artifact runs the full proof in pinned Node 20.0.0 Alpine 3.17 and Node 22.13.0 Alpine 3.21 images, with musl 1.2.3 and 1.2.5 respectively. Compilation uses the locked registry offline; runtime containers mount only the source and artifact read-only. Python is absent, and proof processes receive an empty PATH.

Windows bindings and launcher

Windows uses windows-binding.mts and the same Rust crate. WindowsHandle owns a non-inheritable handle through Rust's File; explicit close() and garbage collection release it. Handles never cross into Node's CRT descriptor table. Paths and returned names are UTF-16LE buffers without a NUL terminator, preserving lone surrogates. Volume identities are decimal strings; file IDs retain all 128 bits in a buffer.

scan-read-binding.mts supplies the held read operations used by sealed-scan validation. openScanReadRoot holds a canonical directory; openFile traverses relative directory components without following links and opens only regular files. Unix uses descriptor-relative opens. Windows opens each ancestor with attribute-read and traversal access and holds it without delete sharing for the lifetime of the root and each open file. Files support chunked reads so consumers can check cancellation between chunks. verify checks that the root path still names the held directory. Explicit close and garbage collection release handles. Private-directory permissions and artifact path policy remain with the caller. The native proofs exercise nested reads, link rejection, root replacement, and handle lifetime on every target.

The binding exposes synchronous file and recursive directory creation, attributes and reparse tags, identity and final/opened names, read/write, and exact-handle rename and deletion. Rust's File supplies ordinary I/O. Calls return numeric Windows errors, including 6 for closed handles. Buffer ranges and path encoding are checked before use. Overlapped handles are unsupported because pending operations could retain native buffers beyond the call. Path authorization, ancestor traversal, and reparse-point policy remain the caller's responsibility.

Four additional operations preserve Windows strings at the Node boundary. windowsArguments returns the complete OS argument vector, including the executable and Node options, using Rust's CRT-compatible parser. windowsEnvironment reads one wide environment name and distinguishes an absent value (null) from an empty buffer. windowsAbsolutePath resolves against the native current directory and drive directories without requiring the destination to exist. windowsDirectoryEntries uses std::fs::read_dir and cached DirEntry::file_type() values without opening each child; names remain UTF-16LE, and construction or iteration failures return their numeric Windows error and an empty array. Directory symlinks and junctions have both directory and symbolic-link flags. The typed adapter exposes this enumerator through entriesWithTypes, which resolve-security-md --list uses on Windows. Assessment validation and deep-review worklists share the typed wide-path reader and writer.

windows-files.mts uses native absolute and final paths, preserving raw UTF-16 and the returned device prefix. Non-strict realpath resolves the nearest existing ancestor of a missing path; dangling links and other access errors remain errors. Callers must check containment independently. It follows native Windows path behavior rather than emulating Python's special cases for device names, whitespace, verbatim dot segments, and prefix removal. stat(path, false) retains exact symbolic-link and reparse-point metadata so callers can reject junction traversal independently of the enumerator's link label. The SDK's public runtime floor remains Node 22.13.0. Node 20.0.0 is an additional native-foundation compatibility proof; it does not change the SDK engine requirement.

Windows process arguments and working directories can also contain unpaired UTF-16 units. windows-process.mts runs a private Node subprocess shim that passes those values as bytes to runWindowsProcess; ordinary invocations still use Node directly. The native call inherits stdin, stdout, stderr, and the shim's environment. The shim joins a kill-on-close Job Object before starting the child and retains its handle until process exit. Descendants inherit membership, so terminating the shim also closes the child's streams. Startup errors return through Node IPC, separately from command stderr and exit status. The Windows proof checks raw arguments and working directories, binary stream forwarding, environment inheritance, exit status, startup errors, and termination cleanup. The file adapter's readChunks callback supports bounded reads and closes the handle when a consumer stops or throws.

Target NODE_OPTIONS, NODE_DEBUG, NODE_DEBUG_NATIVE, NODE_EXTRA_CA_CERTS, and NODE_V8_COVERAGE values travel through the same environment override payload instead of affecting the private shim's startup. This preserves relative preloads, certificate paths, and coverage directories in the target's working directory and keeps shim diagnostics out of the target's stderr. Node's automatic forwarding of parent coverage settings is preserved for the target. The one-command shim restores target environment overrides before lookup and changes to the target directory before launching it, so relative executable paths and PATH entries use that directory. Bare executable names check that directory when the Windows current-directory search setting permits it, then search each PATH directory in order. Early cancellation skips the IPC handoff and its cancellation-induced transport errors.

Every selected image uses CreateProcessW with that exact application name, because Rust's Command otherwise searches different extensions and can prefer a sibling such as .bin.exe over the selected .bin. The originally requested executable spelling remains argv[0]. The launcher preserves UTF-16 arguments with CRT quoting, duplicates the shim's standard handles for inheritance, and uses the same restored environment, job lifetime, and error reporting.

Selected .cmd and .bat files are rejected with Windows error 87 before launch, including Node's case-insensitive extension handling with trailing dots and whitespace. Win32 can otherwise dispatch batch files through a command interpreter whose argument rules differ from CRT quoting. The check follows image selection, preserving missing-file errors and .com/.exe sibling selection. The proof uses harmless echo metacharacters to check that batch contents and argument commands never execute.

Explicit paths and names searched through PATH try the given name first when it has an extension, followed by .com and .exe, matching Node's lookup. Candidate checks inspect Windows entry attributes without following file symlinks and skip directories, including directory symlinks. A dangling first file candidate therefore reports its launch failure instead of selecting a later image. The Windows proof compares image selection and argv[0] with ordinary Node spawning, including PATH-only .com files, extension collisions, quoted PATH entries, symlink candidates, and names with a trailing dot, while preserving the caller's working directory.

Build on Windows after compiling the TypeScript tools, then run:

node plugins/codex-security/native/build.mjs
node plugins/codex-security/native/check.mjs
node --expose-gc plugins/codex-security/native/proof-windows.mjs

The native-windows workflow builds x64 and arm64 with MSVC and a static CRT. It checks PE architecture and private paths, then runs the same artifact on Node 22.13.0 and 20.0.0 with an empty PATH. The proof covers handle lifetime and garbage collection, ancestor replacement, junctions, exact-handle operations, raw UTF-16 and long paths, and numeric errors.

The build also compiles the test-only windows-wide-launcher Rust example. It starts a Node proof child with lone surrogates in arguments, environment values, and its working directory. That child checks complete directory iteration, distinct surrogate and replacement-character files, canonical paths, bounded reads, output truncation, and recursive long paths through the typed adapter. A Rust file guard with sharing disabled remains open while the child enumerates its name; an explicit data read fails with a sharing violation. Attribute-only access is not blocked by Windows file sharing. Adapter path and I/O tests run on the same matrix. Scope binding also reads raw requested-scope and contract paths, preserves ordered JSON and unrelated hash fields, truncates both outputs, and leaves documents unchanged when validation fails. The launcher cleans up the wide fixtures and is never included in the uploaded or bundled native payloads.

Creating file and directory symbolic links requires Windows Developer Mode or the symbolic-link privilege. Without it, the proofs still run their other assertions, including directory junctions, and report the skipped symbolic-link assertions as false in their JSON output. CI requires real symbolic links on both architectures and also forces the restricted case to exercise both paths.