@reticlehq/electron 2.6.0 → 2.8.0

package/README.md

@@ -6,6 +6,10 @@ Everything else Reticle does inside an Electron app is the ordinary browser SDK
 
 Both are **dev-only**. Gate each `require` behind your own dev check so neither ships.
 
+```bash
+npm i -D @reticlehq/electron
+```
+
 ## IPC observation — one line at the top of your preload
 
 ```js

package/main.cjs

@@ -17,7 +17,7 @@
  * Dev-only, like the rest of Reticle. Gate the require behind your dev check so it never ships.
  */
 const { ipcMain } = require('electron');
-const { writeFile, readdir, stat, unlink } = require('node:fs/promises');
+const { writeFile, readdir, stat, unlink, mkdtemp } = require('node:fs/promises');
 const { tmpdir } = require('node:os');
 const { join } = require('node:path');
 // Generated from @reticlehq/core's TypeScript source, so the main process, the preload and the
@@ -26,6 +26,7 @@ const {
   RETICLE_CAPTURE_CHANNEL,
   RETICLE_CAPTURE_FILE_PREFIX,
   RETICLE_FULL_PAGE_UNSUPPORTED,
+  RETICLE_NOT_COMPOSITED,
 } = require('@reticlehq/core/desktop-contract');
 
 let captureSeq = 0;
@@ -57,8 +58,9 @@ function usableContents(sender) {
  *
  * The daemon unlinks a capture after reading it, but only if it ever reads: a session that died, a
  * command that timed out, or a path the daemon rejected all leave a ~300KB PNG in the temp directory
- * forever. Sweeping our own prefix on each capture bounds that to one file at a time, with no timer
- * to leak and no cleanup handler to forget. Best-effort — a failed sweep must never fail a capture.
+ * forever. Sweeping our own prefix on each capture bounds that to one file at a time, and the daemon
+ * removes this empty private directory in its existing shutdown path. Best-effort — a failed sweep
+ * must never fail a capture.
  *
  * Only files older than STALE_CAPTURE_MS are swept. Deleting every sibling unconditionally raced
  * with CONCURRENT captures: with two screenshots in flight, the second one's sweep unlinked the
@@ -67,14 +69,37 @@ function usableContents(sender) {
  */
 const STALE_CAPTURE_MS = 60_000;
 
+/**
+ * This process's own capture directory, created 0700 — made once, on the first capture.
+ *
+ * A screenshot of your app window can hold customer records, a token on screen, an authenticated
+ * session. Written straight into the SHARED temp dir under a guessable name — a constant prefix, a
+ * readable pid and a counter from 0 — it is readable by any other local user for as long as it
+ * sits there, and a symlink pre-placed at that name would have `writeFile` follow it and write
+ * through with this app's privileges.
+ *
+ * `mkdtemp` closes both at once, and it is the DIRECTORY that does it rather than a less guessable
+ * filename: the OS creates it 0700 with a random suffix, so another user cannot enter it to read a
+ * capture, and cannot pre-create anything inside a directory that did not exist until this process
+ * made it. Guessing is not the property that matters; the shared parent was.
+ *
+ * Memoised as the PROMISE, not the resolved path, so two captures racing on the first screenshot
+ * await one `mkdtemp` instead of creating two directories and leaking one.
+ */
+let capturesDirPromise;
+
+function capturesDir() {
+  capturesDirPromise ??= mkdtemp(join(tmpdir(), RETICLE_CAPTURE_FILE_PREFIX));
+  return capturesDirPromise;
+}
+
 async function sweepOldCaptures(dir, keepFile) {
-  const mine = `${RETICLE_CAPTURE_FILE_PREFIX}${String(process.pid)}-`;
   const cutoff = Date.now() - STALE_CAPTURE_MS;
   try {
     const entries = await readdir(dir);
     await Promise.all(
       entries
-        .filter((name) => name.startsWith(mine) && join(dir, name) !== keepFile)
+        .filter((name) => join(dir, name) !== keepFile)
         .map(async (name) => {
           const file = join(dir, name);
           const info = await stat(file).catch(() => undefined);
@@ -83,7 +108,7 @@ async function sweepOldCaptures(dir, keepFile) {
         }),
     );
   } catch {
-    /* the temp dir is unreadable; a capture is still worth attempting */
+    /* the capture directory is unreadable; a capture is still worth attempting */
   }
 }
 
@@ -104,27 +129,43 @@ function installReticleCapture(win) {
       // Saying so beats handing back a viewport the caller thinks covers the whole scroll height.
       if (options && options.fullPage === true) throw new Error(RETICLE_FULL_PAGE_UNSUPPORTED);
       const contents = usableContents(event.sender);
-      if (contents === null) return null;
+      // Named, not null. Every no-image answer used to be the same bare null, so a dead window, an
+      // uncomposited one and a thrown error were one silence — the tool reported `saved:false` with
+      // no bytes and no reason, which is unreadable in CI and useless to a user.
+      if (contents === null) throw new Error('no usable webContents to capture');
       try {
         const image = await contents.capturePage();
-        // An empty image means the window had nothing to compose yet; report it as no-image rather
-        // than handing back a 0-byte PNG that a diff would treat as a real, blank baseline.
-        if (image.isEmpty()) return null;
+        // An empty image means the window had nothing to compose yet, which is a fact about TIMING
+        // rather than a failure of the capture path — under a headless compositor a window that has
+        // not painted returns empty rather than erroring. Still never a 0-byte PNG, which a diff
+        // would trust as a real blank baseline; it is now reported by name instead.
+        if (image.isEmpty()) throw new Error(RETICLE_NOT_COMPOSITED);
         // Write to a temp FILE and return its path, rather than base64 over the bridge. The SDK's
         // transport sanitizer caps every string at 64KB, so a real screenshot came back silently
         // truncated — an invalid PNG that still reported `saved: true`. The daemon and the app are
         // always on the same machine here (the bridge is loopback), so a path is the honest channel:
         // no size cap, no chunking, and nothing large on the event wire.
         captureSeq += 1;
-        const file = join(
-          tmpdir(),
-          `${RETICLE_CAPTURE_FILE_PREFIX}${String(process.pid)}-${String(captureSeq)}.png`,
-        );
-        await writeFile(file, image.toPNG());
-        await sweepOldCaptures(tmpdir(), file);
+        // Inside this process's own 0700 directory. A failure to create it throws to the catch
+        // below and answers no-image; it deliberately does NOT fall back to the shared temp dir,
+        // because that fallback is the very exposure this directory exists to remove.
+        const dir = await capturesDir();
+        const file = join(dir, `${RETICLE_CAPTURE_FILE_PREFIX}${String(captureSeq)}.png`);
+        // `wx` is O_CREAT|O_EXCL: it REFUSES an existing path instead of writing through it, and
+        // O_EXCL does not follow a final symlink. The 0700 directory already stops an attacker
+        // getting a symlink here, so this is the second lock on the same door — and the one that
+        // still holds if a later change moves this write back out into the shared temp dir. The
+        // sequence only ever climbs within a fresh per-process directory, so it never collides
+        // with a capture of our own.
+        await writeFile(file, image.toPNG(), { flag: 'wx' });
+        await sweepOldCaptures(dir, file);
         return file;
-      } catch {
-        return null;
+      } catch (error) {
+        // Rethrow rather than swallow. The renderer maps the reasons it recognises onto the closed
+        // VisualReason vocabulary and passes anything else through as its own message, so a real
+        // failure (EACCES on the capture file, a window closing mid-write) now reaches the caller
+        // saying what it was. Swallowing it here is what made all of these indistinguishable.
+        throw error instanceof Error ? error : new Error(String(error));
       }
     });
     registered = true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/electron",
-  "version": "2.6.0",
+  "version": "2.8.0",
   "description": "Reticle adapter for Electron: makes main-process IPC observable and the window screenshottable, from the two places the renderer cannot reach.",
   "type": "module",
   "exports": {
@@ -8,7 +8,7 @@
     "./main": "./main.cjs"
   },
   "dependencies": {
-    "@reticlehq/core": "2.6.0"
+    "@reticlehq/core": "2.8.0"
   },
   "peerDependencies": {
     "electron": ">=22"