@super-hands/connect 0.1.17 → 0.1.18

package/README.md

@@ -3,12 +3,20 @@
 Connect the coding agents on this machine to your team's
 [Superhands](https://app.superhands.ai) MCP server, in one command.
 
-Superhands setup generates the command for you, credential included:
+Superhands generates the command for you, with a short-lived setup code on
+the end of it:
 
 ```
-SUPERHANDS_MCP_TOKEN="…" npx -y @super-hands/connect@latest
+npx -y @super-hands/connect@latest --code shsetup_…
 ```
 
+The client exchanges that code for the credential over one request to your
+deployment and writes the credential into the clients below. The code is
+worth nothing twenty minutes later; the token it becomes never appears in the
+command, the prompt you pasted it from, or your shell history. A command
+written by hand around a token from the Agents page still works:
+`SUPERHANDS_MCP_TOKEN="…" npx -y @super-hands/connect@latest`.
+
 It connects to `https://app.superhands.ai/api/mcp` unless `SUPERHANDS_MCP_URL`
 says otherwise — a command from a preview or local deployment carries that
 variable too.
@@ -71,10 +79,11 @@ remove one client and leave the rest.
 
 ## What it does not do
 
-It reads no repository, runs none of your code, and uploads nothing. The one
-secret it holds is the token in its own environment, and it is written only
-into the client configs above. The token can be revoked at any time from the
-Superhands MCP page.
+It reads no repository, runs none of your code, and uploads nothing but the
+setup code it was given, once, to the deployment that issued it. The one
+secret it then holds is the token that came back, and it is written only into
+the client configs above. The token can be revoked at any time from the
+Superhands Agents page.
 
 This file is generated from
 [`lib/connect-client-entry.ts`](https://github.com/superhandsai/superhands/blob/main/lib/connect-client-entry.ts)

package/client.mjs

@@ -21,6 +21,7 @@ var MCP_ACCESS_TOKEN_TTL_SECONDS = 30 * 24 * 60 * 60;
 // lib/mcp-clients.ts
 var CONNECT_TOKEN_ENV = "SUPERHANDS_MCP_TOKEN";
 var CONNECT_URL_ENV = "SUPERHANDS_MCP_URL";
+var CONNECT_CODE_FLAG = "--code";
 var CONNECT_DEFAULT_MCP_URL = "https://app.superhands.ai/api/mcp";
 var CONNECT_CLIENT_PACKAGE = "@super-hands/connect";
 var CONNECT_CLIENT_SPEC = `${CONNECT_CLIENT_PACKAGE}@latest`;
@@ -328,6 +329,59 @@ function writeSkill(clientDir) {
 function connectReportUrl(endpoint) {
   return `${endpoint.replace(/\/+$/, "")}/connect`;
 }
+function connectExchangeUrl(endpoint) {
+  return `${connectReportUrl(endpoint)}/exchange`;
+}
+function takeCodeArgument(argv) {
+  const rest = [];
+  let code = null;
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === CONNECT_CODE_FLAG) {
+      const next = argv[i + 1];
+      if (next !== void 0 && !next.startsWith("--")) {
+        code = next;
+        i += 1;
+      } else {
+        code = "";
+      }
+      continue;
+    }
+    if (arg.startsWith(`${CONNECT_CODE_FLAG}=`)) {
+      code = arg.slice(CONNECT_CODE_FLAG.length + 1);
+      continue;
+    }
+    rest.push(arg);
+  }
+  return { code, rest };
+}
+async function exchangeSetupCode(args) {
+  let response;
+  try {
+    response = await fetch(connectExchangeUrl(args.endpoint), {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ code: args.code }),
+      signal: AbortSignal.timeout(1e4)
+    });
+  } catch {
+    return stop(
+      `Superhands at ${args.endpoint} could not be reached to turn the setup code into a credential. Check the connection and run this command again.`
+    );
+  }
+  const body = await response.json().catch(() => null);
+  if (response.ok && body?.ok && typeof body.token === "string" && body.token) {
+    return body.token;
+  }
+  if (response.status === 401 || response.status === 400) {
+    return stop(
+      "this setup code has expired or has been used up. Get a fresh command from Superhands and run it unchanged."
+    );
+  }
+  return stop(
+    `Superhands answered ${response.status} to the setup code. Try again in a moment, or get a fresh command from Superhands.`
+  );
+}
 async function reportSkillVersion(args) {
   try {
     await fetch(connectReportUrl(args.endpoint), {
@@ -427,7 +481,7 @@ function chosenClients(flags) {
   return explicit ? { cursor, claude, codex, explicit } : { cursor: true, claude: true, codex: true, explicit };
 }
 async function main() {
-  const argv = process.argv.slice(2);
+  const { code, rest: argv } = takeCodeArgument(process.argv.slice(2));
   const flags = new Set(argv.filter((arg) => arg.startsWith("--")));
   const command = argv.find((arg) => !arg.startsWith("--")) ?? "install";
   if (command === "uninstall") return uninstall(flags);
@@ -437,14 +491,19 @@ async function main() {
       `unknown command "${command}". This tool takes "install" (the default), "update" or "uninstall".`
     );
   }
-  return install(flags);
+  return install(flags, code);
 }
-async function install(flags) {
-  const token = process.env[CONNECT_TOKEN_ENV]?.trim();
+async function install(flags, code) {
   const endpoint = process.env[CONNECT_URL_ENV]?.trim() || CONNECT_DEFAULT_MCP_URL;
+  if (code === "") {
+    stop(
+      `${CONNECT_CODE_FLAG} needs the setup code after it. Copy the whole command from Superhands and run it unchanged.`
+    );
+  }
+  const token = code ? await exchangeSetupCode({ endpoint, code }) : process.env[CONNECT_TOKEN_ENV]?.trim();
   if (!token) {
     stop(
-      `this command needs ${CONNECT_TOKEN_ENV} set on the same line. Copy the whole command from Superhands setup and run it unchanged.`
+      `this command needs a setup code after ${CONNECT_CODE_FLAG}, or ${CONNECT_TOKEN_ENV} set on the same line. Copy the whole command from Superhands and run it unchanged.`
     );
   }
   const wanted = chosenClients(flags);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@super-hands/connect",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "description": "Connect the coding agents on this machine to your team's Superhands MCP server, refresh it later with `update` (no token needed), and take it back off again with `uninstall`. Writes each client's own config; reads no repository, uploads nothing.",
   "bin": {
     "superhands-connect": "client.mjs"