Nebular npm wrapper candidate

Local candidate version is maintained by apps/studio/package.json and projected into wrapper package.json (currently 0.6.1). No publication is authorized or claimed.

The wrapper selects exactly one optional platform package: darwin-arm64, linux-arm64, or linux-x64. Only the wrapper owns the npm tfnf bin, avoiding competing npm bin links from optional dependencies.

CLI and launch contracts

tfnf --version and --help report wrapper information and usage without requiring a native payload.

tfnf --path resolves and outputs the absolute canonical pathname of the native GUI executable on all supported platforms after authenticating the installed platform package and its manifest digest bound in payload-bindings.json.

Normal invocation launches the installed native GUI directly with any provided arguments. There is no first-run download, checkout fallback, or foreign-architecture fallback. Unsupported platforms fail closed. On Linux hosts, GNU/glibc runtime is required; musl and unsupported libc environments fail closed.

Payload verification and inventory bounds

Platform manifests bind fixed target paths, the complete payload inventory, regular-file sizes, SHA-256 hashes, file/directory modes, and exact internal symlink targets. The verifier enforces:

• Bounded manifest size (<= 4MB) and inventory member counts (<= 20,000 members).
• Expected complete status (payloadStatus: "complete") and platform payload type (app-bundle or linux-executable-resources).
• Platform identity match across package name, version, OS, and CPU architecture.
• Full path containment within package and payload roots, rejecting .., ., empty segments, backslashes, null bytes, and traversal attempts.
• Internal relative symlink containment, rejecting absolute targets, escaping symlinks, and link target mismatches.
• Mode enforcement (0o755 for directories, 0o644 or 0o755 for regular files, executable bit for GUI binary) and per-file/aggregate size bounds (<= 512MB per file, <= 2GB aggregate).
• Rejection of absent bindings, changed manifests, changed files, unexpected members on disk, and missing executables.

This is candidate input authentication, not a published provenance or notarization receipt.

Launch revalidation and TOCTOU guarantee

The launcher performs full payload verification immediately before invoking child_process.spawn.

Truthful TOCTOU boundary: Node.js launches child processes by filesystem pathname (child_process.spawn) rather than executing an open file descriptor (fexecve is not used). Consequently, same-user concurrent pathname mutation, symlink substitution, or file alteration after verification falls outside this guarantee. No descriptor-level or race-free kernel guarantees are claimed against concurrent processes operating with the same user privileges.

Environment sanitization and process lifecycle

Before spawn, the launcher sanitizes dynamic linker and Node execution injection environment variables (NODE_OPTIONS, NODE_PATH, LD_PRELOAD, LD_LIBRARY_PATH, LD_AUDIT, DYLD_INSERT_LIBRARIES, DYLD_LIBRARY_PATH, DYLD_FALLBACK_LIBRARY_PATH, DYLD_FRAMEWORK_PATH, DYLD_FALLBACK_FRAMEWORK_PATH), while preserving desktop environment variables (DISPLAY, WAYLAND_DISPLAY, XDG_*, DBUS_SESSION_BUS_ADDRESS, HOME, PATH, etc.).

Process lifecycle management:

• Child process exit code or terminating signal is propagated to the wrapper exit.
• SIGTERM and SIGINT signals are forwarded to the child process.
• A fixed 5000ms termination timer escalates to SIGKILL if the child does not terminate in response to SIGTERM.

Assembly and qualification boundary

The checked-in platform manifests are marked pending-native-build and the wrapper bindings are empty. These sources are not complete GUI packages. The wrapper does not fabricate or mark unbuilt payloads complete; parent workflows own assembly. tools/qualify-nebular-npm-package.mjs requires explicitly selected prepared platform packages with external expected manifest digests and a fresh output directory. It packs candidates and tests offline installation and selection; GUI workflows remain separate evidence. It never discovers an old checkout app.