@emesoft/tokenhub 0.4.0 → 0.6.0

package/README.md

@@ -2,12 +2,16 @@
 
 Pair Claude Code on this machine with a [TokenHub](https://tokenhub.aimpact.io.vn) pool. No dependencies, Node 18+.
 
+`connect` pairs with https://tokenhub.aimpact.io.vn by default. For another pool, pass its address: `npx @emesoft/tokenhub connect https://pool.example.com`.
+
 ```
-npx @emesoft/tokenhub connect https://tokenhub.aimpact.io.vn
-npx @emesoft/tokenhub connect https://tokenhub.aimpact.io.vn --no-statusline
+npx @emesoft/tokenhub connect
+npx @emesoft/tokenhub connect --no-statusline
 npx @emesoft/tokenhub usage
 npx @emesoft/tokenhub dashboard
 npx @emesoft/tokenhub disconnect
+npx @emesoft/tokenhub connect --admin
+npx @emesoft/tokenhub disconnect --admin
 ```
 
 `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`). It also adds a `statusLine` that shows today's spend and credit under the Claude Code prompt (pass `--no-statusline` to skip it; a `statusLine` you already had is left alone). 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.
@@ -20,6 +24,8 @@ Requests to the pool carry your key and one extra header, `x-tokenhub-cli: <vers
 
 `disconnect` removes only those two entries and the TokenHub `statusLine`.
 
+`connect --admin` is for pool admins. It pairs this machine as an *admin device* for the TokenHub desktop overlay: you confirm the code on the pool's **admin** console (so only the signed-in admin can approve it), and the CLI saves a read-only device token to `~/.tokenhub/admin.json` (or `$TOKENHUB_CONFIG_DIR/admin.json`). It never touches Claude Code's settings. The token can read account names and quota levels, nothing else. Revoke a device on the admin Devices page (`/admin/pair`); `disconnect --admin` just forgets the token locally.
+
 If `ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN` or `ANTHROPIC_API_KEY` is set in your shell, it overrides `settings.json`.
 
-Sign in, manage your keys and top up at [tokenhub.aimpact.io.vn](https://tokenhub.aimpact.io.vn). The setup guide there has this command with your pool address filled in.
+Sign in, manage your keys and top up at [tokenhub.aimpact.io.vn](https://tokenhub.aimpact.io.vn).

package/bin/tokenhub.js

@@ -1,20 +1,26 @@
 #!/usr/bin/env node
 import { readFileSync } from "node:fs";
+import { adminConfigPath, removeAdminConfig } from "../lib/admin.js";
 import { parseDashboardArgs, runDashboard } from "../lib/dashboard.js";
-import { runConnect } from "../lib/pair.js";
+import { DEFAULT_POOL_URL, runConnect } from "../lib/pair.js";
 import { disconnectSettings, readSettings, settingsPath } from "../lib/settings.js";
 import { fetchUsage, formatUsage, resolveCredentials } from "../lib/usage.js";
 
 const HELP = `tokenhub - pair Claude Code with a TokenHub pool
 
 Usage:
-  tokenhub connect <poolUrl> [--no-statusline]
+  tokenhub connect [poolUrl] [--no-statusline]
                                Pair this machine and write ~/.claude/settings.json, including the status line
-                               (today's spend under the prompt) unless --no-statusline
+                               (today's spend under the prompt) unless --no-statusline.
+                               poolUrl defaults to ${DEFAULT_POOL_URL}
+  tokenhub connect [poolUrl] --admin
+                               Pair this machine as an admin device (for the desktop overlay's pool view): the admin
+                               confirms in the console, the token is saved to ~/.tokenhub/admin.json
   tokenhub usage [--json]      Show today's and this week's spend, credit and pool health
   tokenhub dashboard [--interval <sec>] [--once]
                                Live full-screen view of spend, pool health and recent requests (q quits)
   tokenhub disconnect          Remove the pool entries and the status line from settings.json
+  tokenhub disconnect --admin  Forget the admin device token on this machine (revoke it on the pool's admin Devices page)
   tokenhub --help | --version
 `;
 
@@ -38,19 +44,22 @@ async function main(argv) {
   }
   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, statusLine: !flags.includes("--no-statusline") });
+    return runConnect({
+      poolUrl: arg,
+      settingsFile: file,
+      signal: controller.signal,
+      statusLine: !flags.includes("--no-statusline"),
+      admin: flags.includes("--admin"),
+      adminFile: adminConfigPath(),
+    });
   }
   if (command === "usage") {
     try {
       const credentials = resolveCredentials(readSettings(file).settings);
       if (!credentials) {
-        console.error("Not connected. Run `tokenhub connect <poolUrl>` first.");
+        console.error("Not connected. Run `tokenhub connect` first.");
         return 1;
       }
       const report = await fetchUsage(credentials.baseUrl, credentials.key);
@@ -66,7 +75,7 @@ async function main(argv) {
       const options = parseDashboardArgs(argv.slice(1));
       const credentials = resolveCredentials(readSettings(file).settings);
       if (!credentials) {
-        console.error("Not connected. Run `tokenhub connect <poolUrl>` first.");
+        console.error("Not connected. Run `tokenhub connect` first.");
         return 1;
       }
       return await runDashboard(credentials, options);
@@ -77,6 +86,11 @@ async function main(argv) {
   }
   if (command === "disconnect") {
     try {
+      if (flags.includes("--admin")) {
+        const adminFile = adminConfigPath();
+        console.log(removeAdminConfig(adminFile) ? `Admin device forgotten. Removed ${adminFile}` : `Nothing to remove at ${adminFile}`);
+        return 0;
+      }
       console.log(disconnectSettings(file) ? `Disconnected. Updated ${file}` : `Nothing to remove in ${file}`);
       return 0;
     } catch (error) {

package/lib/admin.d.ts

@@ -0,0 +1,4 @@
+export function adminConfigPath(env?: Record<string, string | undefined>, home?: string): string;
+export function writeAdminConfig(file: string, baseUrl: string, token: string): void;
+export function readAdminConfig(file: string): { baseUrl: string; token: string } | null;
+export function removeAdminConfig(file: string): boolean;

package/lib/admin.js

@@ -0,0 +1,51 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+/**
+ * Locate the file `tokenhub connect --admin` stores the admin device token in (read by the desktop overlay).
+ * @param {Record<string, string | undefined>} [env] Environment to read TOKENHUB_CONFIG_DIR from.
+ * @param {string} [home] Home directory used when TOKENHUB_CONFIG_DIR is unset.
+ * @returns {string} Absolute path of admin.json.
+ */
+export function adminConfigPath(env = process.env, home = homedir()) {
+  return join(env.TOKENHUB_CONFIG_DIR || join(home, ".tokenhub"), "admin.json");
+}
+
+/**
+ * Store the pool address and admin device token, readable only by the current user where the OS supports it.
+ * @param {string} file Path from `adminConfigPath`.
+ * @param {string} baseUrl Pool address.
+ * @param {string} token Admin device token issued by the pool.
+ * @returns {void}
+ */
+export function writeAdminConfig(file, baseUrl, token) {
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, `${JSON.stringify({ baseUrl, token }, null, 2)}\n`, { mode: 0o600 });
+}
+
+/**
+ * Read a stored admin device.
+ * @param {string} file Path from `adminConfigPath`.
+ * @returns {{ baseUrl: string, token: string } | null} The pair, or null when missing or unusable.
+ */
+export function readAdminConfig(file) {
+  if (!existsSync(file)) return null;
+  try {
+    const { baseUrl, token } = JSON.parse(readFileSync(file, "utf8"));
+    return typeof baseUrl === "string" && typeof token === "string" && baseUrl && token ? { baseUrl, token } : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Forget the stored admin device (the token stays valid on the pool until revoked on its Devices page).
+ * @param {string} file Path from `adminConfigPath`.
+ * @returns {boolean} Whether a file was removed.
+ */
+export function removeAdminConfig(file) {
+  if (!existsSync(file)) return false;
+  rmSync(file);
+  return true;
+}

package/lib/pair.d.ts

@@ -1,6 +1,8 @@
+export const DEFAULT_POOL_URL: string;
 export function openBrowser(url: string, platform?: string): void;
 export function runConnect(options: {
-  poolUrl: string;
+  /** Pool address; defaults to `DEFAULT_POOL_URL`. */
+  poolUrl?: string;
   settingsFile: string;
   log?: (line: string) => void;
   open?: (url: string) => void;
@@ -9,4 +11,8 @@ export function runConnect(options: {
   intervalOverrideMs?: number;
   env?: Record<string, string | undefined>;
   statusLine?: boolean;
+  /** Pair as an admin device (token goes to `adminFile`, not settings.json). */
+  admin?: boolean;
+  /** Where the admin device token is stored; required with `admin`. */
+  adminFile?: string;
 }): Promise<number>;

package/lib/pair.js

@@ -1,9 +1,13 @@
 import { spawn } from "node:child_process";
 import { hostname } from "node:os";
+import { writeAdminConfig } from "./admin.js";
 import { connectSettings, normalizeUrl, overridingEnvVars, readSettings } from "./settings.js";
 
 const MAX_WAIT_MS = 15 * 60 * 1000;
 
+/** The pool `connect` pairs with when no address is given. */
+export const DEFAULT_POOL_URL = "https://tokenhub.aimpact.io.vn";
+
 /**
  * Open a URL in the default browser; failures are ignored (the URL is printed anyway).
  * @param {string} url Address to open.
@@ -61,7 +65,7 @@ async function postJson(url, body, signal) {
 /**
  * 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.poolUrl] Pool address as typed by the user (default `DEFAULT_POOL_URL`).
  * @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.
@@ -70,10 +74,12 @@ async function postJson(url, body, signal) {
  * @param {number} [options.intervalOverrideMs] Poll interval override (tests).
  * @param {Record<string, string | undefined>} [options.env] Environment inspected for overriding variables.
  * @param {boolean} [options.statusLine] Also install the TokenHub status line (default true).
+ * @param {boolean} [options.admin] Pair as an admin device: the admin approves in the console and the token is stored in `adminFile` (for the desktop overlay), leaving Claude Code's settings alone.
+ * @param {string} [options.adminFile] Path from `adminConfigPath`; required with `admin`.
  * @returns {Promise<number>} Process exit code.
  */
 export async function runConnect({
-  poolUrl,
+  poolUrl = DEFAULT_POOL_URL,
   settingsFile,
   log = console.log,
   open = openBrowser,
@@ -82,17 +88,19 @@ export async function runConnect({
   intervalOverrideMs,
   env = process.env,
   statusLine = true,
+  admin = false,
+  adminFile,
 }) {
   let pool;
   try {
     pool = normalizeUrl(poolUrl);
-    readSettings(settingsFile);
+    if (!admin) readSettings(settingsFile);
   } catch (error) {
     log(`Error: ${error.message}`);
     return 1;
   }
   try {
-    const start = await postJson(`${pool}/pair/start`, { deviceName }, signal);
+    const start = await postJson(`${pool}/pair/start`, admin ? { deviceName, kind: "admin" } : { deviceName }, signal);
     if (start.status === 429) {
       log("Too many pairing attempts. Wait a few minutes and try again.");
       return 1;
@@ -105,7 +113,7 @@ export async function runConnect({
     log("");
     log(`  Your code:  ${userCode}`);
     log("");
-    log(`Confirm it at: ${verifyUrl}`);
+    log(`Confirm it at: ${verifyUrl}${admin ? " (sign in as the admin)" : ""}`);
     log("Opening your browser. Waiting for approval (Ctrl+C to cancel)...");
     open(verifyUrl);
 
@@ -120,6 +128,16 @@ export async function runConnect({
       const poll = await postJson(`${pool}/pair/poll`, { deviceCode }, signal);
       if (poll.status === 429) continue;
       const status = poll.body?.status;
+      if (status === "approved" && admin) {
+        if (poll.body.kind !== "admin") {
+          log("Error: the pool did not issue an admin device token. Update the pool, then run the command again.");
+          return 1;
+        }
+        writeAdminConfig(adminFile, poll.body.baseUrl, poll.body.key);
+        log(`Admin device paired. Token saved to ${adminFile}`);
+        log(`Revoke it any time on the pool's admin Devices page (${poll.body.baseUrl}/admin/pair).`);
+        return 0;
+      }
       if (status === "approved") {
         const statusResult = connectSettings(settingsFile, poll.body.baseUrl, poll.body.key, { statusLine });
         log(`Connected. Claude Code settings updated: ${settingsFile}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emesoft/tokenhub",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Pair Claude Code on this machine with a TokenHub pool",
   "type": "module",
   "bin": {