@emesoft/tokenhub 0.1.0

package/README.md

@@ -0,0 +1,14 @@
+# @emesoft/tokenhub
+
+Pair Claude Code on this machine with a TokenHub pool. No dependencies, Node 18+.
+
+```
+npx @emesoft/tokenhub connect https://pool.example.com
+npx @emesoft/tokenhub disconnect
+```
+
+`connect` prints a short code and opens your browser. Confirm the code on the pool's member site and the CLI writes `ANTHROPIC_BASE_URL` and `ANTHROPIC_AUTH_TOKEN` into `~/.claude/settings.json` (or `$CLAUDE_CONFIG_DIR/settings.json`). Other settings are kept, and the previous file is saved as `settings.json.bak`. Each paired machine gets its own key, which you can revoke on the Keys page.
+
+`disconnect` removes only those two entries.
+
+If `ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN` or `ANTHROPIC_API_KEY` is set in your shell, it overrides `settings.json`.

package/bin/tokenhub.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { runConnect } from "../lib/pair.js";
+import { disconnectSettings, settingsPath } from "../lib/settings.js";
+
+const HELP = `tokenhub - pair Claude Code with a TokenHub pool
+
+Usage:
+  tokenhub connect <poolUrl>   Pair this machine and write ~/.claude/settings.json
+  tokenhub disconnect          Remove the pool entries from settings.json
+  tokenhub --help | --version
+`;
+
+/**
+ * CLI entry point.
+ * @param {string[]} argv Arguments after the script name.
+ * @returns {Promise<number>} Process exit code.
+ */
+async function main(argv) {
+  const [command, arg] = argv;
+  if (!command || command === "--help" || command === "-h" || command === "help") {
+    console.log(HELP);
+    return command ? 0 : 1;
+  }
+  if (command === "--version" || command === "-v") {
+    const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    console.log(pkg.version);
+    return 0;
+  }
+  const file = settingsPath();
+  if (command === "connect") {
+    if (!arg) {
+      console.error(`Missing pool URL.\n\n${HELP}`);
+      return 1;
+    }
+    const controller = new AbortController();
+    process.once("SIGINT", () => controller.abort());
+    return runConnect({ poolUrl: arg, settingsFile: file, signal: controller.signal });
+  }
+  if (command === "disconnect") {
+    try {
+      console.log(disconnectSettings(file) ? `Disconnected. Updated ${file}` : `Nothing to remove in ${file}`);
+      return 0;
+    } catch (error) {
+      console.error(`Error: ${error.message}`);
+      return 1;
+    }
+  }
+  console.error(`Unknown command: ${command}\n\n${HELP}`);
+  return 1;
+}
+
+process.exitCode = await main(process.argv.slice(2));

package/lib/pair.d.ts

@@ -0,0 +1,11 @@
+export function openBrowser(url: string, platform?: string): void;
+export function runConnect(options: {
+  poolUrl: string;
+  settingsFile: string;
+  log?: (line: string) => void;
+  open?: (url: string) => void;
+  signal?: AbortSignal;
+  deviceName?: string;
+  intervalOverrideMs?: number;
+  env?: Record<string, string | undefined>;
+}): Promise<number>;

package/lib/pair.js

@@ -0,0 +1,149 @@
+import { spawn } from "node:child_process";
+import { hostname } from "node:os";
+import { connectSettings, normalizeUrl, overridingEnvVars, readSettings } from "./settings.js";
+
+const MAX_WAIT_MS = 15 * 60 * 1000;
+
+/**
+ * Open a URL in the default browser; failures are ignored (the URL is printed anyway).
+ * @param {string} url Address to open.
+ * @param {string} [platform] Node platform name.
+ * @returns {void}
+ */
+export function openBrowser(url, platform = process.platform) {
+  const [command, args] =
+    platform === "win32" ? ["cmd", ["/c", "start", '""', url]] : platform === "darwin" ? ["open", [url]] : ["xdg-open", [url]];
+  try {
+    const child = spawn(command, args, { stdio: "ignore", detached: true, windowsVerbatimArguments: platform === "win32" });
+    child.on("error", () => {});
+    child.unref();
+  } catch {
+    // no browser available; the URL was already printed
+  }
+}
+
+/**
+ * Sleep that resolves early when the signal aborts.
+ * @param {number} ms Duration in milliseconds.
+ * @param {AbortSignal} [signal] Cancels the wait.
+ * @returns {Promise<void>}
+ */
+function sleep(ms, signal) {
+  return new Promise((resolve) => {
+    if (signal?.aborted) return resolve();
+    const timer = setTimeout(done, ms);
+    function done() {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", done);
+      resolve();
+    }
+    signal?.addEventListener("abort", done);
+  });
+}
+
+/**
+ * POST JSON to the pool and parse the reply.
+ * @param {string} url Endpoint URL.
+ * @param {object} body JSON payload.
+ * @param {AbortSignal} [signal] Cancels the request.
+ * @returns {Promise<{ status: number, body: any }>} HTTP status and parsed JSON (null when not JSON).
+ */
+async function postJson(url, body, signal) {
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+    signal,
+  });
+  return { status: res.status, body: await res.json().catch(() => null) };
+}
+
+/**
+ * Run the pairing flow and write the issued key into settings.json.
+ * @param {object} options
+ * @param {string} options.poolUrl Pool address as typed by the user.
+ * @param {string} options.settingsFile Path of settings.json to update.
+ * @param {(line: string) => void} [options.log] Output sink.
+ * @param {(url: string) => void} [options.open] Browser opener.
+ * @param {AbortSignal} [options.signal] Aborts the flow (Ctrl+C).
+ * @param {string} [options.deviceName] Name shown on the confirmation page.
+ * @param {number} [options.intervalOverrideMs] Poll interval override (tests).
+ * @param {Record<string, string | undefined>} [options.env] Environment inspected for overriding variables.
+ * @returns {Promise<number>} Process exit code.
+ */
+export async function runConnect({
+  poolUrl,
+  settingsFile,
+  log = console.log,
+  open = openBrowser,
+  signal,
+  deviceName = hostname(),
+  intervalOverrideMs,
+  env = process.env,
+}) {
+  let pool;
+  try {
+    pool = normalizeUrl(poolUrl);
+    readSettings(settingsFile);
+  } catch (error) {
+    log(`Error: ${error.message}`);
+    return 1;
+  }
+  try {
+    const start = await postJson(`${pool}/pair/start`, { deviceName }, signal);
+    if (start.status === 429) {
+      log("Too many pairing attempts. Wait a few minutes and try again.");
+      return 1;
+    }
+    if (start.status !== 200 || !start.body?.deviceCode) {
+      log(`Error: the pool rejected the pairing request (HTTP ${start.status}).`);
+      return 1;
+    }
+    const { deviceCode, userCode, verifyUrl, interval, expiresIn } = start.body;
+    log("");
+    log(`  Your code:  ${userCode}`);
+    log("");
+    log(`Confirm it at: ${verifyUrl}`);
+    log("Opening your browser. Waiting for approval (Ctrl+C to cancel)...");
+    open(verifyUrl);
+
+    const intervalMs = intervalOverrideMs ?? Math.max(1, Number(interval) || 3) * 1000;
+    const deadline = Date.now() + Math.min(MAX_WAIT_MS, (Number(expiresIn) || 600) * 1000 + intervalMs);
+    while (Date.now() < deadline) {
+      await sleep(intervalMs, signal);
+      if (signal?.aborted) {
+        log("Cancelled.");
+        return 130;
+      }
+      const poll = await postJson(`${pool}/pair/poll`, { deviceCode }, signal);
+      if (poll.status === 429) continue;
+      const status = poll.body?.status;
+      if (status === "approved") {
+        connectSettings(settingsFile, poll.body.baseUrl, poll.body.key);
+        log(`Connected. Claude Code settings updated: ${settingsFile}`);
+        const overriding = overridingEnvVars(env);
+        if (overriding.length > 0) {
+          log(`Warning: ${overriding.join(", ")} set in your shell overrides settings.json. Unset it to use the pool.`);
+        }
+        return 0;
+      }
+      if (status === "denied") {
+        log("The request was denied.");
+        return 1;
+      }
+      if (status === "expired") {
+        log("The code expired. Run the command again.");
+        return 1;
+      }
+    }
+    log("Timed out waiting for approval. Run the command again.");
+    return 1;
+  } catch (error) {
+    if (signal?.aborted) {
+      log("Cancelled.");
+      return 130;
+    }
+    log(`Error: ${error.message}`);
+    return 1;
+  }
+}

package/lib/settings.d.ts

@@ -0,0 +1,9 @@
+export function settingsPath(env?: Record<string, string | undefined>, home?: string): string;
+export function normalizeUrl(input: string): string;
+export function mergeSettings(settings: Record<string, any>, baseUrl: string, key: string): Record<string, any>;
+export function removeSettings(settings: Record<string, any>): Record<string, any>;
+export function overridingEnvVars(env?: Record<string, string | undefined>): string[];
+export function readSettings(file: string): { exists: boolean; settings: Record<string, any> };
+export function writeSettings(file: string, settings: Record<string, any>): void;
+export function connectSettings(file: string, baseUrl: string, key: string): void;
+export function disconnectSettings(file: string): boolean;

package/lib/settings.js

@@ -0,0 +1,139 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+const BASE_URL_KEY = "ANTHROPIC_BASE_URL";
+const TOKEN_KEY = "ANTHROPIC_AUTH_TOKEN";
+
+/**
+ * Locate Claude Code's user settings file.
+ * @param {Record<string, string | undefined>} [env] Environment to read CLAUDE_CONFIG_DIR from.
+ * @param {string} [home] Home directory used when CLAUDE_CONFIG_DIR is unset.
+ * @returns {string} Absolute path of settings.json.
+ */
+export function settingsPath(env = process.env, home = homedir()) {
+  const dir = env.CLAUDE_CONFIG_DIR || join(home, ".claude");
+  return join(dir, "settings.json");
+}
+
+/**
+ * Normalize a pool URL: require http/https, drop trailing slashes, query and hash.
+ * @param {string} input Raw URL typed by the user.
+ * @returns {string} Origin plus path without a trailing slash.
+ * @throws {Error} When the URL is invalid or not http/https.
+ */
+export function normalizeUrl(input) {
+  let url;
+  try {
+    url = new URL(String(input).trim());
+  } catch {
+    throw new Error(`Invalid pool URL: ${input}`);
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error(`Pool URL must start with http:// or https://: ${input}`);
+  }
+  return `${url.origin}${url.pathname}`.replace(/\/+$/, "");
+}
+
+/**
+ * Return a copy of the settings with the pool connection set in `env`.
+ * @param {Record<string, any>} settings Existing settings object.
+ * @param {string} baseUrl Value for ANTHROPIC_BASE_URL.
+ * @param {string} key Value for ANTHROPIC_AUTH_TOKEN.
+ * @returns {Record<string, any>} New settings; all other keys are preserved.
+ */
+export function mergeSettings(settings, baseUrl, key) {
+  const env = isPlainObject(settings.env) ? settings.env : {};
+  return { ...settings, env: { ...env, [BASE_URL_KEY]: baseUrl, [TOKEN_KEY]: key } };
+}
+
+/**
+ * Return a copy of the settings without the pool connection entries.
+ * @param {Record<string, any>} settings Existing settings object.
+ * @returns {Record<string, any>} New settings; `env` is dropped when it ends up empty.
+ */
+export function removeSettings(settings) {
+  const { env, ...rest } = settings;
+  if (!isPlainObject(env)) return { ...settings };
+  const { [BASE_URL_KEY]: _url, [TOKEN_KEY]: _token, ...otherEnv } = env;
+  return Object.keys(otherEnv).length > 0 ? { ...rest, env: otherEnv } : rest;
+}
+
+/**
+ * Shell variables that take precedence over settings.json.
+ * @param {Record<string, string | undefined>} [env] Environment to inspect.
+ * @returns {string[]} Names of the overriding variables that are set.
+ */
+export function overridingEnvVars(env = process.env) {
+  return [BASE_URL_KEY, TOKEN_KEY, "ANTHROPIC_API_KEY"].filter((name) => env[name]);
+}
+
+/**
+ * Read and parse a settings file.
+ * @param {string} file Path of settings.json.
+ * @returns {{ exists: boolean, settings: Record<string, any> }} Parsed settings ({} when the file is missing).
+ * @throws {Error} When the file exists but is not a JSON object.
+ */
+export function readSettings(file) {
+  if (!existsSync(file)) return { exists: false, settings: {} };
+  const text = readFileSync(file, "utf8");
+  if (text.trim() === "") return { exists: true, settings: {} };
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new Error(`${file} is not valid JSON. Fix or remove it, then run again.`);
+  }
+  if (!isPlainObject(parsed)) {
+    throw new Error(`${file} does not contain a JSON object. Fix or remove it, then run again.`);
+  }
+  return { exists: true, settings: parsed };
+}
+
+/**
+ * Write settings, creating the directory and a `.bak` copy of any existing file.
+ * @param {string} file Path of settings.json.
+ * @param {Record<string, any>} settings Settings to persist.
+ * @returns {void}
+ */
+export function writeSettings(file, settings) {
+  mkdirSync(dirname(file), { recursive: true });
+  if (existsSync(file)) copyFileSync(file, `${file}.bak`);
+  writeFileSync(file, `${JSON.stringify(settings, null, 2)}\n`);
+}
+
+/**
+ * Persist a pool connection into the settings file.
+ * @param {string} file Path of settings.json.
+ * @param {string} baseUrl Value for ANTHROPIC_BASE_URL.
+ * @param {string} key Value for ANTHROPIC_AUTH_TOKEN.
+ * @returns {void}
+ * @throws {Error} When the existing file is invalid JSON (left untouched).
+ */
+export function connectSettings(file, baseUrl, key) {
+  const { settings } = readSettings(file);
+  writeSettings(file, mergeSettings(settings, baseUrl, key));
+}
+
+/**
+ * Remove the pool connection from the settings file.
+ * @param {string} file Path of settings.json.
+ * @returns {boolean} True when the file changed, false when there was nothing to remove.
+ * @throws {Error} When the existing file is invalid JSON (left untouched).
+ */
+export function disconnectSettings(file) {
+  const { exists, settings } = readSettings(file);
+  if (!exists) return false;
+  const next = removeSettings(settings);
+  if (JSON.stringify(next) === JSON.stringify(settings)) return false;
+  writeSettings(file, next);
+  return true;
+}
+
+/**
+ * @param {unknown} value Value to test.
+ * @returns {value is Record<string, any>} True for non-null, non-array objects.
+ */
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@emesoft/tokenhub",
+  "version": "0.1.0",
+  "description": "Pair Claude Code on this machine with a TokenHub pool",
+  "type": "module",
+  "bin": {
+    "tokenhub": "bin/tokenhub.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "UNLICENSED"
+}