Frames cross processes as mach send-rights; delete the global-IOSurface patch (#16)

kIOSurfaceIsGlobal (patch 0002) made every headless render target
world-readable: any local process that guessed a uint32 surface ID
could read live terminal pixels. Replace it with Apple's sanctioned
mechanism for passing a surface between tasks (IOSurfaceRef.h:
"atomically or securely"): IOSurfaceCreateMachPort in the host,
IOSurfaceLookupFromMachPort in the parent — an unguessable capability.

Electron's parentPort can't carry mach send-rights, so the addon grows
a small channel (~180 lines):

  machChannelCreate(name)   parent: receive port, bootstrap_register
  machSenderOpen(name)      host: bootstrap_look_up (name via env)
  machSendSurface(s, h, n)  host: wrap surface, MOVE_SEND + inline seq
  machChannelReceiveSurface parent: bounded mach_msg receive -> +1 ref

Sequencing keeps it thread-free: the host sends the mach message
BEFORE the 'frame' JS message, and flow control is one-frame-in-flight,
so when the parent handles the JS message exactly one mach message is
already queued — the receive is immediate, no dedicated receive thread.
A live port holds +1 on the surface's global use count, so an in-flight
frame can't be recycled even across a resize; both sides deallocate
rights promptly (send-timeout failure path included, so a dead parent
doesn't leak use counts in the host).

patches/0002 is reverted from the vendor checkout and deleted — the
fork shrinks back to patch 0001 (headless platform) alone, which also
cleans up the upstream story. surfaceLookup/surfaceId are gone from
the addon surface; docs updated (security caveat removed, mechanism
documented in both READMEs).

Verified: all 7 utility-engine protocol scenarios, 7 e2e, 6 integration
tests pass over the mach-port path.

Author: mxschmitt

README.md

@@ -145,26 +145,27 @@ embedding is the main open workstream.
                                                    └───────────────────┘
 ```
 
-Two small patches to a pinned ghostty checkout make this possible
-(`patches/`, applied by `npm run setup:ghostty`):
-
-1. **`0001` — headless apprt platform.** `GHOSTTY_PLATFORM_HEADLESS`
-   (a surface with no NSView; the Metal backend's IOSurfaceLayer works
-   standalone) plus `ghostty_surface_headless_frame()` returning the
-   last presented IOSurface. This is the piece worth proposing
-   upstream — small, additive, independently useful for screenshots,
-   testing, and embedding.
-2. **`0002` — global IOSurfaces for headless targets.** Frames must be
-   representable cross-process; `kIOSurfaceIsGlobal` makes a frame a
-   lookup-able `uint32`. ⚠️ Deprecated by Apple and **insecure** (any
-   local process that guesses an ID can read the terminal's pixels) —
-   acceptable for research, not for shipping. The production path is a
-   mach-port handoff (`IOSurfaceCreateMachPort`), which needs a small
-   native channel since Electron's `parentPort` can't carry mach
-   send-rights.
-
-The N-API addon (`packages/electron-ghostty/src/addon.c`, ~700 lines)
-is pure marshalling around `ghostty.h` — ghostty does the work.
+One small patch to a pinned ghostty checkout makes this possible
+(`patches/0001`, applied by `npm run setup:ghostty`): the headless
+apprt platform — `GHOSTTY_PLATFORM_HEADLESS` (a surface with no
+NSView; the Metal backend's IOSurfaceLayer works standalone) plus
+`ghostty_surface_headless_frame()` returning the last presented
+IOSurface. This is the piece worth proposing upstream — small,
+additive, independently useful for screenshots, testing, and
+embedding.
+
+Frames cross the engine→main process boundary as **mach send-rights**
+(`IOSurfaceCreateMachPort` in the host, a bootstrap-registered channel
+— Electron's `parentPort` can't carry mach rights —
+`IOSurfaceLookupFromMachPort` in the parent). That's Apple's
+recommended mechanism for passing a surface "atomically or securely to
+another task": an unguessable capability, no fork patch needed. Each
+in-flight port holds +1 on the surface's global use count, so a frame
+can't be recycled mid-transfer.
+
+The N-API addon (`packages/electron-ghostty/src/addon.c`, ~900 lines)
+is marshalling around `ghostty.h` plus that mach channel — ghostty
+does the work.
 
 ## Platform matrix (honest)
 
@@ -228,8 +229,6 @@ native/renderer-poc/        Linux EGL/headless probe experiments
 ## Caveats
 
 - Research-grade. The package is not published and its API will change.
-- Patch `0002`'s global IOSurfaces mean terminal pixels are readable by
-  any local process — do not ship this as-is (see above).
 - ghostty is pinned (`scripts/setup-ghostty.sh`); the embedding pokes
   one private detail (the IOSurfaceLayer `contents` property) that an
   upstream API should replace.

packages/electron-ghostty/README.md

@@ -18,12 +18,14 @@ loop, forward input, ship each presented frame.
 By default the engine doesn't even run in the Electron main process:
 `host.js` runs the whole terminal in an Electron **utilityProcess**, so
 a busy or crashed terminal can't stall window management. Frames cross
-the process boundary as global IOSurface IDs (a `uint32` over
-`parentPort`); the main process re-derives a local `IOSurfaceRef` via
-`IOSurfaceLookup` and imports it into `sharedTexture` — still zero-copy,
-the pixels never leave the GPU. Set `engine: 'main'` to run the engine
-in-process (the original mode; tests use it for synchronous pixel
-assertions).
+the process boundary as **mach send-rights**
+(`IOSurfaceCreateMachPort` → bootstrap channel →
+`IOSurfaceLookupFromMachPort`) — an unguessable capability, per
+Apple's recommended mechanism for passing surfaces between tasks; the
+main process imports each received surface into `sharedTexture` —
+still zero-copy, the pixels never leave the GPU. Set `engine: 'main'`
+to run the engine in-process (the original mode; tests use it for
+synchronous pixel assertions).
 
 macOS-only for now (Metal + IOSurface). Linux needs an EGL/GBM
 presenter (probe experiments in `native/renderer-poc/`); Windows has
@@ -32,11 +34,6 @@ iteration had a working D3D11/DirectWrite producer, last at repo
 commit `1a4357c`. See `docs/ghostty-renderer-reuse.md` at the repo
 root.
 
-⚠️ **Security caveat:** frames cross the engine→main process boundary
-as *global* IOSurfaces (`kIOSurfaceIsGlobal`, patch `0002`), meaning
-any local process that guesses a surface ID can read the terminal's
-pixels. Acceptable for research, not for shipping; the production path
-is an `IOSurfaceCreateMachPort` handoff.
 
 ## Usage
 

packages/electron-ghostty/host.js

@@ -5,21 +5,32 @@
  * Runs the entire terminal engine (ghostty: PTY + shell, VT parsing,
  * input encoding, fonts, Metal rendering) OUTSIDE the Electron main
  * process, so a busy or crashing terminal can't stall window
- * management. The main process stays a thin presenter: we post the
- * global IOSurfaceID of each presented frame over parentPort; the main
- * side re-derives a local IOSurfaceRef via IOSurfaceLookup and imports
- * it into sharedTexture — still zero-copy, frames never leave the GPU.
+ * management. The main process stays a thin presenter: it receives
+ * each presented frame as a mach send-right and imports it into
+ * sharedTexture — still zero-copy, frames never leave the GPU.
+ *
+ * Frame handoff: per frame, the IOSurface crosses the process
+ * boundary as a mach send-right (IOSurfaceCreateMachPort) over a
+ * bootstrap-registered channel — an unguessable capability, unlike
+ * the deprecated global-IOSurface IDs. The mach message is sent
+ * FIRST, then a 'frame' JS message with the metadata; the parent
+ * receives the (already queued) port on handling the JS message.
  *
  * Frame flow control: one frame in flight — we don't post the next
  * frame until the parent acks the previous one, so a slow presenter
  * degrades to skipped frames instead of a queue of stale messages.
+ * The in-flight frame's port holds +1 on the surface's global use
+ * count, so it can't be recycled mid-transfer.
  *
  * Protocol (parentPort messages, all {type, ...}):
  *   in : create {opts} | frame-ack | key/text/mouse-* {..} |
  *        resize {widthPx,heightPx} | draw | read-pixels {id} |
  *        size {id} | destroy
- *   out: created | frame {surfaceId,width,height,scale} | exit |
+ *   out: created | frame {seq,width,height,scale} | exit |
  *        reply {id, result} | error {message}
+ *
+ * The mach channel name arrives in ELECTRON_GHOSTTY_MACH_CHANNEL
+ * (set by the parent before fork).
  */
 const { load } = require('./addon');
 
@@ -28,11 +39,15 @@ const PRESENT_INTERVAL_MS = 8; // ~120Hz poll of ghostty's swap chain
 const addon = load();
 addon.init();
 
+const sender = addon.machSenderOpen(
+  process.env.ELECTRON_GHOSTTY_MACH_CHANNEL, 5000);
+
 let session = null;
 let presentTimer = null;
 let lastFramePtr = null;
 let awaitingAck = false;
 let exited = false;
+let frameSeq = 0;
 
 function post(msg) {
   process.parentPort.postMessage(msg);
@@ -57,10 +72,15 @@ function presentTick() {
   const ptr = frame.handle.toString('hex');
   if (ptr === lastFramePtr) return;
   lastFramePtr = ptr;
+  // Mach message first (the port right travels out-of-band), then the
+  // JS metadata message. If the mach send fails (parent gone, queue
+  // full) skip this frame — the swap chain will produce another.
+  const seq = ++frameSeq;
+  if (!addon.machSendSurface(sender, frame.handle, seq)) return;
   awaitingAck = true;
   post({
     type: 'frame',
-    surfaceId: frame.surfaceId,
+    seq,
     width: frame.width,
     height: frame.height,
     scale: frame.scale,

packages/electron-ghostty/index.js

@@ -21,11 +21,11 @@
  *
  * Engine placement — opts.engine:
  *   'utility' (default)  the whole engine runs in an Electron
- *       utilityProcess (host.js); the main process only re-derives
- *       each presented frame from its global IOSurfaceID
- *       (IOSurfaceLookup) and imports it into sharedTexture. A busy
- *       or crashed terminal can't stall window management, and the
- *       path stays zero-copy — frames never leave the GPU.
+ *       utilityProcess (host.js); each presented frame arrives in the
+ *       main process as a mach send-right (IOSurfaceCreateMachPort)
+ *       and is imported into sharedTexture. A busy or crashed
+ *       terminal can't stall window management, and the path stays
+ *       zero-copy — frames never leave the GPU.
  *   'main'  the engine runs in this process (the original mode; also
  *       what tests use to assert on pixels synchronously).
  */
@@ -134,25 +134,35 @@ class LocalEngine {
   }
 }
 
+let machChannelSeq = 0;
+
 /**
- * Engine in an Electron utilityProcess (host.js). Frames arrive as
- * global IOSurfaceIDs; we re-derive a local IOSurfaceRef via
- * IOSurfaceLookup (addon, no ghostty init needed) and present it.
- * State queries (size/readPixels) become async — the sync accessors
- * serve the last known size, tests use the async variants.
+ * Engine in an Electron utilityProcess (host.js). Frames cross the
+ * process boundary as mach send-rights (IOSurfaceCreateMachPort over
+ * a bootstrap channel — Electron's parentPort can't carry mach
+ * rights); each 'frame' JS message means exactly one mach message is
+ * already queued, so the receive here is immediate. State queries
+ * (size/readPixels) become async — the sync accessors serve the last
+ * known size, tests use the async variants.
  */
 class UtilityEngine {
   constructor(term, opts) {
     this._term = term;
-    this._addon = load(); // only for surfaceLookup/surfaceRelease
+    this._addon = load(); // mach channel + surfaceRelease
     this._exited = false;
     this._lastSize = null;
     this._replies = new Map(); // id -> resolve
     this._replySeq = 0;
+    const channelName =
+      `electron-ghostty.${process.pid}.${++machChannelSeq}`;
+    this._machChannel = this._addon.machChannelCreate(channelName);
     this._child = utilityProcess.fork(
       path.join(__dirname, 'host.js'),
       [],
-      { serviceName: 'electron-ghostty engine' },
+      {
+        serviceName: 'electron-ghostty engine',
+        env: { ...process.env, ELECTRON_GHOSTTY_MACH_CHANNEL: channelName },
+      },
     );
     this._child.on('message', (msg) => this._onMessage(msg));
     this._child.on('exit', () => {
@@ -177,16 +187,23 @@ class UtilityEngine {
   _onMessage(msg) {
     switch (msg.type) {
       case 'frame': {
-        const surf = this._addon.surfaceLookup(msg.surfaceId);
-        if (surf) {
+        // One-frame-in-flight: this JS message means exactly one mach
+        // message is queued on our channel. Drain any stale frames
+        // (shouldn't happen; belt-and-suspenders) and keep the newest.
+        let recv = this._addon.machChannelReceiveSurface(this._machChannel, 250);
+        while (recv && recv.seq < msg.seq) {
+          this._addon.surfaceRelease(recv.handle);
+          recv = this._addon.machChannelReceiveSurface(this._machChannel, 250);
+        }
+        if (recv) {
+          const surf = recv.handle;
           const ok = this._term._presentFrame(
             { ioSurface: surf }, msg.width, msg.height);
           const release = () => this._addon.surfaceRelease(surf);
           if (ok && typeof ok.then === 'function') ok.then(release, release);
           else release();
         }
-        // Ack regardless — a failed lookup (surface already recycled,
-        // e.g. right after a resize) must not wedge the frame flow.
+        // Ack regardless — a missed receive must not wedge the flow.
         this._child.postMessage({ type: 'frame-ack' });
         break;
       }