brane 0.1.1 → 0.3.0

package/dist/tls.js

@@ -0,0 +1,148 @@
+// TLS certificate management for the brane daemon.
+//
+// The daemon serves over HTTPS using Tailscale-issued Let's Encrypt certs.
+// `provisionTlsCert` shells out to `tailscale cert` (the same command the
+// `brane certify` CLI uses) and lands a fresh cert/key pair on disk.
+// `parseCertExpiry` reads a cert file and returns its `notAfter` so the
+// CertManager can decide when to renew.
+//
+// Both functions are pure plumbing — no schedule, no state, no logging.
+// The renewal/scheduling/hot-reload policy lives in src/daemon/cert-manager.ts.
+import { execFile } from "node:child_process";
+import { X509Certificate } from "node:crypto";
+import { readFileSync, renameSync } from "node:fs";
+/**
+ * Provision a TLS cert+key pair for `host` via `tailscale cert`.
+ *
+ * Writes to temporary `.new` files, validates the result (parses, future
+ * `notAfter`, subject CN matches `host`), then atomically renames them into
+ * place. Partial failures leave the existing cert intact.
+ */
+export function provisionTlsCert(opts) {
+    const { host, certPath, keyPath, timeoutMs = 30000 } = opts;
+    const tmpCert = certPath + ".new";
+    const tmpKey = keyPath + ".new";
+    return new Promise((resolve) => {
+        execFile("tailscale", ["cert", "--cert-file", tmpCert, "--key-file", tmpKey, host], { timeout: timeoutMs }, (err, _stdout, stderr) => {
+            if (err) {
+                resolve({
+                    ok: false,
+                    reason: classifyTailscaleError(err, stderr),
+                    message: err.message,
+                    stderr,
+                });
+                return;
+            }
+            // tailscale cert exited 0 — validate before swapping in.
+            let parsed;
+            try {
+                parsed = new X509Certificate(readFileSync(tmpCert));
+            }
+            catch (parseErr) {
+                resolve({
+                    ok: false,
+                    reason: "invalid_output",
+                    message: `Provisioned cert at ${tmpCert} did not parse: ${parseErr.message}`,
+                });
+                return;
+            }
+            const notAfter = parseValidTo(parsed.validTo);
+            if (!notAfter || notAfter.getTime() <= Date.now()) {
+                resolve({
+                    ok: false,
+                    reason: "invalid_output",
+                    message: `Provisioned cert has invalid or past notAfter: ${parsed.validTo}`,
+                });
+                return;
+            }
+            // Subject should match the requested host. tailscale puts the host
+            // in the CN; we accept any cert whose subject CN equals host, which
+            // is what tailscale always produces.
+            if (!subjectMatchesHost(parsed, host)) {
+                resolve({
+                    ok: false,
+                    reason: "invalid_output",
+                    message: `Provisioned cert subject ${parsed.subject} does not match host ${host}`,
+                });
+                return;
+            }
+            try {
+                renameSync(tmpCert, certPath);
+                renameSync(tmpKey, keyPath);
+            }
+            catch (renameErr) {
+                resolve({
+                    ok: false,
+                    reason: "unknown",
+                    message: `Failed to install provisioned cert: ${renameErr.message}`,
+                });
+                return;
+            }
+            resolve({ ok: true, certPath, keyPath, notAfter });
+        });
+    });
+}
+/** Read a cert file and return its X.509 `notAfter` date. */
+export function parseCertExpiry(certPath) {
+    try {
+        const cert = new X509Certificate(readFileSync(certPath));
+        return parseValidTo(cert.validTo);
+    }
+    catch {
+        return null;
+    }
+}
+/** Read a cert file and return both expiry and subject in one shot. */
+export function inspectCert(certPath) {
+    try {
+        const cert = new X509Certificate(readFileSync(certPath));
+        const notAfter = parseValidTo(cert.validTo);
+        if (!notAfter)
+            return null;
+        return { notAfter, subject: cert.subject };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Parse the X509Certificate#validTo string into a Date.
+ *
+ * Node added `X509Certificate#validToDate` in v23.0.0; on Node 20 (our LTS
+ * baseline) only the string form is available. The string is OpenSSL's
+ * ASN1_TIME format, e.g. "Jun 21 14:41:05 2026 GMT" — a format `new Date()`
+ * parses reliably across V8 versions on every platform we ship to.
+ */
+function parseValidTo(validTo) {
+    if (!validTo)
+        return null;
+    const d = new Date(validTo);
+    return Number.isNaN(d.getTime()) ? null : d;
+}
+function classifyTailscaleError(err, stderr) {
+    if (err.code === "ENOENT")
+        return "tailscale_missing";
+    if (err.signal === "SIGTERM" || err.killed)
+        return "timeout";
+    const haystack = (stderr ?? "").toLowerCase();
+    // Tailscale messaging is stable enough to pattern-match. Examples we've
+    // seen in the wild:
+    //   "HTTPS must be enabled..." (admin console toggle off)
+    //   "HTTPS is not enabled for this tailnet"
+    //   "no such host" / "is not in your tailnet" (wrong host)
+    if (haystack.includes("https") && (haystack.includes("not enabled") || haystack.includes("must be enabled"))) {
+        return "https_not_enabled";
+    }
+    if (haystack.includes("no such host") || haystack.includes("not in your tailnet")) {
+        return "bad_host";
+    }
+    return "unknown";
+}
+function subjectMatchesHost(cert, host) {
+    // X509Certificate.subject is multi-line "CN=foo\nO=bar". Pull the CN.
+    const cnLine = cert.subject.split(/\r?\n/).find((l) => l.startsWith("CN="));
+    if (!cnLine)
+        return false;
+    return cnLine.slice(3).trim().toLowerCase() === host.toLowerCase();
+}
+//# sourceMappingURL=tls.js.map

package/dist/tmux.js

@@ -0,0 +1,202 @@
+import { accessSync, constants, existsSync, mkdirSync, chmodSync, unlinkSync, createWriteStream, createReadStream, } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+import { homedir, platform, arch } from "node:os";
+import { get as httpsGet } from "node:https";
+import { createHash } from "node:crypto";
+let cachedPath;
+const TMUX_VERSION = "3.6a";
+const BRANE_BIN = join(homedir(), ".brane", "bin");
+const BUNDLED_TMUX = join(BRANE_BIN, "tmux");
+// Map Node.js platform/arch to tmux-builds release-asset naming.
+const PLATFORM_MAP = { darwin: "macos", linux: "linux" };
+const ARCH_MAP = { arm64: "arm64", x64: "x86_64" };
+// Pinned SHA-256 digests for tmux-builds v3.6a release assets, keyed by
+// `${os}-${cpu}`. Sourced from the GitHub release API's asset `digest`
+// field. If an upstream asset is ever re-uploaded or substituted, the
+// hash check below fails closed and we refuse to extract/run it.
+const SHA256 = {
+    "linux-arm64": "bb5afd9d646df54a7d7c66e198aa22c7d293c7453534f1670f7c540534db8b5e",
+    "linux-x86_64": "c0a772a5e6ca8f129b0111d10029a52e02bcbc8352d5a8c0d3de8466a1e59c2e",
+    "macos-arm64": "12b5b9f8696e1286897d946649c0a80d0169dd76e018d34476a1fbd34de89a0f",
+    "macos-x86_64": "b9b12eaeba43acf5671acf3857d947525440b544185a8db34ea557199a090251",
+};
+/** Scan PATH for an executable — pure in-process, no subprocess spawn. */
+function findInPath(name) {
+    for (const dir of (process.env.PATH ?? "").split(":")) {
+        if (!dir)
+            continue;
+        const candidate = join(dir, name);
+        try {
+            accessSync(candidate, constants.X_OK);
+            return candidate;
+        }
+        catch { }
+    }
+    return undefined;
+}
+/** Resolve the tmux binary: system PATH first, then ~/.brane/bin/, then error. */
+export function resolveTmux() {
+    if (cachedPath)
+        return cachedPath;
+    // 1. System PATH (in-process scan, no subprocess)
+    const systemTmux = findInPath("tmux");
+    if (systemTmux) {
+        cachedPath = systemTmux;
+        return cachedPath;
+    }
+    // 2. Binary fetched lazily by ensureTmux() into ~/.brane/bin/
+    try {
+        accessSync(BUNDLED_TMUX, constants.X_OK);
+        cachedPath = BUNDLED_TMUX;
+        return cachedPath;
+    }
+    catch { }
+    throw new Error("tmux not found. Install it with: brew install tmux (macOS) or apt install tmux (Linux)");
+}
+let ensurePromise;
+/**
+ * Ensure a usable tmux exists, downloading a verified static binary into
+ * ~/.brane/bin/ if neither a system tmux nor a previously-fetched one is
+ * present. Best-effort and idempotent: single-flighted, never throws, and
+ * never blocks the caller's success path — if it cannot provide tmux,
+ * resolveTmux() will surface the actionable "install tmux" error when a
+ * tmux-dependent operation is actually attempted.
+ */
+export function ensureTmux() {
+    if (!ensurePromise)
+        ensurePromise = doEnsureTmux();
+    return ensurePromise;
+}
+async function doEnsureTmux() {
+    // Already satisfiable — system tmux or a prior fetch.
+    if (findInPath("tmux"))
+        return;
+    try {
+        accessSync(BUNDLED_TMUX, constants.X_OK);
+        return;
+    }
+    catch { }
+    const os = PLATFORM_MAP[platform()];
+    const cpu = ARCH_MAP[arch()];
+    if (!os || !cpu) {
+        console.error(`brane: no prebuilt tmux for ${platform()}-${arch()}; install tmux manually`);
+        return;
+    }
+    const key = `${os}-${cpu}`;
+    const expected = SHA256[key];
+    const url = `https://github.com/tmux/tmux-builds/releases/download/v${TMUX_VERSION}/tmux-${TMUX_VERSION}-${key}.tar.gz`;
+    const tarball = join(BRANE_BIN, `tmux-${TMUX_VERSION}.tar.gz`);
+    try {
+        mkdirSync(BRANE_BIN, { recursive: true });
+        console.error("brane: tmux not found, downloading static binary…");
+        // Download (follows redirects — GitHub releases redirect to a CDN).
+        await download(url, tarball);
+        // Verify integrity before trusting the archive. Fail closed: on any
+        // mismatch (or missing pin) delete the file and refuse to extract or
+        // run an unverified binary.
+        const actual = await sha256File(tarball);
+        if (!expected || actual !== expected) {
+            try {
+                unlinkSync(tarball);
+            }
+            catch { }
+            console.error(`brane: tmux archive failed SHA-256 verification (expected ${expected ?? "n/a"}, got ${actual}); refusing to install. Install manually: brew install tmux`);
+            return;
+        }
+        // Extract — the tarball contains a bare "tmux" at its root.
+        const { execFileSync } = await import("node:child_process");
+        execFileSync("tar", ["xzf", tarball, "-C", BRANE_BIN, "tmux"], {
+            stdio: "ignore",
+        });
+        try {
+            unlinkSync(tarball);
+        }
+        catch { }
+        if (existsSync(BUNDLED_TMUX)) {
+            chmodSync(BUNDLED_TMUX, 0o755);
+            console.error(`brane: tmux ${TMUX_VERSION} installed to ${BUNDLED_TMUX}`);
+        }
+        else {
+            console.error("brane: failed to extract tmux binary from archive");
+        }
+    }
+    catch (err) {
+        try {
+            unlinkSync(tarball);
+        }
+        catch { }
+        console.error(`brane: failed to download tmux (${err.message}). Install manually: brew install tmux`);
+    }
+}
+/** Compute the SHA-256 hex digest of a file by streaming it. */
+function sha256File(path) {
+    return new Promise((resolve, reject) => {
+        const hash = createHash("sha256");
+        const stream = createReadStream(path);
+        stream.on("data", (chunk) => hash.update(chunk));
+        stream.on("end", () => resolve(hash.digest("hex")));
+        stream.on("error", reject);
+    });
+}
+/** Download a URL to a file, following up to 5 redirects. */
+function download(url, dest, redirects = 0) {
+    if (redirects > 5)
+        return Promise.reject(new Error("Too many redirects"));
+    return new Promise((resolve, reject) => {
+        const file = createWriteStream(dest);
+        httpsGet(url, (res) => {
+            const status = res.statusCode ?? 0;
+            if (status >= 300 && status < 400 && res.headers.location) {
+                file.close();
+                download(res.headers.location, dest, redirects + 1).then(resolve, reject);
+                return;
+            }
+            if (status !== 200) {
+                file.close();
+                reject(new Error(`HTTP ${status}`));
+                return;
+            }
+            res.pipe(file);
+            file.on("finish", () => file.close(() => resolve()));
+            file.on("error", reject);
+        }).on("error", (err) => {
+            file.close();
+            reject(err);
+        });
+    });
+}
+/** A tmux command-language word: single-quoted, nothing inside is special
+ *  (`$`, `~`, `#`, `;`), and a `'` is closed, escaped and reopened. */
+export function tmuxQuote(word) {
+    return `'${word.replace(/'/g, `'\\''`)}'`;
+}
+/** The `new-session` line `newTmuxSession` sends, as tmux will parse it. */
+export function newSessionLine(opts) {
+    const parts = ["new-session", "-d", "-s", tmuxQuote(opts.name), "-c", tmuxQuote(opts.cwd)];
+    if (opts.size)
+        parts.push("-x", String(opts.size.cols), "-y", String(opts.size.rows));
+    parts.push(tmuxQuote(opts.command));
+    return parts.join(" ");
+}
+/** Start a detached tmux session running `command`, without the command
+ *  ever appearing in a process's arguments. A launch command carries the
+ *  session's agent token (`BRANE_NARRATIVE_SECRET=…`), and arguments are
+ *  readable by every user on the machine through `ps` — for the client's
+ *  brief life, and for the tmux *server's* whole life when this call is the
+ *  one that starts it, since the server is forked from that client and keeps
+ *  its argv. So the command goes to `tmux source-file -` on stdin, and what
+ *  `ps` shows is `tmux source-file -`. Throws if tmux refuses (a duplicate
+ *  session name, say). */
+export function newTmuxSession(opts) {
+    // `source-file` alone needs a server already running, and tmux exits with
+    // its last session, so the first launch after a reboot would fail
+    // (claude-jrjh1e8w:22). `start-server` starts one if needed — with this
+    // argv, which carries no secret — and is a no-op otherwise.
+    const socketArgs = opts.socket ? ["-S", opts.socket] : [];
+    execFileSync(resolveTmux(), [...socketArgs, "start-server", ";", "source-file", "-"], {
+        input: newSessionLine(opts) + "\n",
+        stdio: ["pipe", "ignore", "pipe"],
+    });
+}
+//# sourceMappingURL=tmux.js.map

package/dist/user-agent.js

@@ -0,0 +1,46 @@
+/**
+ * A short "Safari on iPhone" for a User-Agent header, for the Devices list.
+ * It is a label for a human telling rows apart, not a detection anyone should
+ * branch on: User-Agents lie (an iPad asks for desktop sites as a Mac), and
+ * that is fine here — the row also shows where and when it was seen.
+ *
+ * Order matters: every Chromium browser also says "Chrome" and "Safari", and
+ * every iOS browser is WebKit underneath and says "Safari" or nothing.
+ */
+const BROWSERS = [
+    [/\bEdg(?:e|A|iOS)?\//, "Edge"],
+    [/\bOPR\/|\bOPiOS\//, "Opera"],
+    [/\bFirefox\/|\bFxiOS\//, "Firefox"],
+    [/\bCriOS\//, "Chrome"],
+    [/\bChrome\//, "Chrome"],
+    [/\bVersion\/[\d.]+.*\bSafari\//, "Safari"],
+];
+const PLATFORMS = [
+    [/\biPhone\b/, "iPhone"],
+    [/\biPad\b/, "iPad"],
+    [/\bAndroid\b/, "Android"],
+    [/\bCrOS\b/, "ChromeOS"],
+    [/\bMacintosh\b|\bMac OS X\b/, "macOS"],
+    [/\bWindows\b/, "Windows"],
+    [/\bLinux\b/, "Linux"],
+];
+export function describeUserAgent(ua) {
+    if (!ua)
+        return null;
+    const browser = BROWSERS.find(([re]) => re.test(ua))?.[1];
+    const platform = PLATFORMS.find(([re]) => re.test(ua))?.[1];
+    if (browser && platform)
+        return `${browser} on ${platform}`;
+    // An app saved to an iPhone's home screen drops the Safari token and keeps
+    // only WebKit's.
+    if (platform && /\bAppleWebKit\//.test(ua))
+        return `Web app on ${platform}`;
+    if (browser)
+        return browser;
+    if (platform)
+        return platform;
+    // Not a browser: `node`, `curl/8.7.1`. Its product name is the best label.
+    const product = /^([A-Za-z][\w.-]*)/.exec(ua)?.[1];
+    return product && product !== "Mozilla" ? product : null;
+}
+//# sourceMappingURL=user-agent.js.map

package/docker-entrypoint.sh

@@ -0,0 +1,141 @@
+#!/bin/bash
+set -e
+
+# Volume is mounted at /home/brane (the entire home directory).
+# Migrate from old layout where volume was mounted at /home/brane/.brane
+# and contained brane.db at the volume root.
+if [ -f /home/brane/brane.db ] && [ ! -d /home/brane/.brane/db ]; then
+    echo "Migrating volume layout: moving contents into .brane/ subdirectory..."
+    mkdir -p /home/brane/.brane
+    # Move everything except .brane itself into .brane/
+    for f in /home/brane/*; do
+        [ "$(basename "$f")" = ".brane" ] && continue
+        mv "$f" /home/brane/.brane/
+    done
+    for f in /home/brane/.[!.]* /home/brane/..?*; do
+        [ -e "$f" ] || continue
+        [ "$(basename "$f")" = ".brane" ] && continue
+        mv "$f" /home/brane/.brane/
+    done
+    echo "Migration complete."
+fi
+
+# Ensure the brane user owns the home directory
+chown -R brane:brane /home/brane
+
+# Copy tmux binary into the volume if missing (the image layer copy is
+# hidden when the persistent volume mounts over /home/brane)
+if [ ! -f /home/brane/.brane/bin/tmux ] && [ -f /root/.brane/bin/tmux ]; then
+    mkdir -p /home/brane/.brane/bin
+    cp /root/.brane/bin/tmux /home/brane/.brane/bin/tmux
+    chown brane:brane /home/brane/.brane/bin/tmux
+fi
+
+# Tailscale state lives inside the brane data volume (single mount on Fly)
+TS_STATE=/home/brane/.brane/tailscale
+mkdir -p "$TS_STATE"
+
+# Start tailscaled as root (needs privileges for networking)
+tailscaled --tun=userspace-networking --statedir="$TS_STATE" &
+
+# Wait for the tailscaled socket
+for i in $(seq 1 10); do
+    [ -S /var/run/tailscale/tailscaled.sock ] && break
+    sleep 1
+done
+
+# Authenticate with Tailscale (as root).
+# Build hostname: append Fly region if available (e.g., brane-5a04ec-nrt)
+TS_HOSTNAME="${TS_HOSTNAME:-brane}"
+if [ -n "$FLY_REGION" ]; then
+    TS_HOSTNAME="${TS_HOSTNAME}-${FLY_REGION}"
+fi
+# The node is tag-owned, so its key never expires. Every `up` names the tags:
+# one without them asks control to drop them, which needs a login nobody here
+# can complete. --timeout makes any such wait fail instead of hang.
+TS_TAGS="${TS_TAGS:-tag:brane}"
+TS_UP=(tailscale up --reset --hostname="$TS_HOSTNAME" --advertise-tags="$TS_TAGS")
+
+# Fly's OIDC token for this machine (`sub` is <org>:<app>:<machine>), which
+# Tailscale's workload identity federation trades for a node key.
+fly_oidc_token() {
+    local out
+    out=$(curl -fsS --unix-socket /.fly/api -X POST http://localhost/v1/tokens/oidc \
+        -H 'Content-Type: application/json' --data "{\"aud\":\"$1\"}") || return 1
+    case "$out" in
+        \{*) printf '%s' "$out" | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{const j=JSON.parse(s);process.stdout.write(j.token||j.jwt||j.id_token||"")})' ;;
+        *) printf '%s' "$out" | tr -d '"\r\n' ;;
+    esac
+}
+
+# The state on the volume first (every restart after the first boot), then a
+# credential: TS_CLIENT_ID (workload identity: no secret on Fly) or TS_AUTHKEY
+# (an auth key or OAuth client secret allowed to apply $TS_TAGS).
+if "${TS_UP[@]}" --timeout=30s; then
+    :
+elif [ -n "$TS_CLIENT_ID" ]; then
+    ID_TOKEN=$(fly_oidc_token "${TS_AUDIENCE:-api.tailscale.com/${TS_CLIENT_ID}}") || ID_TOKEN=
+    if [ -z "$ID_TOKEN" ]; then
+        echo "entrypoint: could not get an OIDC token from Fly for Tailscale" >&2
+        exit 1
+    fi
+    "${TS_UP[@]}" --timeout=60s --client-id="${TS_CLIENT_ID}?ephemeral=false&preauthorized=true" --id-token="$ID_TOKEN"
+elif [ -n "$TS_AUTHKEY" ]; then
+    "${TS_UP[@]}" --timeout=60s --auth-key="$TS_AUTHKEY"
+else
+    echo "entrypoint: not on the tailnet, and neither TS_CLIENT_ID nor TS_AUTHKEY is set" >&2
+    exit 1
+fi
+
+# Allow the brane user to manage Tailscale (needed for cert provisioning)
+tailscale set --operator=brane || true
+
+# Provision TLS cert from Tailscale (non-fatal if it fails)
+gosu brane brane certify 2>/dev/null || true
+
+# Ensure workspace directory exists on the volume
+mkdir -p /home/brane/workspace
+chown brane:brane /home/brane/workspace
+
+# Ensure .mcp.json exists so agents have brane MCP tools from the start
+MCP_JSON=/home/brane/workspace/.mcp.json
+if [ ! -f "$MCP_JSON" ]; then
+    cat > "$MCP_JSON" <<'MCPEOF'
+{"mcpServers":{"brane":{"command":"node","args":["/usr/local/bin/brane","mcp"]}}}
+MCPEOF
+    chown brane:brane "$MCP_JSON"
+fi
+
+# Clear stale daemon meta from the persisted volume — PIDs from a previous
+# container life are never valid in a new container, but may collide with
+# a live PID here (e.g., tailscaled) and trip the "already running" check.
+gosu brane sqlite3 /home/brane/.brane/brane.db \
+    "DELETE FROM meta WHERE key IN ('daemon_pid','daemon_token','daemon_port','daemon_version','daemon_tls','daemon_http_port','daemon_socket');" \
+    2>/dev/null || true
+
+# Register the default workspace as a fold (idempotent) once the daemon is up.
+# `brane fold` is a daemon client: run before the daemon, it would start one
+# of its own, and the exec below would start a second on the same database.
+# The daemon records its port only after its socket is bound, and the rows
+# above are gone, so a port here means the daemon below is ready.
+(
+    for i in $(seq 1 120); do
+        port=$(gosu brane sqlite3 /home/brane/.brane/brane.db \
+            "SELECT value FROM meta WHERE key = 'daemon_port';" 2>/dev/null || true)
+        if [ -n "$port" ]; then
+            gosu brane brane fold /home/brane/workspace >/dev/null ||
+                echo "entrypoint: could not register /home/brane/workspace as a fold" >&2
+            exit 0
+        fi
+        sleep 1
+    done
+    echo "entrypoint: no daemon after 120s; /home/brane/workspace is not registered as a fold" >&2
+) &
+
+# Drop privileges and run the daemon as the brane user.
+# --bind 0.0.0.0: tailscaled --tun=userspace-networking doesn't put the
+# 100.x.y.z address on a kernel interface, so a specific bind to it fails
+# with EADDRNOTAVAIL. Binding broadly is safe here — Fly's only reachable
+# networks are Tailscale and the private 6PN, both of which the userspace
+# IP filter already restricts.
+exec gosu brane brane daemon start --foreground --bind 0.0.0.0 "$@"

package/docs/README.md

@@ -0,0 +1,3 @@
+# docs/
+
+Design notes for brane's subsystems, one file each. They are indexed, with a line on what each covers and which code it goes with, in [AGENTS.md's Further Reading](../AGENTS.md#further-reading). The rules that apply to every change are in [AGENTS.md](../AGENTS.md) itself.