tesseract-agent 0.10.7 → 0.10.9

package/dist-bundle/mesh-core/index.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The mesh overlay data plane (Rust, via napi-rs).
+ *
+ * Everything here is CONTROL plane. Packets do not cross this boundary on desktop:
+ * the daemon runs the engine in `tun_mode: "internal"` so Rust owns the device
+ * directly — a per-packet call into JS would melt Electron's event loop.
+ */
+
+/** `"host:port"`. */
+export type Endpoint = string;
+
+export interface SendItem {
+  /** Where to send it. */
+  to: Endpoint;
+  bytes: Buffer;
+}
+
+export interface MeshEvent {
+  kind: 'peerEstablished' | 'pathChanged' | 'dropped' | 'handshakeFailed';
+  /** Present for peer-scoped events. */
+  staticPub?: Buffer;
+  /**
+   * For `dropped`: why. `source-not-allowed` means cryptokey routing refused the
+   * peer's source address (a spoofing attempt), which is a very different thing
+   * from `policy-denied` — do not merge them in telemetry.
+   * For `pathChanged`: `'direct'` or `'relay'`.
+   */
+  detail?: string;
+}
+
+export declare class MeshEngine {
+  constructor(
+    genesis: Buffer,
+    staticPrivate: Buffer,
+    cert: Buffer,
+    overlayV4: number,
+    overlayV6: Buffer,
+  );
+
+  /**
+   * Install a policy bundle.
+   *
+   * MUST already be verified (quorum, mesh binding, rollback, staleness). Handing
+   * this an unverified bundle puts the coordination relay back into the trust path.
+   */
+  setBundle(bundle: Buffer): void;
+
+  addPeer(staticPub: Buffer, overlayV4: number, overlayV6: Buffer): void;
+  /** A relayed path always ranks below a direct one, regardless of RTT. */
+  addPath(staticPub: Buffer, endpoint: Endpoint, relayed: boolean): void;
+  startHandshake(staticPub: Buffer, nowMs: number): void;
+
+  injectTun(pkt: Buffer, nowMs: number): void;
+  injectUdp(pkt: Buffer, from: Endpoint, nowMs: number): void;
+  tick(nowMs: number): void;
+
+  pollSend(): SendItem | null;
+  pollTun(): Buffer | null;
+  pollEvent(): MeshEvent | null;
+
+  peerCount(): number;
+
+  /**
+   * Route all non-mesh traffic through this peer; `null` restores a split tunnel.
+   *
+   * SELECTION IS NOT AUTHORIZATION. It is one of three gates the engine checks per
+   * packet — the others are the CA marking the peer's certificate `isExitNode` and a
+   * `CAP_EXIT_NODE` grant in the signed bundle — so calling this before the peer's
+   * certificate arrives widens nothing.
+   *
+   * Declared late: the napi binding has had this since it was written
+   * (`crates/tsmesh-napi/src/lib.rs:293`), but it was missing from this file, so no
+   * TypeScript caller could reach it and a full tunnel was unreachable from the
+   * product even though the engine implemented it.
+   */
+  setExitNode(staticPub: Buffer | null): void;
+}
+
+/** True only when the prebuilt loaded AND its ABI matches. Check before use. */
+export declare const available: boolean;
+/** Why it did not load, for diagnostics. */
+export declare const loadError: string | null;
+export declare function abiVersion(): number | null;

package/dist-bundle/mesh-core/index.js

@@ -0,0 +1,85 @@
+'use strict';
+// Loader for the mesh data plane (Rust, napi-rs). Mirrors packages/mac-ax: return
+// inert stubs when the prebuilt binary is absent so host-core can require this
+// unconditionally and dev/build/typecheck stay green on any platform. Callers check
+// `available` first.
+//
+// Deliberately NOT bundled by esbuild: add '@fineguide-tesseract/mesh-core' to the
+// externals in apps/tesseract-cli/esbuild.mjs, and to asarUnpack in both
+// electron-builder.yml files, exactly as the other native packages are.
+//
+// The prebuilt is FETCHED, not committed. Nine build targets at ~6-12 MB each, every
+// release, would permanently bloat the repo — the same reason Chromium and
+// Real-ESRGAN are fetched (apps/desktop/scripts/fetch-7zz.mjs is the pattern).
+
+const path = require('node:path');
+
+/** ABI the JS side expects. Must match ABI_VERSION in crates/tsmesh-napi. */
+const EXPECTED_ABI = 8;
+
+function platformDir() {
+  const arch = process.arch;
+  switch (process.platform) {
+    case 'darwin': return [`darwin-${arch}`, 'darwin-universal'];
+    case 'win32': return [`win32-${arch}`];
+    case 'linux': return [`linux-${arch}`];
+    default: return [];
+  }
+}
+
+let native = null;
+let loadError = null;
+
+for (const dir of platformDir()) {
+  try {
+    native = require(path.join(__dirname, 'prebuilds', dir, 'tsmesh.node'));
+    break;
+  } catch (e) {
+    loadError = e;
+  }
+}
+// Developer build (`npm run rebuild -w packages/mesh-core`) lands here.
+if (!native) {
+  try {
+    native = require(path.join(__dirname, 'build', 'tsmesh.node'));
+  } catch (e) {
+    loadError = loadError || e;
+  }
+}
+
+// A prebuilt from a different release can be present but incompatible. Refusing it
+// here turns a confusing runtime failure deep in the data path into one clear
+// disabled-feature check at load — the same discipline the Dart side needs against
+// an over-the-air patch running on an older native.
+let abiOk = false;
+if (native) {
+  try {
+    abiOk = native.abiVersion() === EXPECTED_ABI;
+    if (!abiOk) {
+      loadError = new Error(
+        `mesh-core ABI mismatch: native ${native.abiVersion()}, expected ${EXPECTED_ABI}`,
+      );
+      native = null;
+    }
+  } catch (e) {
+    loadError = e;
+    native = null;
+  }
+}
+
+const unavailable = () => {
+  throw new Error(
+    `mesh-core native addon not available${loadError ? `: ${loadError.message}` : ''}`,
+  );
+};
+
+module.exports = {
+  /** True only when the prebuilt loaded AND its ABI matches. Check before use. */
+  available: !!native,
+  /** Why it did not load, for diagnostics and the support bundle. */
+  loadError: native ? null : loadError && loadError.message,
+  /** Native ABI version, or null when unavailable. */
+  abiVersion: native ? native.abiVersion : () => null,
+  /** The engine. Construct with (genesis, staticPrivate, cert, overlayV4, overlayV6). */
+  MeshEngine: native ? native.MeshEngine : unavailable,
+};

package/dist-bundle/mesh-core/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "@fineguide-tesseract/mesh-core",
+  "version": "0.10.9",
+  "main": "index.js",
+  "types": "index.d.ts"
+}

package/dist-bundle/mesh-core/scripts/fetch-prebuilt.mjs

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+/**
+ * Materialise the mesh native payload for THIS platform from a GitHub release.
+ *
+ * TWO artifacts, not one: the data-plane engine (`tsmesh.node`) and the privileged
+ * helper (`tesseract-netd`). The engine decides what a packet may do; the helper opens
+ * the tun device and programs the routes. Without the second, a machine joins a network,
+ * holds a certificate, shows a roster — and carries no packets, which is exactly what a
+ * `npm i -g tesseract-agent` install did.
+ *
+ * The binary is not committed: nine build targets at ~6-12 MB each, every release,
+ * would permanently bloat a repo with no git-lfs — the same reasoning that makes 7-Zip,
+ * the on-device models and Chromium fetched rather than vendored
+ * (`apps/desktop/scripts/fetch-7zz.mjs` is the pattern this follows).
+ *
+ * ## Why a missing prebuilt is not an error
+ *
+ * `packages/mesh-core/index.js` returns inert stubs when no binary is present, so the
+ * overlay simply reports itself unavailable and nothing else breaks. This script honours
+ * that: it exits 0 when it cannot fetch, unless `--require` is passed. A release job
+ * uses `--require`; a developer's `npm ci` must not fail because a network blipped on an
+ * optional feature.
+ *
+ * ## Integrity
+ *
+ * Every download is checked against the `.sha256` published beside it. That file comes
+ * from the same release, so this is a consistency check against corruption and a
+ * truncated transfer — NOT a defence against a compromised release. The binary is
+ * loaded into the daemon, so treat the release as trusted infrastructure and rely on
+ * repository access control for that, exactly as the other fetched binaries do.
+ */
+import { chmodSync, createWriteStream, existsSync, mkdirSync, readFileSync, rmSync, statSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { pipeline } from 'node:stream/promises';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const pkg = join(here, '..');
+const REQUIRE = process.argv.includes('--require');
+const REPO = process.env.TESSERACT_MESH_REPO || 'opentech-dev/tesseract-release';
+const VERSION = process.env.TESSERACT_MESH_VERSION
+  || JSON.parse(readFileSync(join(pkg, 'package.json'), 'utf8')).version;
+
+/** Must match `platformDir()` in index.js — the loader looks only where this writes. */
+function platformDir() {
+  const { platform, arch } = process;
+  if (platform === 'darwin') return `darwin-${arch}`;
+  if (platform === 'win32') return `win32-${arch}`;
+  if (platform === 'linux') return `linux-${arch}`;
+  return null;
+}
+
+function done(msg) {
+  console.log(`[mesh-core] ${msg}`);
+  process.exit(0);
+}
+
+function fail(msg) {
+  console.error(`[mesh-core] ${msg}`);
+  // Exit 0 unless the caller demanded the binary: an optional feature must never be
+  // the reason an install fails.
+  process.exit(REQUIRE ? 1 : 0);
+}
+
+async function fetchTo(url, dest) {
+  const res = await fetch(url, { redirect: 'follow' });
+  if (!res.ok) throw new Error(`${res.status} ${res.statusText} for ${url}`);
+  mkdirSync(dirname(dest), { recursive: true });
+  await pipeline(res.body, createWriteStream(dest));
+}
+
+function sha256(p) {
+  return createHash('sha256').update(readFileSync(p)).digest('hex');
+}
+
+const dir = platformDir();
+if (!dir) done(`no prebuilt for ${process.platform}-${process.arch}; the overlay will report unavailable`);
+
+const outDir = join(pkg, 'prebuilds', dir);
+const out = join(outDir, 'tsmesh.node');
+
+// Idempotent: a binary already present and non-empty is left alone, so repeated
+// installs and offline rebuilds cost nothing.
+if (existsSync(out) && statSync(out).size > 0) done(`already present for ${dir}`);
+
+const tag = `mesh-core-v${VERSION}`;
+const base = `https://github.com/${REPO}/releases/download/${tag}`;
+
+/**
+ * Fetch one asset and check it against the `.sha256` published beside it.
+ *
+ * Throws. The caller decides whether a given asset is worth failing the install for,
+ * and the two are not the same: the engine and the helper fail independently, because a
+ * machine with an engine and no helper is still useful (it can enrol, hold a
+ * certificate and show a roster) while one with neither is not.
+ */
+async function fetchChecked(asset, dest) {
+  await fetchTo(`${base}/${asset}`, dest);
+  let expected = null;
+  try {
+    const sumPath = `${dest}.sha256`;
+    await fetchTo(`${base}/${asset}.sha256`, sumPath);
+    expected = readFileSync(sumPath, 'utf8').trim().split(/\s+/)[0];
+    rmSync(sumPath, { force: true });
+  } catch {
+    // A release without a checksum is older than this script. Refuse it under
+    // --require rather than install an unverified binary into a daemon.
+    if (REQUIRE) throw new Error('no .sha256 published beside the asset');
+  }
+  if (expected) {
+    const got = sha256(dest);
+    if (got !== expected) {
+      rmSync(dest, { force: true });
+      throw new Error(`checksum mismatch: expected ${expected}, got ${got}`);
+    }
+  }
+  return `${asset} (${statSync(dest).size} bytes)${expected ? ', checksum ok' : ''}`;
+}
+
+const engineAsset = `tsmesh-${dir}.node`;
+try {
+  console.log(`[mesh-core] fetched ${await fetchChecked(engineAsset, out)}`);
+} catch (e) {
+  rmSync(out, { force: true });
+  fail(`could not fetch ${engineAsset} from ${tag}: ${e.message}`);
+}
+
+// ── The privileged helper ────────────────────────────────────────────────────────────
+//
+// Lands in `prebuilds/<dir>/netd/`, which is where `netdBinaryPath()` looks — the same
+// layout the desktop packages use, so one resolver serves both. Named for what it is on
+// the machine it lands on (`tesseract-netd`), not for the crate.
+//
+// Its absence is NEVER fatal, not even under --require: a release older than this
+// script has no netd asset for this platform, and failing there would break installs of
+// the engine, which does work. The helper is installed by an explicit elevation the user
+// accepts, and `ensureNetHelperInstalled` already says "this build did not ship the
+// network helper" when it is not here.
+const netdName = process.platform === 'win32' ? 'tesseract-netd.exe' : 'tesseract-netd';
+const netdOut = join(outDir, 'netd', netdName);
+const netdAsset = `tesseract-netd-${dir}${process.platform === 'win32' ? '.exe' : ''}`;
+if (existsSync(netdOut) && statSync(netdOut).size > 0) {
+  console.log(`[mesh-core] network helper already present for ${dir}`);
+} else {
+  try {
+    const what = await fetchChecked(netdAsset, netdOut);
+    // Executable, because the installer hands this exact path to systemd / launchd / the
+    // Windows SCM. A 0644 file there produces a service that fails to start with a
+    // permission error naming the binary, which reads as a corrupt download.
+    if (process.platform !== 'win32') chmodSync(netdOut, 0o755);
+    console.log(`[mesh-core] fetched ${what}`);
+    // WINTUN, and only on Windows. `tun-rs` does not link it — it LoadLibrary's `wintun.dll`
+    // from the helper's OWN directory at runtime — so a netd.exe without it fails with
+    // `open tun: LoadLibraryExW failed` and the machine carries no packets. It is fetched
+    // here rather than by a separate step because the two are one artifact in practice: a
+    // helper without its driver library is not a helper.
+    if (process.platform === 'win32') {
+      const dll = join(outDir, 'netd', 'wintun.dll');
+      console.log(`[mesh-core] fetched ${await fetchChecked(`wintun-${dir}.dll`, dll)}`);
+    }
+  } catch (e) {
+    rmSync(netdOut, { force: true });
+    // Remove the DLL too. Half a helper on disk is worse than none: `netdBinaryPath()` would
+    // find the exe and the installer would register a service that cannot open a device.
+    rmSync(join(outDir, 'netd', 'wintun.dll'), { force: true });
+    console.log(`[mesh-core] no network helper for ${dir} in ${tag} (${e.message}); routing will be unavailable`);
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tesseract-agent",
-  "version": "0.10.7",
+  "version": "0.10.9",
   "license": "UNLICENSED",
   "publishConfig": {
     "access": "public",
@@ -30,7 +30,7 @@
     "bundle": "node esbuild.mjs",
     "dev": "tsc --watch",
     "prepublishOnly": "npm run build",
-    "postinstall": "node -e \"process.env.PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD||process.env.CI_SKIP_PLAYWRIGHT?process.exit(0):process.exit(1)\" || playwright-core install chromium-headless-shell"
+    "postinstall": "node dist-bundle/mesh-core/scripts/fetch-prebuilt.mjs || echo \"[tesseract] mesh natives unavailable; the overlay will report itself disabled\" && node -e \"process.env.PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD||process.env.CI_SKIP_PLAYWRIGHT?process.exit(0):process.exit(1)\" || playwright-core install chromium-headless-shell"
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "0.3.257",