ai-or-die 0.1.87 → 0.1.88

package/bin/ai-or-die.js

@@ -106,7 +106,12 @@ async function main() {
       port,
       auth: authToken,
       noAuth: noAuth,
-      https: options.https,
+      // Mesh terminates real TLS at the tailnet edge (the sidecar serves the
+      // <host>.ts.net cert) and reverse-proxies to a loopback backend, so in
+      // mesh mode the local server stays plain HTTP on 127.0.0.1 regardless of
+      // --https. (Mesh forces a loopback-only bind anyway, so --https's LAN
+      // secure-context role does not apply.) --https WITHOUT --mesh is unchanged.
+      https: options.mesh ? false : options.https,
       cert: options.cert,
       key: options.key,
       dev: options.dev,
@@ -158,7 +163,7 @@ async function main() {
     const app = new ClaudeCodeWebServer(serverOptions);
     await app.start();
 
-    const protocol = options.https ? 'https' : 'http';
+    const protocol = serverOptions.https ? 'https' : 'http';
     const baseUrl = `${protocol}://localhost:${port}`;
     // For localhost with auth, embed token in URL so user can just click it
     const url = authToken ? `${baseUrl}?token=${authToken}` : baseUrl;
@@ -168,8 +173,10 @@ async function main() {
       console.log(`   Auth token: \x1b[1m\x1b[33m${authToken}\x1b[0m`);
     }
 
-    // Warn if STT is enabled without HTTPS or tunnel
-    if ((serverOptions.stt || serverOptions.sttEndpoint) && !options.https && !options.tunnel) {
+    // Warn if STT is enabled without HTTPS or tunnel. Skip in mesh mode: it
+    // binds loopback-only (no LAN), the mic works on http://localhost locally,
+    // and remotely via the mesh edge's real TLS.
+    if ((serverOptions.stt || serverOptions.sttEndpoint) && !options.https && !options.tunnel && !options.mesh) {
       console.log('\n\x1b[33m⚠  STT enabled over plain HTTP \u2014 microphone only works on localhost.\x1b[0m');
       console.log('   For LAN access, restart with \x1b[1m--https\x1b[0m or \x1b[1m--tunnel\x1b[0m.');
     }
@@ -202,6 +209,9 @@ async function main() {
     // Mesh: permanent Tailscale reachability. Coexists with --tunnel (mesh for
     // owned devices, tunnel fallback for borrowed ones). Auth token stays ON.
     if (options.mesh) {
+      if (options.https) {
+        console.log('\n  \x1b[33mNote: --https is handled by the mesh edge (real .ts.net TLS); the local server stays HTTP on loopback.\x1b[0m');
+      }
       const { MeshManager } = require('../src/mesh-manager');
       const mesh = new MeshManager({
         port,

package/mesh/main.go

@@ -5,16 +5,28 @@
 // rest of the machine never joins. Enrollment is one-time via TS_AUTHKEY; the
 // node identity persists in --statedir so the key is never needed again.
 //
+// TLS: when the tailnet has HTTPS certificates enabled, the sidecar terminates
+// real `<host>.ts.net` TLS at the edge (so the advertised https:// URL is a
+// genuine browser secure context — remote mic/PWA work) and reverse-proxies to
+// the loopback backend. When certs are unavailable it degrades to plain http on
+// :80 and says so. The scheme is decided BEFORE the URL is advertised, never
+// after, because tsnet provisions the cert lazily inside the TLS handshake — a
+// post-advertise failure would otherwise hang the browser.
+//
 // stdout protocol (parsed by src/mesh-manager.js):
-//   MESH-URL https://<name>      node is up and serving
+//   MESH-URL https://<name>      node is up, serving real TLS at the edge
+//   MESH-URL http://<name>       node is up, but TLS certs unavailable (degraded)
+//   MESH-NOCERT                  hint: enable HTTPS Certificates in the tailnet
 //   MESH-NEEDLOGIN <url>         no/!valid key — operator must enroll
-//   MESH-ERR <msg>              fatal
+//   MESH-ERR <msg>               fatal
 package main
 
 import (
 	"context"
+	"crypto/tls"
 	"flag"
 	"fmt"
+	"net"
 	"net/http"
 	"net/http/httputil"
 	"net/url"
@@ -25,12 +37,33 @@ import (
 	"tailscale.com/tsnet"
 )
 
+// version is stamped at build time via -ldflags "-X main.version=<contentHash>".
+var version = "dev"
+
+const certWaitTimeout = 20 * time.Second
+
 func main() {
-	port := flag.String("port", "7777", "local ai-or-die port to expose")
+	port := flag.String("port", "7777", "local ai-or-die port to expose (loopback)")
+	backend := flag.String("backend", "", "full backend URL to proxy to (overrides --port); must be loopback")
 	host := flag.String("hostname", "aiordie", "tailnet hostname")
 	dir := flag.String("statedir", "./ts-state", "persistent node state dir")
+	showVersion := flag.Bool("version", false, "print the build version (content hash) and exit")
 	flag.Parse()
 
+	if *showVersion {
+		fmt.Println(version)
+		return
+	}
+
+	// Resolve + validate the backend target. It MUST be loopback: the sidecar is
+	// a tailnet-facing reverse proxy, and pointing it off-host would expose an
+	// arbitrary origin to the whole tailnet.
+	target, err := resolveBackend(*backend, *port)
+	if err != nil {
+		fmt.Printf("MESH-ERR %v\n", err)
+		os.Exit(1)
+	}
+
 	s := &tsnet.Server{Dir: *dir, Hostname: *host}
 	// Surface the login URL exactly once instead of tsnet's default stderr spam.
 	s.AuthKey = os.Getenv("TS_AUTHKEY")
@@ -39,27 +72,158 @@ func main() {
 	// Bring the node up; report the enroll URL if it needs login.
 	ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
 	defer cancel()
-	if _, err := s.Up(ctx); err != nil {
+	st, err := s.Up(ctx)
+	if err != nil {
 		// Up blocks until authed; on timeout it's almost always missing/!key.
 		fmt.Printf("MESH-NEEDLOGIN https://login.tailscale.com/admin/settings/keys\n")
 		fmt.Printf("MESH-ERR %v\n", err)
 		os.Exit(1)
 	}
 
+	name := *host
+	if st != nil && st.Self != nil && st.Self.DNSName != "" {
+		name = strings.TrimSuffix(st.Self.DNSName, ".")
+	}
+
+	// One reverse proxy; the edge scheme it advertises to the backend is decided
+	// just below and captured by pointer so the X-Forwarded-Proto header is
+	// always accurate. The terminal client derives ws/wss from window.location,
+	// so wss works regardless; this header is hygiene for any absolute-URL or
+	// redirect the app generates (no mixed content).
+	edgeProto := "http"
+	rp := newEdgeProxy(target, name, &edgeProto)
+
+	// Decide the scheme BEFORE advertising. tsnet's ListenTLS returns a listener
+	// without provisioning the cert; the ACME work (and any failure) happens
+	// lazily inside the first TLS handshake. So we probe cert readiness up front
+	// and only advertise https:// when we are confident the handshake will work.
+	if tlsLn := tryListenTLS(ctx, s, name); tlsLn != nil {
+		edgeProto = "https"
+		// Best-effort :80 -> https redirect so a bare http:// hit is upgraded.
+		if httpLn, e := s.Listen("tcp", ":80"); e == nil {
+			go http.Serve(httpLn, redirectToHTTPS(name))
+		}
+		fmt.Printf("MESH-URL https://%s\n", name)
+		// http.Serve only returns on failure; exit non-zero so the manager
+		// (which restarts on a non-zero exit) brings the sidecar back.
+		err := http.Serve(tlsLn, rp)
+		fmt.Printf("MESH-ERR %v\n", err)
+		os.Exit(1)
+	}
+
+	// Degraded: no usable cert. Serve plain http and say so. http://<name>.ts.net
+	// is NOT a browser secure context, so remote mic/PWA will not work until the
+	// operator enables HTTPS Certificates in the tailnet admin console.
 	ln, err := s.Listen("tcp", ":80")
 	if err != nil {
 		fmt.Printf("MESH-ERR %v\n", err)
 		os.Exit(1)
 	}
-	target, _ := url.Parse("http://127.0.0.1:" + *port)
-	rp := httputil.NewSingleHostReverseProxy(target) // handles WS upgrade via hijack
+	fmt.Printf("MESH-NOCERT\n")
+	fmt.Printf("MESH-URL http://%s\n", name)
+	serveErr := http.Serve(ln, rp)
+	fmt.Printf("MESH-ERR %v\n", serveErr)
+	os.Exit(1)
+}
 
-	st, _ := s.Up(ctx)
-	name := *host
-	if st != nil && st.Self != nil && st.Self.DNSName != "" {
-		name = strings.TrimSuffix(st.Self.DNSName, ".")
+// resolveBackend builds the proxy target from --backend (preferred) or --port,
+// and rejects anything that is not an http(s) loopback origin.
+func resolveBackend(backend, port string) (*url.URL, error) {
+	raw := backend
+	if raw == "" {
+		raw = "http://127.0.0.1:" + port
 	}
-	fmt.Printf("MESH-URL https://%s\n", name)
+	u, err := url.Parse(raw)
+	if err != nil {
+		return nil, fmt.Errorf("invalid --backend %q: %v", raw, err)
+	}
+	if u.Scheme != "http" && u.Scheme != "https" {
+		return nil, fmt.Errorf("backend scheme must be http/https, got %q", u.Scheme)
+	}
+	if !isLoopbackHost(u.Hostname()) {
+		return nil, fmt.Errorf("backend host must be loopback (127.0.0.1/::1/localhost), got %q", u.Hostname())
+	}
+	// Pin "localhost" to a numeric loopback so the later proxy dial cannot be
+	// redirected off-host by a poisoned resolver / hosts file.
+	if u.Hostname() == "localhost" {
+		if p := u.Port(); p != "" {
+			u.Host = "127.0.0.1:" + p
+		} else {
+			u.Host = "127.0.0.1"
+		}
+	}
+	return u, nil
+}
 
-	_ = http.Serve(ln, rp)
+func isLoopbackHost(h string) bool {
+	if h == "localhost" {
+		return true
+	}
+	ip := net.ParseIP(h)
+	return ip != nil && ip.IsLoopback()
+}
+
+// tryListenTLS returns a TLS listener on :443 only when a cert for `name` looks
+// obtainable; otherwise nil. It first checks the tailnet's advertised cert
+// domains, then proactively warms the cert with a bounded timeout so a failure
+// surfaces here (returning nil) instead of mid-handshake later.
+func tryListenTLS(ctx context.Context, s *tsnet.Server, name string) net.Listener {
+	lc, err := s.LocalClient()
+	if err != nil {
+		return nil
+	}
+	status, err := lc.Status(ctx)
+	if err != nil || status == nil {
+		return nil
+	}
+	eligible := false
+	for _, d := range status.CertDomains {
+		if d == name {
+			eligible = true
+			break
+		}
+	}
+	if !eligible {
+		return nil
+	}
+	// Proactively obtain the cert with a bounded timeout. If the tailnet says the
+	// domain is eligible but issuance still fails (HTTPS not actually enabled,
+	// ACME hiccup), we learn it now and fall back to http rather than hanging the
+	// first browser request.
+	warmCtx, cancel := context.WithTimeout(ctx, certWaitTimeout)
+	defer cancel()
+	if _, _, err := lc.CertPair(warmCtx, name); err != nil {
+		return nil
+	}
+	ln, err := s.ListenTLS("tcp", ":443")
+	if err != nil {
+		return nil
+	}
+	return ln
+}
+
+func redirectToHTTPS(name string) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		u := "https://" + name + r.URL.RequestURI()
+		http.Redirect(w, r, u, http.StatusPermanentRedirect)
+	}
+}
+
+// newEdgeProxy builds the reverse proxy to the loopback backend. It stamps
+// X-Forwarded-Proto (read through *proto, set after the TLS decision) and
+// X-Forwarded-Host so the app never emits mixed-content links. For an https
+// loopback backend (a future self-signed local listener) it skips verification —
+// the host is already validated as loopback, so this is not a trust boundary.
+func newEdgeProxy(target *url.URL, name string, proto *string) *httputil.ReverseProxy {
+	rp := httputil.NewSingleHostReverseProxy(target)
+	orig := rp.Director
+	rp.Director = func(r *http.Request) {
+		orig(r)
+		r.Header.Set("X-Forwarded-Proto", *proto)
+		r.Header.Set("X-Forwarded-Host", name)
+	}
+	if target.Scheme == "https" {
+		rp.Transport = &http.Transport{TLSClientConfig: &tls.Config{InsecureSkipVerify: true}}
+	}
+	return rp
 }

package/mesh/main_test.go

@@ -0,0 +1,119 @@
+package main
+
+import (
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strings"
+	"testing"
+)
+
+func TestResolveBackend(t *testing.T) {
+	cases := []struct {
+		name      string
+		backend   string
+		port      string
+		wantErr   bool
+		wantHost  string // expected resolved u.Host when no error
+	}{
+		{"default port → loopback", "", "7777", false, "127.0.0.1:7777"},
+		{"explicit loopback v4", "http://127.0.0.1:8080", "0", false, "127.0.0.1:8080"},
+		{"loopback v6", "http://[::1]:8080", "0", false, "[::1]:8080"},
+		{"ipv4-mapped loopback", "http://[::ffff:127.0.0.1]:8080", "0", false, "[::ffff:127.0.0.1]:8080"},
+		{"localhost normalized to 127.0.0.1", "http://localhost:9000", "0", false, "127.0.0.1:9000"},
+		{"https loopback allowed", "https://127.0.0.1:8443", "0", false, "127.0.0.1:8443"},
+		{"off-host private ip rejected", "http://10.0.0.5:80", "0", true, ""},
+		{"0.0.0.0 rejected", "http://0.0.0.0:80", "0", true, ""},
+		{"public ip rejected", "http://93.184.216.34:80", "0", true, ""},
+		{"arbitrary dns rejected", "http://evil.example.com:80", "0", true, ""},
+		{"non-loopback v6 rejected", "http://[2001:db8::1]:80", "0", true, ""},
+		{"bad scheme rejected", "ftp://127.0.0.1:80", "0", true, ""},
+		{"file scheme rejected", "file:///etc/passwd", "0", true, ""},
+		{"garbage rejected", "://nope", "0", true, ""},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			u, err := resolveBackend(c.backend, c.port)
+			if c.wantErr {
+				if err == nil {
+					t.Fatalf("expected error for backend=%q, got host=%q", c.backend, u.Host)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("unexpected error for backend=%q: %v", c.backend, err)
+			}
+			if u.Host != c.wantHost {
+				t.Fatalf("backend=%q → host=%q, want %q", c.backend, u.Host, c.wantHost)
+			}
+		})
+	}
+}
+
+func TestIsLoopbackHost(t *testing.T) {
+	loop := []string{"localhost", "127.0.0.1", "127.0.0.2", "::1", "::ffff:127.0.0.1"}
+	notLoop := []string{"0.0.0.0", "10.0.0.1", "192.168.1.1", "93.184.216.34", "2001:db8::1", "example.com", ""}
+	for _, h := range loop {
+		if !isLoopbackHost(h) {
+			t.Errorf("isLoopbackHost(%q) = false, want true", h)
+		}
+	}
+	for _, h := range notLoop {
+		if isLoopbackHost(h) {
+			t.Errorf("isLoopbackHost(%q) = true, want false", h)
+		}
+	}
+}
+
+// End-to-end through the actual reverse proxy (no tailnet): a real loopback
+// backend must receive the X-Forwarded-Proto/Host the edge stamps, and the
+// pointer-captured proto must reflect the post-TLS decision.
+func TestEdgeProxyForwardsProtoAndHost(t *testing.T) {
+	var gotProto, gotHost, gotBody string
+	backend := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotProto = r.Header.Get("X-Forwarded-Proto")
+		gotHost = r.Header.Get("X-Forwarded-Host")
+		io.WriteString(w, "backend-ok")
+	}))
+	defer backend.Close()
+
+	target, _ := url.Parse(backend.URL) // 127.0.0.1 loopback
+	proto := "http"                      // default before the TLS decision
+	rp := newEdgeProxy(target, "node.tailnet.ts.net", &proto)
+	proto = "https" // edge decided real TLS AFTER constructing the proxy
+
+	front := httptest.NewServer(rp)
+	defer front.Close()
+
+	res, err := http.Get(front.URL + "/app")
+	if err != nil {
+		t.Fatalf("proxy request failed: %v", err)
+	}
+	defer res.Body.Close()
+	b, _ := io.ReadAll(res.Body)
+	gotBody = string(b)
+
+	if gotProto != "https" {
+		t.Errorf("backend saw X-Forwarded-Proto=%q, want https (pointer-captured decision)", gotProto)
+	}
+	if gotHost != "node.tailnet.ts.net" {
+		t.Errorf("backend saw X-Forwarded-Host=%q, want node.tailnet.ts.net", gotHost)
+	}
+	if gotBody != "backend-ok" {
+		t.Errorf("proxy body=%q, want backend-ok", gotBody)
+	}
+}
+
+func TestRedirectToHTTPS(t *testing.T) {
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest("GET", "http://anything/path?q=1", nil)
+	redirectToHTTPS("node.tailnet.ts.net")(rec, req)
+	if rec.Code != http.StatusPermanentRedirect {
+		t.Fatalf("status=%d, want 308", rec.Code)
+	}
+	loc := rec.Header().Get("Location")
+	if !strings.HasPrefix(loc, "https://node.tailnet.ts.net/path") || !strings.Contains(loc, "q=1") {
+		t.Fatalf("Location=%q, want https://node.tailnet.ts.net/path?q=1", loc)
+	}
+}

package/mesh-sidecar.lock.json

@@ -0,0 +1,12 @@
+{
+  "version": "1.0.0",
+  "contentHash": "fb010e2cd6a930ef7eeac0de0adaf903cdb7252815650c38eac2d72f15da6e3d",
+  "assets": {
+    "aiordie-mesh-windows-amd64.exe": "7a30a635b726e5cae694e3f48b37b329d470e8cf493ac5f025b99ea4a0fbded0",
+    "aiordie-mesh-windows-arm64.exe": "6d056c561538a40991a975e410b61b7ba4e076c456ee280744ae9ade65202dda",
+    "aiordie-mesh-linux-amd64": "2e5fd52842b67ec56647efb59ce8944bb211055b7630a19206a67b2c80b328fd",
+    "aiordie-mesh-linux-arm64": "7508a98a2762feb3405df54150a34c53028b5588b44eac504835c56a5df82822",
+    "aiordie-mesh-darwin-amd64": "d095c85d01036f3a9a529179c9ef5ca67231150bd49fc5adf1c4fb4e0d0da11b",
+    "aiordie-mesh-darwin-arm64": "8d115b8233697995dc0d7bab8f45f881bba2d37896c86cd70ea626965b1e4cb0"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-or-die",
-  "version": "0.1.87",
+  "version": "0.1.88",
   "description": "Universal AI coding terminal — Claude, Copilot, Gemini & more in your browser",
   "main": "src/server.js",
   "bin": {
@@ -22,6 +22,8 @@
     "test:longevity": "npm run test:longevity:server && npm run test:longevity:browser",
     "build:bundle": "node scripts/build-sea.js bundle",
     "build:sea": "node scripts/build-sea.js",
+    "mesh:lock": "node scripts/mesh-lock.js",
+    "mesh:lock:check": "node scripts/mesh-lock.js --check",
     "release:pr": "bash scripts/release-pr.sh"
   },
   "keywords": [

package/src/mesh-manager.js

@@ -34,12 +34,18 @@ class MeshManager {
       ? path.join(localApp, 'ai-or-die')
       : path.join(os.homedir(), '.ai-or-die');
     this.stateDir = options.stateDir || path.join(base, 'ts-state');
-    const exe = process.platform === 'win32' ? 'aiordie-mesh.exe' : 'aiordie-mesh';
-    this.sidecar = options.sidecar || path.join(base, 'bin', exe);
+    // The sidecar binary is content-addressed: its path embeds the lock's
+    // contentHash so a new build installs alongside the old one (no overwrite of
+    // a running .exe). Derived from the installer's lock + path helpers.
+    this._installer = options._installer || require('./utils/sidecar-installer');
+    this.sidecar = options.sidecar || this._sidecarPathFromLock(base);
     this.hostname = (options.hostname || `aiordie-${os.hostname()}`).toLowerCase().replace(/[^a-z0-9-]/g, '');
 
     this.proc = null;
     this.dnsName = null;
+    this.scheme = null;          // 'https' (edge TLS) or 'http' (degraded)
+    this.backend = options.backend || `http://127.0.0.1:${this.port}`;  // mesh serves plaintext loopback
+    this._lastError = null;
     this.stopping = false;
     this.retryCount = 0;
     this._totalRestarts = 0;
@@ -54,30 +60,40 @@ class MeshManager {
     console.log('\n  Connecting mesh (Tailscale userspace)...');
     this.stopping = false;
     if (!fs.existsSync(this.sidecar)) {
-      if (!(await this._ensureSidecar())) { this._printMissing(); return; }
+      if (!(await this._ensureSidecar())) { this._printMissing(this._lastError); return; }
     }
     if (!this._authKey && !this._enrolled()) { this._printNotEnrolled(); return; }
     try { fs.mkdirSync(this.stateDir, { recursive: true }); } catch (_) {}
     await this._spawn();
   }
 
+  /** Content-addressed sidecar path from the committed lock; safe fallback. */
+  _sidecarPathFromLock(base) {
+    try {
+      const lock = this._installer.loadLock();
+      return this._installer.sidecarPath(lock.contentHash);
+    } catch (_) {
+      const exe = process.platform === 'win32' ? 'aiordie-mesh.exe' : 'aiordie-mesh';
+      return path.join(base, 'bin', exe);
+    }
+  }
+
   /** Download + verify the sidecar from the matching release. Best-effort. */
   async _ensureSidecar() {
     try {
-      const { ensureSidecar } = require('./utils/sidecar-installer');
-      let version = '0.0.0';
-      try { version = require('../package.json').version; } catch (_) {}
       console.log('  [mesh] fetching sidecar binary...');
-      await ensureSidecar(version, this.sidecar);
+      await this._installer.ensureSidecar(this.sidecar);
+      this._lastError = null;
       return fs.existsSync(this.sidecar);
     } catch (e) {
+      this._lastError = e;
       if (this.dev) console.error('  [mesh] sidecar fetch failed:', e.message);
       return false;
     }
   }
 
   getStatus() {
-    return { running: this.proc !== null && !this.stopping && !!this.dnsName, publicUrl: this.dnsName ? `https://${this.dnsName}` : null };
+    return { running: this.proc !== null && !this.stopping && !!this.dnsName, publicUrl: this.dnsName ? `${this.scheme || 'https'}://${this.dnsName}` : null };
   }
 
   async stop() {
@@ -100,7 +116,7 @@ class MeshManager {
 
   _spawn() {
     return new Promise((resolve) => {
-      const args = ['--port', String(this.port), '--hostname', this.hostname, '--statedir', this.stateDir];
+      const args = ['--port', String(this.port), '--backend', this.backend, '--hostname', this.hostname, '--statedir', this.stateDir];
       // Pass the key to the sidecar via TS_AUTHKEY (enroll only); it's already
       // stripped from this process + base child env, so it reaches only this child.
       const env = this._authKey ? { ...this._childEnv, TS_AUTHKEY: this._authKey } : this._childEnv;
@@ -110,12 +126,14 @@ class MeshManager {
       this.proc.stdout.on('data', (d) => {
         const out = d.toString();
         if (this.dev) process.stdout.write(`  [mesh] ${out}`);
-        const url = out.match(/MESH-URL (https:\/\/\S+)/);
+        if (/MESH-NOCERT/.test(out)) this._printNoCert();
+        const url = out.match(/MESH-URL (https?):\/\/(\S+)/);
         if (url && !this.dnsName) {
-          this.dnsName = url[1].replace(/^https:\/\//, '');
+          this.scheme = url[1];
+          this.dnsName = url[2];
           this._authKey = null;
           this._startStabilityTimer();
-          this.onUrl(`https://${this.dnsName}`);
+          this.onUrl(`${this.scheme}://${this.dnsName}`);
           if (!done) { done = true; clearTimeout(timer); resolve(); }
         }
         if (/MESH-NEEDLOGIN/.test(out)) { this._printNotEnrolled(); if (!done) { done = true; clearTimeout(timer); resolve(); } }
@@ -129,11 +147,27 @@ class MeshManager {
     });
   }
 
-  _printMissing() {
-    console.log('\n  \x1b[33mMesh: sidecar not installed.\x1b[0m  Fetched on next release build; see docs/specs/mesh.md.');
+  _printMissing(err) {
+    const code = err && err.code;
+    const map = {
+      'unsupported-platform': `Mesh: no sidecar build for this platform (${err && err.message}).`,
+      'lock-unfinalized': 'Mesh: sidecar checksum missing from this build — upgrade ai-or-die.',
+      'assets-missing': 'Mesh: sidecar binaries for this build are not published yet — try again shortly.',
+      'network': `Mesh: could not download the sidecar — ${err && err.message}.`,
+      'checksum-mismatch': 'Mesh: sidecar checksum mismatch — refusing to run an unverified binary.',
+      'locked-binary': `Mesh: ${err && err.message} — stop any running ai-or-die mesh and retry.`,
+    };
+    const line = (code && map[code]) || 'Mesh: sidecar not installed.';
+    console.log(`\n  \x1b[33m${line}\x1b[0m  See docs/specs/mesh.md.`);
     console.log('  Continuing on localhost/devtunnel.\n');
   }
 
+  _printNoCert() {
+    console.log('\n  \x1b[33mMesh: tailnet HTTPS certificates are not enabled — serving plain http.\x1b[0m');
+    console.log('    Remote microphone (voice) and PWA install need a secure context (https).');
+    console.log('    Enable it once: \x1b[1mhttps://login.tailscale.com/admin/dns\x1b[0m → HTTPS Certificates.');
+  }
+
   _printNotEnrolled() {
     const ex = process.platform === 'win32' ? '$env:AIORDIE_TS_AUTHKEY="<key>"; ai-or-die --mesh' : 'AIORDIE_TS_AUTHKEY=<key> ai-or-die --mesh';
     console.log('\n  \x1b[1m\x1b[33mMesh: NOT ENROLLED\x1b[0m — enroll once:');

package/src/utils/sidecar-installer.js

@@ -1,13 +1,18 @@
 'use strict';
 
 // Sidecar installer — fetches the prebuilt aiordie-mesh tsnet binary for the
-// current platform from the matching GitHub release and verifies it against the
-// release's published SHA-256 checksums before use. Mirrors the download/verify
-// shape of gguf-model-manager (resumable not needed — the binary is ~20MB).
+// current platform and verifies it against a SHA-256 that ships INSIDE this npm
+// package (mesh-sidecar.lock.json). Trust is therefore anchored by the signed
+// npm artifact, not by a checksums file fetched from the same mutable GitHub
+// release (which a tampered release could swap alongside the binary).
+//
+// Identity is content-addressed: the binary lives at the release tag
+// `mesh-<contentHash>` where contentHash is derived from the sidecar source
+// (see scripts/mesh-lock.js). Many ai-or-die versions can pin the same sidecar;
+// CI only rebuilds when the source — and thus the hash — changes.
 //
 // Asset convention (published by .github/workflows/release-on-main.yml):
 //   aiordie-mesh-<plat>-<arch>[.exe]   plat: windows|linux|darwin  arch: amd64|arm64
-//   aiordie-mesh-checksums.txt         "<sha256>  <assetname>" per line
 
 const fs = require('fs');
 const fsp = require('fs').promises;
@@ -19,6 +24,22 @@ const REPO = 'animeshkundu/ai-or-die';
 const PLAT = { win32: 'windows', linux: 'linux', darwin: 'darwin' };
 const ARCH = { x64: 'amd64', arm64: 'arm64' };
 
+// Typed failure so the manager can print an accurate cause instead of a blanket
+// "fetched on next release build".
+class SidecarError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'SidecarError';
+    this.code = code; // unsupported-platform | lock-unfinalized | assets-missing | network | checksum-mismatch | locked-binary
+  }
+}
+
+function loadLock() {
+  // The lock ships at the package root, two levels up from src/utils/.
+  const p = path.join(__dirname, '..', '..', 'mesh-sidecar.lock.json');
+  return JSON.parse(fs.readFileSync(p, 'utf8'));
+}
+
 function assetName() {
   const plat = PLAT[process.platform];
   const arch = ARCH[process.arch];
@@ -26,10 +47,33 @@ function assetName() {
   return `aiordie-mesh-${plat}-${arch}${process.platform === 'win32' ? '.exe' : ''}`;
 }
 
-function sidecarPath() {
+function baseDir() {
   const localApp = process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
-  const base = process.platform === 'win32' ? path.join(localApp, 'ai-or-die') : path.join(os.homedir(), '.ai-or-die');
-  return path.join(base, 'bin', `aiordie-mesh${process.platform === 'win32' ? '.exe' : ''}`);
+  return process.platform === 'win32' ? path.join(localApp, 'ai-or-die') : path.join(os.homedir(), '.ai-or-die');
+}
+
+// Versioned path: a new contentHash installs alongside the old one, so we never
+// rename over a binary that a running sidecar still has open (Windows EPERM).
+function sidecarPath(contentHash) {
+  const ext = process.platform === 'win32' ? '.exe' : '';
+  return path.join(baseDir(), 'bin', `aiordie-mesh-${contentHash}${ext}`);
+}
+
+// The release ref to fetch from. Defaults to mesh-<contentHash>; an explicit
+// override is a dev/testing escape hatch and is announced loudly.
+function meshRef(lock) {
+  const override = process.env.AIORDIE_MESH_REF || process.env.AIORDIE_MESH_VERSION;
+  if (override) {
+    // Constrain to a safe tag shape — no path segments / traversal — even though
+    // the host is fixed. This is a dev/testing escape hatch, announced loudly.
+    const ref = /^mesh-/.test(override) ? override : `mesh-${override}`;
+    if (!/^mesh-[A-Za-z0-9._-]+$/.test(ref)) {
+      throw new SidecarError('unsupported-platform', `invalid AIORDIE_MESH_REF ${JSON.stringify(override)}`);
+    }
+    console.warn(`  \x1b[33m[mesh] overriding sidecar ref → ${ref} (AIORDIE_MESH_REF/VERSION)\x1b[0m`);
+    return ref;
+  }
+  return `mesh-${lock.contentHash}`;
 }
 
 async function _sha256(file) {
@@ -42,68 +86,87 @@ async function _sha256(file) {
   });
 }
 
-async function _fetchText(url, ms = 15000) {
+async function _download(url, tmp, ms = 120000) {
   const ac = new AbortController();
   const t = setTimeout(() => ac.abort(), ms);
+  let r;
   try {
-    const r = await fetch(url, { signal: ac.signal });
-    if (!r.ok) throw new Error(`HTTP ${r.status}`);
-    return await r.text();
-  } finally { clearTimeout(t); }
+    r = await fetch(url, { signal: ac.signal });
+  } catch (e) {
+    throw new SidecarError('network', `could not reach ${hostOf(url)} (${e.message})`);
+  } finally {
+    clearTimeout(t);
+  }
+  if (r.status === 404) throw new SidecarError('assets-missing', `HTTP 404 for ${url}`);
+  if (!r.ok || !r.body) throw new SidecarError('network', `HTTP ${r.status} for ${url}`);
+  // Exclusive create — never follow/overwrite a pre-planted file or symlink.
+  const out = fs.createWriteStream(tmp, { flags: 'wx' });
+  const reader = r.body.getReader();
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    await new Promise((res, rej) => out.write(value, (e) => (e ? rej(e) : res())));
+  }
+  await new Promise((res) => out.end(res));
 }
 
-async function _download(url, tmp, ms = 120000) {
-  const ac = new AbortController();
-  const t = setTimeout(() => ac.abort(), ms);
-  try {
-    const r = await fetch(url, { signal: ac.signal });
-    if (!r.ok || !r.body) throw new Error(`HTTP ${r.status}`);
-    // Exclusive create — never follow/overwrite a pre-planted file or symlink.
-    const out = fs.createWriteStream(tmp, { flags: 'wx' });
-    const reader = r.body.getReader();
-    for (;;) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      await new Promise((res, rej) => out.write(value, (e) => (e ? rej(e) : res())));
-    }
-    await new Promise((res) => out.end(res));
-  } finally { clearTimeout(t); }
+function hostOf(url) {
+  try { return new URL(url).host; } catch (_) { return 'github.com'; }
 }
 
-// Ensure the sidecar binary exists locally AND matches the release checksum;
-// download + verify if missing or stale. Returns the path; throws on failure.
-async function ensureSidecar(version, dest = sidecarPath()) {
+// Ensure the sidecar binary exists locally AND matches the lock's checksum;
+// download + verify if missing. Returns the path; throws SidecarError on failure.
+// `opts.lock` injects a lock object (tests); production reads the committed lock.
+async function ensureSidecar(dest, opts = {}) {
+  const lock = opts.lock || loadLock();
   const name = assetName();
-  if (!name) throw new Error(`unsupported platform ${process.platform}/${process.arch}`);
-
-  // Resolve the expected hash first so an existing file is also verified.
-  const baseUrl = `https://github.com/${REPO}/releases/download/v${version}`;
-  const sums = await _fetchText(`${baseUrl}/aiordie-mesh-checksums.txt`);
-  const line = sums.split('\n').find((l) => {
-    const f = l.trim().split(/\s+/)[1];   // exact filename column, not endsWith
-    return f === name;
-  });
-  if (!line) throw new Error(`no checksum for ${name} in release v${version}`);
-  const want = line.trim().split(/\s+/)[0].toLowerCase();
+  if (!name) throw new SidecarError('unsupported-platform', `unsupported platform ${process.platform}/${process.arch}`);
+
+  const want = (lock.assets && lock.assets[name] || '').toLowerCase();
+  if (!want) {
+    throw new SidecarError('lock-unfinalized', `mesh-sidecar.lock.json has no checksum for ${name} (built without the mesh asset pipeline?)`);
+  }
+
+  dest = dest || sidecarPath(lock.contentHash);
 
   // Existing file: trust only if it matches; otherwise replace it.
   if (fs.existsSync(dest)) {
     if ((await _sha256(dest)).toLowerCase() === want) return dest;
-    try { await fsp.unlink(dest); } catch (_) {}
+    try { await fsp.unlink(dest); }
+    catch (e) {
+      if (e.code === 'EPERM' || e.code === 'EBUSY' || e.code === 'EACCES') {
+        throw new SidecarError('locked-binary', `cannot replace in-use sidecar at ${dest} (${e.code})`);
+      }
+      throw e; // surface real filesystem faults instead of masking them
+    }
   }
 
   await fsp.mkdir(path.dirname(dest), { recursive: true });
+  const ref = meshRef(lock);
+  const url = `https://github.com/${REPO}/releases/download/${ref}/${name}`;
   const tmp = `${dest}.${crypto.randomBytes(8).toString('hex')}.incomplete`;
   try {
-    await _download(`${baseUrl}/${name}`, tmp);
+    await _download(url, tmp);
     // Verify BEFORE the bytes ever reach the runnable path (no TOCTOU window).
-    if ((await _sha256(tmp)).toLowerCase() !== want) throw new Error(`checksum mismatch for ${name}`);
+    if ((await _sha256(tmp)).toLowerCase() !== want) {
+      throw new SidecarError('checksum-mismatch', `checksum mismatch for ${name} from ${ref}`);
+    }
     if (process.platform !== 'win32') { try { await fsp.chmod(tmp, 0o755); } catch (_) {} }
-    await fsp.rename(tmp, dest);
+    try {
+      await fsp.rename(tmp, dest);
+    } catch (e) {
+      // Lost a race to a concurrent installer (or the file is locked). If the
+      // destination is now present and valid, accept it; otherwise surface it.
+      if (fs.existsSync(dest) && (await _sha256(dest)).toLowerCase() === want) return dest;
+      if (e.code === 'EPERM' || e.code === 'EBUSY' || e.code === 'EACCES') {
+        throw new SidecarError('locked-binary', `cannot install sidecar at ${dest} (${e.code})`);
+      }
+      throw e;
+    }
   } finally {
     try { await fsp.unlink(tmp); } catch (_) {}
   }
   return dest;
 }
 
-module.exports = { ensureSidecar, sidecarPath, assetName };
+module.exports = { ensureSidecar, sidecarPath, assetName, loadLock, SidecarError };