@claw-link/gateway-host 0.2.4 → 0.2.5

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
 
@@ -111,11 +112,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claw-link/gateway-host",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "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

@@ -262,14 +262,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') {

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));