@drakon-systems/multi-clawd 1.5.1 → 1.5.3

package/README.md

@@ -188,13 +188,18 @@ openclaw plugins install (Get-Location).Path
 **Or let your agent install it.** Running an OpenClaw assistant or Claude
 Code on the target machine already? Paste it this and go make coffee:
 
-> Read https://raw.githubusercontent.com/Drakon-Systems-Ltd/multi-clawd/master/SETUP-AGENT.md
+> Read https://raw.githubusercontent.com/Drakon-Systems-Ltd/multi-clawd/v1.5.3/SETUP-AGENT.md
 > and follow it to set up multi-clawd on this machine. I own a second
 > Claude account — ask me when you need me to log in.
 
 The guide has the guardrails built in (config backup, merge-don't-overwrite,
 never print tokens, ask before touching routing).
 
+That URL is pinned to a release tag on purpose: what your agent reads — and
+therefore executes — is fixed at a version you chose, not whatever `master`
+happens to say today. Swap the tag if you want a different release, but
+prefer a tag over a branch.
+
 **Requirements:** OpenClaw ≥ 2026.6, the `claude` CLI on `PATH`, and a
 second Claude subscription you own.
 
@@ -446,6 +451,10 @@ event, and no plugin API can force a rebuild. See `DESIGN.md`.
 
 ## Security
 
+See **[SECURITY.md](SECURITY.md)** for how to report a vulnerability, exactly
+how credentials are handled, and a table documenting every process-spawn
+callsite (the ones static scanners flag) and why each exists.
+
 **Full declaration of what this plugin touches — nothing else:**
 
 | Surface | What multi-clawd does |

package/SECURITY.md

@@ -0,0 +1,82 @@
+# Security
+
+multi-clawd handles Claude Code login credentials. That makes it worth
+explaining exactly what it touches, and worth telling you how to report a
+problem.
+
+## Reporting a vulnerability
+
+Open a [security advisory](https://github.com/Drakon-Systems-Ltd/multi-clawd/security/advisories/new)
+on the repository, or email **security@drakonsystems.com**. Please do not open
+a public issue for anything exploitable.
+
+We aim to acknowledge within 72 hours. If a fix is warranted we will ship it,
+credit you (unless you'd rather we didn't), and note it in the CHANGELOG.
+
+## How credentials are handled
+
+- **Tokens are never logged and never appear in a command line.** They are
+  passed to the Claude CLI child process through its environment only, so they
+  cannot leak into a process list, a shell history, or a log file.
+- **Secret references are preferred over token files.** `oauthTokenRef` uses
+  the same `{source, provider, id}` shape as the rest of `openclaw.json` and
+  resolves through the gateway's own configured secret providers (1Password,
+  etc.), so the credential never sits in plaintext on disk.
+- **Secret-resolution failures are redacted to a fixed reason code.** The
+  message that reaches your logs contains neither the token, nor the
+  provider/id being resolved, nor the provider's own exception text — only the
+  error class, for debuggability.
+- **Plaintext token files are checked, not trusted.** If you use the legacy
+  `oauthTokenFile`, multi-clawd warns (once per process) when the file is
+  readable beyond your own user account. It warns rather than refuses: the
+  credential still works, and the fix is yours to make — `chmod 600`.
+- **Host credentials are stripped from child processes.** 22 Claude/Anthropic
+  environment variables are cleared before each launch, so one account's
+  credential cannot bleed into another account's session.
+- **State files are written `0600`,** atomically (temp file + rename), and
+  contain rate-limit telemetry only — never credentials.
+
+## Permissions
+
+multi-clawd never grants itself more permission than OpenClaw core grants the
+bundled `claude-cli` backend. It appends `--permission-mode bypassPermissions`
+**only** when your own config already sets `tools.exec.mode: "full"` — which is
+what core does for the bundled backend. Under any other exec mode it passes
+nothing and Claude keeps its default prompt-honouring behaviour.
+
+## Why static scanners flag this package
+
+Automated scans flag multi-clawd for `dangerous_exec`. That is expected and
+correct: starting Claude Code processes *is* the product. Every such callsite
+is listed here so you can check them yourself.
+
+| Location | What it runs | Why |
+| --- | --- | --- |
+| `dist/shim.js` | the `claude` binary | The core function: launches Claude Code for the selected account. Argv is built from a fixed base list plus your configured model; no shell. |
+| `dist/watchdog-schedule.js` | `node <bundled script>` | Runs the eviction watchdog on a timer. Path is the package's own script. |
+| `scripts/cli.mjs` | `node <bundled script>` | The CLI dispatching to its own subcommands. |
+| `scripts/setup.mjs` | `launchctl` / `systemctl` | Loads the watchdog timer during setup on macOS/Linux. |
+
+None of these pass a string to a shell — they are direct process spawns with
+argument arrays, so there is no quoting or injection surface. Paths are
+package-internal or derived from your home directory, never from remote input.
+
+## Things you should decide for yourself
+
+- **The watchdog is persistence.** `setup` schedules a user-level systemd timer
+  (or launchd agent) that can restart the OpenClaw gateway. It is optional —
+  skip it if you don't want that.
+- **The setup wizard edits `~/.openclaw/openclaw.json`.** It backs the file up
+  first and merges rather than overwrites, and `--dry-run` shows you the
+  changes without writing. Use it.
+- **The agent-install one-liner is pinned to a release tag,** not `master`, so
+  what your assistant reads and executes is fixed at a version you chose.
+  Inspect `SETUP-AGENT.md` before pointing an agent at it — that advice holds
+  for anyone's setup guide, including ours.
+
+## Scope
+
+multi-clawd runs entirely on your machine against your own Claude
+subscriptions. It has no server component, no telemetry, and **zero runtime
+dependencies** — the only third-party code in the install is whatever OpenClaw
+itself already provides.

package/dist/account-env.js

@@ -19,6 +19,14 @@ export function buildAccountChildEnv(account, token, stateFile) {
     }
     return env;
 }
+export function tokenFileModeWarning(path, mode) {
+    const perms = mode & 0o777;
+    if ((perms & 0o077) === 0)
+        return undefined;
+    return (`token file ${path} is mode ${perms.toString(8).padStart(3, "0")} — readable beyond your ` +
+        `user account. Anyone with a login on this machine can take the Claude credential. ` +
+        `Fix: chmod 600 ${path}`);
+}
 export function validateAccountTokenSources(account) {
     const sources = [];
     if (account.native)

package/dist/index.js

@@ -2,7 +2,7 @@ import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
 import { resolvePluginConfigObject, resolveLivePluginConfigObject, } from "openclaw/plugin-sdk/plugin-config-runtime";
 import { CLI_FRESH_WATCHDOG_DEFAULTS, CLI_RESUME_WATCHDOG_DEFAULTS, } from "openclaw/plugin-sdk/cli-backend";
 import { homedir } from "node:os";
-import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { MODEL_ALIASES, buildCatalogEntries, canonicalModelId, isModernClaudeModelId, resolveModelSpec, } from "./models.js";
@@ -14,7 +14,7 @@ import { decideStickySelection } from "./sticky.js";
 import { createTokenRefResolver, isSecretRefShape, } from "./token-resolution.js";
 import { resolveSecretRefValues } from "openclaw/plugin-sdk/secret-ref-runtime";
 import { addAlert, clearAlert, pendingAlertText } from "./alerts.js";
-import { buildAccountChildEnv, validateAccountTokenSources } from "./account-env.js";
+import { buildAccountChildEnv, tokenFileModeWarning, validateAccountTokenSources, } from "./account-env.js";
 import { checkAccountCredential, createRefProbeTracker, } from "./login-health.js";
 import { execFileSync } from "node:child_process";
 const BASE_ARGS = [
@@ -164,11 +164,26 @@ function startLoginHealthProbe(accounts, logger) {
     loginProbeTimer = setInterval(() => void probe().catch(() => { }), LOGIN_PROBE_INTERVAL_MS);
     loginProbeTimer.unref?.();
 }
+const warnedTokenFileModes = new Set();
+function warnIfTokenFileExposed(path) {
+    if (warnedTokenFileModes.has(path))
+        return;
+    warnedTokenFileModes.add(path);
+    try {
+        const warning = tokenFileModeWarning(path, statSync(path).mode);
+        if (warning)
+            console.warn(`[multi-clawd] ${warning}`);
+    }
+    catch {
+    }
+}
 function peekToken(account) {
     if (account.native)
         return undefined;
     if (account.oauthTokenFile) {
-        return readFileSync(expandHome(account.oauthTokenFile), "utf8").trim();
+        const path = expandHome(account.oauthTokenFile);
+        warnIfTokenFileExposed(path);
+        return readFileSync(path, "utf8").trim();
     }
     if (isSecretRefShape(account.oauthTokenRef)) {
         return activeTokenResolver?.peek(account.oauthTokenRef);

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "multi-clawd",
   "name": "multi-clawd",
-  "version": "1.5.1",
+  "version": "1.5.3",
   "description": "Register additional Claude Code logins (Max/Pro accounts) as first-class OpenClaw CLI backends for cross-account failover, keeping the full skills/MCP harness on every account.",
   "cliBackends": [
     "claw1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakon-systems/multi-clawd",
-  "version": "1.5.1",
+  "version": "1.5.3",
   "description": "Multi-account Claude Code failover for OpenClaw — register additional Claude (Max/Pro) logins as first-class CLI backends and keep the full skills/MCP harness across every account.",
   "type": "module",
   "license": "MIT",
@@ -46,6 +46,7 @@
     "scripts",
     "openclaw.plugin.json",
     "README.md",
+    "SECURITY.md",
     "LICENSE"
   ],
   "scripts": {
@@ -57,7 +58,8 @@
     "doctor": "node scripts/doctor.mjs",
     "setup": "node scripts/setup.mjs",
     "sync-manifest": "node -e \"const fs=require('fs');const m=JSON.parse(fs.readFileSync('openclaw.plugin.json','utf8'));m.version=process.env.npm_package_version||JSON.parse(fs.readFileSync('package.json','utf8')).version;fs.writeFileSync('openclaw.plugin.json',JSON.stringify(m,null,2)+'\\n')\"",
-    "version": "npm run sync-manifest && git add openclaw.plugin.json"
+    "sync-readme-tag": "node scripts/sync-readme-tag.mjs",
+    "version": "npm run sync-manifest && npm run sync-readme-tag && git add openclaw.plugin.json README.md"
   },
   "peerDependencies": {
     "openclaw": ">=2026.6"

package/scripts/cli.mjs

@@ -185,11 +185,11 @@ async function healWatchdogUnit() {
           refreshLauncher();
           writeFileSync(file, text.split(target).join(WATCHDOG_LAUNCHER));
           if (d.endsWith("LaunchAgents")) {
-            try {
-              execFileSync("/bin/sh", ["-c", `launchctl unload "${file}" 2>/dev/null; launchctl load "${file}" 2>&1 || true`]);
-            } catch {
-              /* manual load needed */
-            }
+            // Direct spawns, not a `sh -c` string: no quoting to get wrong and
+            // no shell for a path to break out of. Both calls are best-effort —
+            // unload fails harmlessly when nothing is loaded yet.
+            spawnSync("launchctl", ["unload", file], { stdio: "ignore" });
+            spawnSync("launchctl", ["load", file], { stdio: "ignore" });
           } else {
             try {
               execFileSync("systemctl", ["--user", "daemon-reload"]);

package/scripts/setup.mjs

@@ -26,7 +26,7 @@ import { readFileSync, writeFileSync, copyFileSync, existsSync, mkdirSync, readd
 import { homedir } from "node:os";
 import { join, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawnSync } from "node:child_process";
 import readline from "node:readline/promises";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -369,12 +369,16 @@ function reloadWatchdogUnit(platform, file) {
       /* was not loaded */
     }
     try {
-      // launchctl can print "Load failed" to stderr and still exit 0 — merge
-      // the streams and check the text, not just the exit code.
-      const out = execFileSync("/bin/sh", ["-c", `launchctl load "${file}" 2>&1 || true`], {
-        encoding: "utf8",
-      });
-      if (/load failed|bootstrap failed/i.test(out)) throw new Error(out.trim());
+      // launchctl can print "Load failed" to stderr and still exit 0, so we
+      // inspect BOTH streams rather than trusting the exit code. spawnSync
+      // (not a `/bin/sh -c` string) keeps this off the shell entirely: no
+      // quoting to get wrong, and nothing for a path to break out of.
+      const r = spawnSync("launchctl", ["load", file], { encoding: "utf8" });
+      if (r.error) throw r.error;
+      const out = `${r.stdout ?? ""}${r.stderr ?? ""}`;
+      if (r.status !== 0 || /load failed|bootstrap failed/i.test(out)) {
+        throw new Error(out.trim() || `launchctl exited ${r.status}`);
+      }
       console.log("  ✅ launchd agent (re)loaded");
     } catch {
       console.log(`  ⚠ plist written but load failed — run: launchctl load ${file}`);

package/scripts/sync-readme-tag.mjs

@@ -0,0 +1,34 @@
+/**
+ * Keep the README's pinned SETUP-AGENT.md URL on the current release tag.
+ *
+ * The agent-install one-liner points people's assistants at a raw GitHub URL,
+ * and that URL is what they will actually EXECUTE. Pinning it to a tag makes
+ * those instructions immutable per release — but a hand-maintained version
+ * number in prose drifts (the openclaw.plugin.json version did exactly that,
+ * twice), so the `version` npm hook rewrites it here instead.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+const readmePath = join(root, "README.md");
+
+// npm sets npm_package_version during the version lifecycle; fall back to the
+// file for direct invocations.
+const version =
+  process.env.npm_package_version ||
+  JSON.parse(readFileSync(join(root, "package.json"), "utf8")).version;
+
+const PATTERN =
+  /(raw\.githubusercontent\.com\/Drakon-Systems-Ltd\/multi-clawd\/)(?:master|v[\d.]+)(\/SETUP-AGENT\.md)/g;
+
+const readme = readFileSync(readmePath, "utf8");
+const updated = readme.replace(PATTERN, `$1v${version}$2`);
+
+if (updated === readme) {
+  console.log(`sync-readme-tag: already pinned to v${version}`);
+} else {
+  writeFileSync(readmePath, updated);
+  console.log(`sync-readme-tag: pinned SETUP-AGENT.md URL to v${version}`);
+}