golem-bridge 1.0.1 → 1.0.3

package/README.md

@@ -8,12 +8,15 @@ distributed through the Roblox Creator Store, not from here.
 
 ## How it connects
 
-The plugin shows one line in Studio (popup on first run, also in Settings):
+The plugin shows one line in Studio (popup on every start, also in Settings):
 
 ```
 Connect to my Roblox Studio, Run: npx golem-bridge connect <channelId>
 ```
 
+The line is a session token: Studio mints a fresh channel on every start
+and wipes the old one.
+
 The user sends that line to their AI. It downloads this package, which asks
 the plugin for its two connection files and stores them under `./.golem/`:
 
@@ -25,7 +28,49 @@ python3 ./.golem/golem.py ping
 `ping` should return `"ok": true` plus the open place name. Then the agent
 reads `./.golem/golem.md` for the full tool reference.
 
+After a Studio restart, relink with the new line:
+
+```sh
+npx golem-bridge reconnect <newChannelId>
+```
+
+Done with a session? Forget it locally (Studio is unaffected):
+
+```sh
+npx golem-bridge disconnect
+```
+
 ## Files
 
 - `cli.js` - source of the `golem-bridge` package
 - `package.json` - npm manifest
+
+## Notes
+
+- Relay: `https://roblox-golem-default-rtdb.firebaseio.com/`. The channel id
+is the secret. Studio mints a fresh one on every start and wipes the old
+channel, so a leaked line dies with the session.
+- The plugin serves `golem.py` and `golem.md` on demand. They are never
+stored on the relay.
+
+## Security
+
+Trust model: whoever holds the channel ID can send commands to that Studio
+session and read the results. Treat the setup line like a password. It
+expires on every Studio restart.
+
+- The CLI (`cli.js`, about 200 lines) is the only code that runs on the
+agent side. Read it here, or fetch without writing anything:
+`npx golem-bridge connect <channelId> --print`.
+- `connect` only accepts hex channel IDs, talks HTTPS to the relay only
+(never follows redirects), times out stalled requests, caps response
+sizes, validates the payload shape before writing, and prints SHA-256
+hashes of both files. It writes nothing unless every check passes, and
+tells you to review both files before running anything.
+- There are no baked-in Firebase credentials or signing keys: the channel
+ID itself is the capability, and transport runs over HTTPS. Public client
+code cannot hold a secret, so any "signed responses" scheme here would be
+theater rather than security.
+- Socket.dev flags the "URL strings" in this package (the relay address).
+That is informational: the relay address is the product. The setup payload
+is validated as described above before anything is written.

package/cli.js

@@ -4,37 +4,99 @@
 // golem-bridge: pulls golem.py and golem.md from the Golem Studio plugin
 // over Firebase and writes them to ./.golem/
 
+const crypto = require("crypto");
 const fs = require("fs");
 const path = require("path");
 
 const DB_URL = "https://roblox-golem-default-rtdb.firebaseio.com";
 const POLL_INTERVAL_MS = 2000;
 const POLL_ATTEMPTS = 45;
+const FETCH_TIMEOUT_MS = 30000;
+const MAX_BODY_BYTES = 2 * 1024 * 1024;
+const MAX_FILE_BYTES = 1024 * 1024;
+// Channel IDs are hex tokens minted by the Studio plugin (16 chars today,
+// tolerated 8-64 for forward compatibility). Anything else is rejected so a
+// malformed ID can never alter the request URL.
+const CHANNEL_RE = /^[0-9a-fA-F]{8,64}$/;
 
-function usage() {
-  console.error("Usage: golem-bridge connect <channelId>");
-  console.error("  <channelId> is shown in the Golem plugin widget inside Roblox Studio.");
-  process.exit(1);
+let VERSION = "unknown";
+try {
+  VERSION = require("./package.json").version || "unknown";
+} catch {
+  // running outside the package dir; version is informational only
 }
 
-async function postJson(url, body) {
-  const res = await fetch(url, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify(body),
-  });
-  if (!res.ok) {
-    throw new Error(`POST ${url} failed: HTTP ${res.status}`);
+function printHelp() {
+  console.log(`golem-bridge v${VERSION} — connect an AI agent to Roblox Studio via the Golem plugin.
+
+Usage:
+  golem-bridge connect <channelId> [--print]
+  golem-bridge reconnect <channelId> [--print]
+  golem-bridge disconnect
+  golem-bridge --help
+  golem-bridge --version
+
+  <channelId>  shown in the Golem plugin widget inside Roblox Studio.
+               Fresh on every Studio start.
+  --print      audit mode: fetch and print both files without writing anything.
+
+connect     link this folder to a Studio session (writes ./.golem/).
+reconnect   same, for a rotated token: replaces the old session files.
+            Use after a Studio restart, with the new line from the widget.
+disconnect  forget this session (removes ./.golem/). Studio is unaffected.
+
+connect writes ./.golem/golem.py and ./.golem/golem.md, fetched over HTTPS
+from your own Studio session. Review both files before running anything.`);
+}
+
+function fail(message, exitCode) {
+  console.error(`golem-bridge error: ${message}`);
+  process.exit(exitCode || 1);
+}
+
+function validateChannel(channelId) {
+  if (typeof channelId !== "string" || !CHANNEL_RE.test(channelId)) {
+    fail("bad channel ID (expect 8-64 hex characters — copy the full line from the Studio widget).", 2);
   }
-  return res.json();
+  return channelId;
 }
 
-async function getJson(url) {
-  const res = await fetch(url);
-  if (!res.ok) {
-    throw new Error(`GET ${url} failed: HTTP ${res.status}`);
+async function fetchText(url, body) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), FETCH_TIMEOUT_MS);
+  try {
+    const res = await fetch(url, {
+      method: body === undefined ? "GET" : "POST",
+      headers: { "Content-Type": "application/json" },
+      body,
+      signal: ctrl.signal,
+      redirect: "error", // never follow redirects: responses must come from the relay itself
+    });
+    if (!res.ok) {
+      throw new Error(`HTTP ${res.status} from the relay`);
+    }
+    const text = await res.text();
+    if (text.length > MAX_BODY_BYTES) {
+      throw new Error("relay response too large, refusing to parse it");
+    }
+    return text;
+  } catch (err) {
+    if (err && err.name === "AbortError") {
+      throw new Error("relay request timed out (30s)");
+    }
+    throw err;
+  } finally {
+    clearTimeout(timer);
   }
-  const text = await res.text();
+}
+
+async function postJson(url, body) {
+  const text = await fetchText(url, JSON.stringify(body));
+  return JSON.parse(text);
+}
+
+async function getJson(url) {
+  const text = await fetchText(url);
   return text === "null" ? null : JSON.parse(text);
 }
 
@@ -42,9 +104,20 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-async function fetchSetupResult(channelId) {
+function checkFileField(name, value) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`relay sent a bad setup payload (missing ${name})`);
+  }
+  if (value.length > MAX_FILE_BYTES) {
+    throw new Error(`relay sent a bad setup payload (${name} too large)`);
+  }
+  return value;
+}
+
+async function fetchSetupFiles(channelId) {
   const cmdId = `setup${Date.now()}${Math.floor(Math.random() * 1e6)}`;
-  await postJson(`${DB_URL}/channels/${channelId}/cmd.json`, {
+  const enc = encodeURIComponent(channelId);
+  await postJson(`${DB_URL}/channels/${enc}/cmd.json`, {
     id: cmdId,
     op: "setup",
     ts: Math.floor(Date.now() / 1000),
@@ -54,46 +127,112 @@ async function fetchSetupResult(channelId) {
     await sleep(POLL_INTERVAL_MS);
     let keys;
     try {
-      keys = await getJson(`${DB_URL}/channels/${channelId}/res.json?shallow=true`);
+      keys = await getJson(`${DB_URL}/channels/${enc}/res.json?shallow=true`);
     } catch {
       continue;
     }
     if (!keys) continue;
-    for (const key of Object.keys(keys).sort()) {
+    const sorted = Object.keys(keys).sort();
+    for (const key of sorted) {
+      if (typeof key !== "string" || key.length > 128) continue;
       let entry;
       try {
-        entry = await getJson(`${DB_URL}/channels/${channelId}/res/${key}.json`);
+        entry = await getJson(`${DB_URL}/channels/${enc}/res/${encodeURIComponent(key)}.json`);
       } catch {
         continue;
       }
-      if (entry && entry.id === cmdId) {
-        return entry;
+      if (!entry || entry.id !== cmdId) continue;
+      if (entry.ok !== true) {
+        throw new Error(`setup failed: ${entry.error || "unknown error"}`);
+      }
+      let result = entry.result;
+      if (entry.resultEncoded) {
+        if (typeof result !== "string") {
+          throw new Error("relay sent a bad setup payload (bad encoding flag)");
+        }
+        try {
+          result = JSON.parse(result);
+        } catch {
+          throw new Error("relay sent a bad setup payload (unparseable result)");
+        }
+      }
+      if (!result || typeof result !== "object") {
+        throw new Error("relay sent a bad setup payload (result is not an object)");
       }
+      return {
+        source: checkFileField("golem.py", result.source),
+        prompt: checkFileField("golem.md", result.prompt),
+        instructions:
+          typeof result.instructions === "string" && result.instructions.length > 0
+            ? result.instructions
+            : "Connected.",
+      };
     }
   }
   return null;
 }
 
-async function connect(channelId) {
-  if (!channelId || channelId.length < 8) {
-    usage();
+function sha256(text) {
+  return crypto.createHash("sha256").update(text, "utf8").digest("hex");
+}
+
+function readSavedChannel() {
+  try {
+    const src = fs.readFileSync(path.join(process.cwd(), ".golem", "golem.py"), "utf8");
+    const m = src.match(/CHANNEL = os\.environ\.get\("AIB_CHANNEL", "([0-9a-fA-F]+)"\)/);
+    return m ? m[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+function disconnectLocal() {
+  const dir = path.join(process.cwd(), ".golem");
+  if (!fs.existsSync(dir)) {
+    console.log("Not connected (no .golem/ in this folder).");
+    return;
   }
+  const old = readSavedChannel();
+  fs.rmSync(dir, { recursive: true, force: true });
+  console.log(old ? `Disconnected from channel ${old} (removed .golem/).` : "Disconnected (removed .golem/).");
+  console.log("Studio is unaffected. To link again: npx golem-bridge connect <channelId>");
+}
 
-  console.log(`Contacting Golem plugin on channel ${channelId} ...`);
-  const entry = await fetchSetupResult(channelId);
+async function reconnect(channelId, printOnly) {
+  validateChannel(channelId);
+  const old = readSavedChannel();
+  if (!printOnly && old && old.toLowerCase() === channelId.toLowerCase()) {
+    console.log(`Already linked to channel ${channelId} — nothing to do.`);
+    return;
+  }
+  if (!printOnly && old) {
+    console.log(`Replacing session files for channel ${old}.`);
+  }
+  await connect(channelId, printOnly);
+}
 
-  if (!entry) {
-    console.error("No response from the Studio plugin. Is Roblox Studio open with Golem running?");
-    process.exit(1);
+async function connect(channelId, printOnly) {
+  validateChannel(channelId);
+  console.log(`Contacting Golem plugin on channel ${channelId} ...`);
+  let files;
+  try {
+    files = await fetchSetupFiles(channelId);
+  } catch (err) {
+    fail(err.message, 1);
   }
-  if (!entry.ok) {
-    console.error(`Setup failed: ${entry.error || "unknown error"}`);
-    process.exit(1);
+
+  if (!files) {
+    fail("no response from the Studio plugin. Is Roblox Studio open with Golem running?", 1);
   }
 
-  let result = entry.result;
-  if (entry.resultEncoded) {
-    result = JSON.parse(result);
+  if (printOnly) {
+    console.log("===== golem.py (not written) =====");
+    console.log(files.source);
+    console.log("===== golem.md (not written) =====");
+    console.log(files.prompt);
+    console.log("===== connection note =====");
+    console.log(files.instructions);
+    return;
   }
 
   const dir = path.join(process.cwd(), ".golem");
@@ -101,27 +240,56 @@ async function connect(channelId) {
 
   const pyPath = path.join(dir, "golem.py");
   const mdPath = path.join(dir, "golem.md");
-  fs.writeFileSync(pyPath, result.source);
-  fs.writeFileSync(mdPath, result.prompt);
+  fs.writeFileSync(pyPath, files.source);
+  fs.writeFileSync(mdPath, files.prompt);
 
   console.log("");
-  console.log(result.instructions || "Connected.");
+  console.log(files.instructions);
   console.log("");
-  console.log(`Wrote ${path.relative(process.cwd(), pyPath)} and ${path.relative(process.cwd(), mdPath)}`);
+  console.log(
+    `Wrote ${path.relative(process.cwd(), pyPath)} (${files.source.length} bytes, sha256:${sha256(files.source).slice(0, 16)}...)`
+  );
+  console.log(
+    `Wrote ${path.relative(process.cwd(), mdPath)} (${files.prompt.length} bytes, sha256:${sha256(files.prompt).slice(0, 16)}...)`
+  );
+  console.log("These files were just downloaded from your Studio session — review them before running anything.");
   console.log(`Next: read ${path.relative(process.cwd(), mdPath)}, then run:`);
   console.log(`  python3 ${path.relative(process.cwd(), pyPath)} ping`);
 }
 
 async function main() {
-  const [cmd, arg] = process.argv.slice(2);
-  if (cmd !== "connect") {
-    usage();
+  const args = process.argv.slice(2);
+  if (args[0] === "--help" || args[0] === "-h" || args[0] === "help") {
+    printHelp();
+    return;
+  }
+  if (args[0] === "--version" || args[0] === "-V" || args[0] === "version") {
+    console.log(VERSION);
+    return;
+  }
+  if (args[0] === "disconnect") {
+    disconnectLocal();
+    return;
+  }
+  const isReconnect = args[0] === "reconnect";
+  if (args[0] !== "connect" && !isReconnect) {
+    printHelp();
+    process.exit(2);
+  }
+  const channelId = args[1];
+  const printOnly = args.includes("--print");
+  if (!channelId || channelId.startsWith("-")) {
+    printHelp();
+    process.exit(2);
   }
   try {
-    await connect(arg);
+    if (isReconnect) {
+      await reconnect(channelId, printOnly);
+    } else {
+      await connect(channelId, printOnly);
+    }
   } catch (err) {
-    console.error(`golem-bridge error: ${err.message}`);
-    process.exit(1);
+    fail(err.message, 1);
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "golem-bridge",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Connects an AI coding agent to a running Roblox Studio session via the Golem plugin.",
   "bin": {
     "golem-bridge": "./cli.js"