@claw-link/gateway-host 0.2.4 → 0.2.6

package/README.md

@@ -64,13 +64,14 @@ tool's own settings).
 **Permissions by scope** — each job carries a scope, and the Claude adapter runs with
 matching permissions automatically:
 
-| Trigger | Scope | Claude permissions |
-|---------|-------|--------------------|
-| Admin **Setup via Chat** / apply skill | `configure` | `--permission-mode acceptEdits` — may write workspace files (GUARDRAILS/SOUL/BOOTSTRAP/TOOLS/AGENTS) |
-| Customer chat + discovery | `customer` | `--disallowedTools "Write Edit MultiEdit NotebookEdit Bash"` — **read-only**, cannot edit config or run shell |
+| Trigger | Scope | Claude | Codex |
+|---------|-------|--------|-------|
+| Admin **Setup via Chat** / apply skill | `configure` | `--permission-mode acceptEdits` (may write workspace files) | `--sandbox workspace-write --ask-for-approval never` |
+| Customer chat + discovery | `customer` | `--disallowedTools "Write Edit MultiEdit NotebookEdit Bash"` (**read-only**) | `--sandbox read-only --ask-for-approval never` |
 
 So an agent's files are editable from the admin panel but never from customer/discovery
-chat. (Operator `args_template` overrides this for advanced setups.)
+chat. (Operator `args_template` overrides this for advanced setups. Hermes/Cursor/OpenClaw
+manage their own permissions.)
 
 ## Commands
 
@@ -80,6 +81,7 @@ After install the `clhost` command is available (aliases: `gateway-host`, `claw-
 clhost install      # install the background service (one-time)
 clhost add-agent    # add an agent by pasting its Host Token
 clhost rm-agent <id># remove a mapped agent
+clhost retoken <id> # re-enter a new token after rotating (keeps workspace/binary)
 clhost agents       # list mapped agents
 clhost status       # bridge + service state + mapped agents
 clhost start        # start the background service
@@ -111,11 +113,18 @@ cached back in). `~/.clawlink-host/config.json` (chmod 600):
 }
 ```
 
+## Platforms
+
+macOS (launchd), Linux (systemd user service), and **Windows** (a hidden, auto-restarting
+Scheduled Task; logs to `%USERPROFILE%\.clawlink-host\host.log`). On Windows the worker
+handles npm `.cmd` CLI shims automatically; for the strongest isolation prefer Claude
+(prompt via stdin) or a native `.exe` runtime.
+
 ## Security
 
-Outbound-only, per-agent token (stored server-side as a hash only), **machine-bound**
-on first connect (a stolen token fails from any other host), no shell injection, runs
-only the configured binary. See [SECURITY.md](./SECURITY.md).
+Outbound-only, per-agent token (stored server-side as a hash only), **machine-bound** on
+first connect to a **stable hardware id** (a stolen token fails from any other host), no
+shell injection, runs only the configured binary. See [SECURITY.md](./SECURITY.md).
 
 ---
 

package/SECURITY.md

@@ -12,18 +12,25 @@ a secret, never run an attacker-controlled command, never open a port.
    exactly one `agent_id`. Rotate any time from the dashboard (the old token dies
    immediately).
 2. **Machine binding** — on first connect the worker sends a **hash** of the host's
-   machine fingerprint (MAC address(es) + hostname); ClawLink binds the agent to that
-   machine. Every later call must present the same fingerprint, so a stolen token is
-   rejected from any other host. Only the hash is sent — raw MACs never leave the
-   machine. Rotating the token clears the binding (also how you move to a new host).
-   (A MAC can be spoofed by an attacker who *also* learns it, so treat this as a strong
-   second factor on top of the token, not a replacement.)
+   **stable hardware machine id** (macOS `IOPlatformUUID`, Linux `/etc/machine-id`,
+   Windows `MachineGuid`; a persisted random id as fallback); ClawLink binds the agent
+   to that machine. Every later call must present the same id, so a stolen token is
+   rejected from any other host. Only the hash is sent — the raw id never leaves the
+   machine. The id is **stable across reboots, network changes, and version upgrades**
+   (earlier builds hashed MAC addresses, which rotate and caused false mismatches).
+   Rotating the token clears the binding (also how you move to a new host). Treat this
+   as a strong second factor on top of the token, not a replacement.
 3. **Outbound-only** — the worker **dials out** to the `host-bridge` HTTPS endpoint
    and short-polls for work. It opens **no inbound port**, needs **no Tailscale
    Funnel**, and works behind NAT. There is nothing to attack from the network.
-4. **No shell injection** — every CLI is launched with `child_process.spawn(binary,
-   argvArray, { shell: false })`. Untrusted prompt text is passed as a single argv
-   token or via stdin — it is **never** concatenated into a command string.
+4. **No shell injection** — on macOS/Linux every CLI is launched with
+   `child_process.spawn(binary, argvArray, { shell: false })`; untrusted prompt text is
+   a single argv token or comes via stdin — **never** concatenated into a command
+   string. On Windows, npm CLI shims are `.cmd`/`.bat` files that Node can only spawn
+   through the shell, so those go through `cmd.exe` with Node's hardened argument
+   escaping; native `.exe` runtimes still use `shell: false`. For Windows, prefer a
+   runtime that reads the prompt via **stdin** (Claude) or a native `.exe` so untrusted
+   text never enters a Windows command line.
 5. **No arbitrary command execution** — the worker runs **only** the runtime binary
    you configured. The job payload it receives carries `{ content, system_prompt,
    attachments, session }` — it is structurally incapable of carrying a command, and

package/bin/cli.js

@@ -27,6 +27,11 @@ async function main() {
     case 'rm':
       return require('../scripts/install').removeAgentCmd();
 
+    case 'retoken':
+    case 're-token':
+    case 'update-token':
+      return require('../scripts/install').retokenCmd();
+
     case 'agents':
     case 'list':
       return require('../scripts/install').listAgents();
@@ -48,7 +53,8 @@ async function main() {
         'To rotate a Host Token (also how you move an agent to a new machine):',
         '  1. ClawLink → Agents → your agent → Host Gateway → "Rotate token"',
         '     (this clears the machine binding so a new host can claim it).',
-        '  2. Copy the new token, then run: clhost add-agent',
+        '  2. Copy the new token, then run: clhost retoken <id>',
+        '     (keeps the agent\'s workspace/binary; or `clhost add-agent` for a new one).',
         '     The old token + old machine stop working immediately.',
       ].join('\n'));
       return;
@@ -63,6 +69,7 @@ async function main() {
         '  install     Install the background service (one-time)',
         '  add-agent   Add an agent by pasting its Host Token (pulls runtime from ClawLink)',
         '  rm-agent    Remove a mapped agent (clhost rm-agent <id>)',
+        '  retoken     Re-enter a new Host Token for an existing agent (clhost retoken <id>)',
         '  agents      List mapped agents',
         '  status      Show bridge, service state, and mapped agents',
         '  start       Start the background service',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claw-link/gateway-host",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "ClawLink Host Gateway — a secure, outbound-only worker that bridges a local agent CLI (OpenClaw, Hermes, Claude, Codex, Cursor) to your ClawLink agents. No inbound ports; authenticated per-agent by a Host Token.",
   "homepage": "https://claw-link.co",
   "bin": {

package/scripts/install.js

@@ -175,11 +175,54 @@ function printAgents(cfg) {
     const tok = a.host_token ? `…${String(a.host_token).slice(-4)}` : '—';
     console.log(`    • ${id}…  runtime=${a.runtime || 'pull'}  token=${tok}` + (a.work_dir ? `  work=${a.work_dir}` : ''));
   }
+  console.log('\n  Update a token after rotating it:  clhost retoken <id>');
 }
 
 // `agents` — list mapped agents.
 function listAgents() { printAgents(config.load() || {}); }
 
+// `retoken [id-or-prefix]` — re-enter a new Host Token for an EXISTING agent after
+// rotating it in the dashboard, keeping the same work_dir/binary/runtime. The new
+// token must resolve to the same agent_id; re-binds this machine on verify.
+async function retokenCmd() {
+  const cfg = config.load();
+  if (!cfg || !(cfg.agents || []).length) { console.log('No agents configured. Run: clhost add-agent'); return; }
+  ensureBridgeUrl(cfg);
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    let target = (process.argv[3] || '').trim();
+    if (!target && cfg.agents.length === 1) target = cfg.agents[0].agent_id || '';
+    if (!target) { printAgents(cfg); target = await ask(rl, '\n  Agent ID (or prefix) to re-token'); }
+    if (!target) { console.log('  (cancelled)'); return; }
+    const agent = cfg.agents.find((a) => a.agent_id && (a.agent_id === target || a.agent_id.startsWith(target)));
+    if (!agent) { console.log(`  No agent matched '${target}'.`); return; }
+
+    const token = await ask(rl, `  New Host Token for ${String(agent.agent_id).slice(0, 8)}… (clk_host_…)`);
+    if (!token) { console.log('  (cancelled)'); return; }
+
+    console.log('  Verifying new token + binding this machine…');
+    let resp;
+    try {
+      resp = await new Bridge(cfg.bridge_url, { host_token: token }, cfg.instance_id).register(null, VERSION);
+    } catch (e) { console.log(`  ✗ Could not verify: ${e.message}`); return; }
+
+    if (resp.agent_id && resp.agent_id !== agent.agent_id) {
+      console.log(`  ✗ That token belongs to a different agent (${String(resp.agent_id).slice(0, 8)}…), not ${String(agent.agent_id).slice(0, 8)}….`);
+      console.log('    To map a different agent, use:  clhost add-agent');
+      return;
+    }
+    agent.host_token = token;
+    if (resp.runtime && resp.runtime !== agent.runtime) {
+      console.log(`  ℹ runtime changed: ${agent.runtime} → ${resp.runtime}`);
+      agent.runtime = resp.runtime;
+    }
+    config.save(cfg);
+    const restarted = serviceControl('restart');
+    console.log(`\n  ✓ Updated token for ${agent.agent_id} (…${token.slice(-4)}).` +
+      (restarted ? ' Service restarted.' : ' Run `clhost restart` to apply.') + '\n');
+  } finally { rl.close(); }
+}
+
 // `start | stop | restart` — control the installed background service.
 function serviceControl(action) {
   const platform = process.platform;
@@ -262,14 +305,59 @@ WantedBy=default.target
       return execSafe('systemctl --user enable --now clawlink-host') !== null;
     }
     if (platform === 'win32') {
-      // Best effort: a scheduled task that runs at logon.
-      const taskCmd = `"${nodeBin()}" "${cliEntry()}" run`;
-      return execSafe(`schtasks /Create /F /SC ONLOGON /TN ClawLinkHost /TR ${JSON.stringify(taskCmd)}`) !== null;
+      return installServiceWindows();
     }
   } catch { /* fall through */ }
   return false;
 }
 
+// Windows: a hidden, auto-restarting Scheduled Task created from an XML definition
+// (avoids schtasks /TR quoting issues with spaces in paths). A .cmd launcher pipes
+// the worker's output to host.log; a .vbs runs that launcher with NO console window.
+function installServiceWindows() {
+  const logPath = path.join(config.HOME_DIR, 'host.log');
+  const cmdPath = path.join(config.HOME_DIR, 'run-host.cmd');
+  const vbsPath = path.join(config.HOME_DIR, 'run-host.vbs');
+  const xmlPath = path.join(config.HOME_DIR, 'task.xml');
+  fs.mkdirSync(config.HOME_DIR, { recursive: true });
+
+  // 1) launcher that runs the worker and redirects stdout+stderr to the log
+  fs.writeFileSync(cmdPath,
+    `@echo off\r\n"${nodeBin()}" "${cliEntry()}" run >> "${logPath}" 2>&1\r\n`);
+
+  // 2) VBScript that runs the launcher hidden (0) and waits (True) so the task
+  //    process stays alive while the worker runs. "" -> a literal quote in VBScript.
+  fs.writeFileSync(vbsPath,
+    `CreateObject("WScript.Shell").Run "cmd /c ""${cmdPath}""", 0, True\r\n`);
+
+  // 3) Task XML: logon trigger, hidden, no time limit, restart-on-failure (parity
+  //    with launchd KeepAlive / systemd Restart=always). UTF-16 + BOM (schtasks /XML).
+  const xml = `<?xml version="1.0" encoding="UTF-16"?>
+<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo><Description>ClawLink Host Gateway</Description></RegistrationInfo>
+  <Triggers><LogonTrigger><Enabled>true</Enabled></LogonTrigger></Triggers>
+  <Principals><Principal id="Author"><LogonType>InteractiveToken</LogonType><RunLevel>LeastPrivilege</RunLevel></Principal></Principals>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <StartWhenAvailable>true</StartWhenAvailable>
+    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
+    <Hidden>true</Hidden>
+    <Enabled>true</Enabled>
+    <RestartOnFailure><Interval>PT1M</Interval><Count>999</Count></RestartOnFailure>
+  </Settings>
+  <Actions Context="Author"><Exec><Command>wscript.exe</Command><Arguments>//B //Nologo "${vbsPath}"</Arguments></Exec></Actions>
+</Task>`;
+  fs.writeFileSync(xmlPath, '' + xml, 'utf16le');
+
+  execSafe('schtasks /End /TN ClawLinkHost');
+  execSafe('schtasks /Delete /F /TN ClawLinkHost');
+  const created = execSafe(`schtasks /Create /F /TN ClawLinkHost /XML "${xmlPath}"`) !== null;
+  if (created) execSafe('schtasks /Run /TN ClawLinkHost');
+  return created;
+}
+
 function serviceRunning() {
   const platform = process.platform;
   if (platform === 'darwin') {
@@ -294,6 +382,6 @@ function status() {
 }
 
 module.exports = {
-  run, installOnly, addAgentCmd, removeAgentCmd, listAgents, status,
+  run, installOnly, addAgentCmd, removeAgentCmd, retokenCmd, listAgents, status,
   serviceControl, serviceControlCmd, installService, SERVICE_LABEL,
 };

package/src/adapters/base.js

@@ -1,11 +1,15 @@
 'use strict';
 // Shared spawn helper for CLI-wrapping adapters.
 //
-// SECURITY: commands are ALWAYS invoked with an argv ARRAY and shell:false, so
-// untrusted prompt text can never be interpreted by a shell. Placeholders in the
-// configured args_template ({prompt}, {sessionId}, {systemPrompt}) are substituted
-// PER ARRAY ELEMENT — each becomes exactly one argv token, never concatenated into
-// a command string. The host only ever runs the configured runtime binary.
+// SECURITY: commands are invoked with an argv ARRAY (never a concatenated command
+// string). Placeholders in args_template ({prompt}, {sessionId}, {systemPrompt}) are
+// substituted PER ARRAY ELEMENT — each becomes exactly one argv token. On POSIX we
+// always use shell:false so untrusted prompt text can never reach a shell. On Windows,
+// `.cmd`/`.bat` shims (e.g. npm-installed CLIs) MUST go through the shell because Node
+// refuses to spawn them otherwise; Node then applies its hardened cmd.exe escaping to
+// each argv token. For Windows, prefer a runtime that takes the prompt via STDIN
+// (Claude does) or a native `.exe` so untrusted text never enters a Windows argv at
+// all. The host only ever runs the configured runtime binary.
 
 const { spawn } = require('child_process');
 const logger = require('../logger');
@@ -44,11 +48,20 @@ function buildArgv(template, vars) {
 async function* spawnStreaming({ binary, argv, cwd, env, timeoutMs = 600000, stdinInput = null, parseLine }) {
   if (!binary) throw new Error('no runtime binary configured');
 
+  // Windows: npm CLIs are `.cmd`/`.bat` shims, and modern Node REFUSES to spawn those
+  // with shell:false (EINVAL, post-CVE-2024-27980). Such shims (and bare names that
+  // resolve via PATHEXT) must go through the shell; Node then applies its hardened
+  // cmd.exe argument escaping. Native `.exe`/`.com` are spawned directly (no shell).
+  // On POSIX we ALWAYS use shell:false (untrusted prompt can never reach a shell).
+  const isWin = process.platform === 'win32';
+  const useShell = isWin && !/\.(exe|com)$/i.test(String(binary));
+
   const child = spawn(binary, argv, {
     cwd: cwd || undefined,
     // Enriched PATH so a CLI in ~/.local/bin etc. resolves under a service's minimal env.
     env: enrichedEnv(env),
-    shell: false, // CRITICAL: never use a shell
+    shell: useShell,        // false on POSIX (no shell, ever); on Windows true only for .cmd/.bat shims
+    windowsHide: true,      // no flashing console window on Windows
     stdio: ['pipe', 'pipe', 'pipe'],
   });
 

package/src/adapters/claude.js

@@ -10,10 +10,11 @@ module.exports = makeCliAdapter({
   streamJson: true,
   // Prompt via stdin keeps it out of argv/process listings.
   promptViaStdin: true,
-  defaultArgs: (_fullPrompt, resumeId) => [
+  defaultArgs: (_fullPrompt, resumeId, _stdin, perm = []) => [
     '-p',
     '--output-format', 'stream-json',
     '--verbose',
+    ...perm,
     ...(resumeId ? ['--resume', resumeId] : []),
   ],
   // Admin "configure" turns may write workspace files (auto-accept edits, no shell

package/src/adapters/cli.js

@@ -78,12 +78,14 @@ function makeCliAdapter(cfg) {
 
       // Scope-based permissions: admin "configure" turns may write workspace files
       // (GUARDRAILS/SOUL/etc.); customer/discovery turns are read-only and cannot
-      // edit or run shell. Operator args_template overrides take full control.
+      // edit or run shell. permArgs is handed to defaultArgs so each adapter can place
+      // it correctly (e.g. Codex must put flags BEFORE its `--` end-of-options).
+      // Operator args_template overrides take full control.
       const scope = job.scope || 'customer';
       const permArgs = (!Array.isArray(agent.args_template) && cfg.permissions) ? cfg.permissions(scope) : [];
       const argvFor = (rid) => Array.isArray(agent.args_template)
         ? buildArgv(agent.args_template, { prompt: fullPrompt, sessionId: rid || '', systemPrompt })
-        : [...cfg.defaultArgs(fullPrompt, rid, cfg.promptViaStdin), ...permArgs];
+        : cfg.defaultArgs(fullPrompt, rid, cfg.promptViaStdin, permArgs);
 
       let emittedAny = false;
       const runOnce = async function* (rid) {

package/src/adapters/codex.js

@@ -7,7 +7,16 @@ module.exports = makeCliAdapter({
   name: 'codex',
   binaries: ['codex'],
   promptViaStdin: false,
-  // `--` ends option parsing so an untrusted prompt starting with '-' is treated
-  // as a positional argument, never as a flag (argument-injection hardening).
-  defaultArgs: (fullPrompt) => ['exec', '--', fullPrompt],
+  // Flags go BEFORE `--`; `--` ends option parsing so an untrusted prompt starting
+  // with '-' is treated as a positional argument, never as a flag (arg-injection
+  // hardening). `--ask-for-approval never` ensures it never blocks waiting for an
+  // interactive approval in headless mode.
+  defaultArgs: (fullPrompt, _resumeId, _stdin, perm = []) => ['exec', ...perm, '--', fullPrompt],
+  // Admin "configure" → workspace-write sandbox (may write files in its work dir);
+  // customer/discovery → read-only sandbox (cannot modify anything). Never the
+  // danger/full-access sandbox.
+  permissions: (scope) =>
+    (scope === 'configure' || scope === 'sub_configure')
+      ? ['--sandbox', 'workspace-write', '--ask-for-approval', 'never']
+      : ['--sandbox', 'read-only', '--ask-for-approval', 'never'],
 });

package/src/paths.js

@@ -10,17 +10,28 @@ const path = require('path');
 
 function enrichedPath() {
   const home = os.homedir();
-  const extras = [
-    path.dirname(process.execPath),            // dir of the running node (npm-global CLIs)
-    path.join(home, '.local', 'bin'),
-    path.join(home, 'bin'),
-    path.join(home, '.npm-global', 'bin'),
-    path.join(home, '.bun', 'bin'),
-    path.join(home, '.cargo', 'bin'),
-    '/opt/homebrew/bin',
-    '/usr/local/bin',
-    '/usr/bin', '/bin', '/usr/sbin', '/sbin',
-  ];
+  const extras = [path.dirname(process.execPath)]; // dir of the running node (npm-global CLIs)
+  if (process.platform === 'win32') {
+    const { APPDATA, LOCALAPPDATA, ProgramFiles, SystemRoot } = process.env;
+    if (APPDATA) extras.push(path.join(APPDATA, 'npm'));                       // npm global shims
+    if (LOCALAPPDATA) {
+      extras.push(path.join(LOCALAPPDATA, 'Programs'));                        // per-user installers (e.g. claude)
+      extras.push(path.join(LOCALAPPDATA, 'Microsoft', 'WindowsApps'));
+    }
+    if (ProgramFiles) extras.push(path.join(ProgramFiles, 'nodejs'));
+    if (SystemRoot) { extras.push(path.join(SystemRoot, 'System32')); extras.push(SystemRoot); }
+  } else {
+    extras.push(
+      path.join(home, '.local', 'bin'),
+      path.join(home, 'bin'),
+      path.join(home, '.npm-global', 'bin'),
+      path.join(home, '.bun', 'bin'),
+      path.join(home, '.cargo', 'bin'),
+      '/opt/homebrew/bin',
+      '/usr/local/bin',
+      '/usr/bin', '/bin', '/usr/sbin', '/sbin',
+    );
+  }
   const seen = new Set();
   const parts = [...extras, ...String(process.env.PATH || '').split(path.delimiter)]
     .filter((p) => p && !seen.has(p) && seen.add(p));