@stroq/cli 0.1.0 → 0.10.1

package/openclaw-plugin/README.md

@@ -0,0 +1,49 @@
+# Stroq plugin for OpenClaw
+
+A thin gate that forwards every tool call to the Stroq CLI and does what it says.
+It is shipped inside `@stroq/cli`; `stroq init --agent openclaw` copies it to
+`$STROQ_HOME/openclaw-plugin/` (default `~/.stroq/openclaw-plugin/`), writes a
+`stroq.json` recording how to start Stroq, and then runs — or prints — these two:
+
+    openclaw plugins install --link ~/.stroq/openclaw-plugin
+    openclaw plugins enable stroq
+
+Restart the Gateway afterwards: plugins are loaded when it starts.
+
+## Hooks
+
+- `before_tool_call` (priority 100, no matcher) runs `stroq hook openclaw pre`.
+  `allow` returns nothing, `deny` blocks with the rule and reason, `ask` raises a
+  `requireApproval` prompt answered with `/approve <id> allow-once|deny`.
+- `after_tool_call` runs `stroq hook openclaw post`, which scans the result, records
+  provenance and taints the session. It is observe-only: the warning is logged, the
+  taint is enforced on the next tool call.
+
+**Fail-closed.** Every one of these blocks the call, which is OpenClaw's own policy
+for this hook: a missing binary, a spawn error, a non-zero exit, a timeout, an aborted
+run, a reply larger than 1 MiB (a hung CLI, not a decision), params that cannot be
+serialised, stdout that is not JSON or is JSON but not an object, and a decision this
+plugin does not know. `after_tool_call` never throws — the tool has already run — and
+a scan that fails there is logged at `warn`, since a failed scan means no taint.
+
+If the `stroq.json` `init` recorded points at an entry that no longer exists (an npx
+cache that has since been pruned), the plugin logs one warning and falls back to
+`stroq` on PATH rather than blocking every call on the same ENOENT. When there is no
+Stroq on PATH either, the call still fails closed.
+
+## Configuration
+
+`plugins.entries.stroq.config` in `openclaw.json`. It is read **once**, when the
+plugin registers, so restart the Gateway after changing any of it:
+
+| Key            | Default                            | What it does                                                                                                                                                                                                                                                                                                                                                                                          |
+| -------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `stroqBin`     | `stroq.json`, else `stroq` on PATH | Path to the Stroq binary to spawn, as one string (never split on spaces, and never existence-checked — a binary you named must fail loudly rather than be silently replaced). `STROQ_BIN` is read before `stroq.json`, and a `stroq.json` whose recorded entry file is gone is skipped in favour of PATH. A launch command needing extra arguments belongs in `stroq.json`'s `command` array instead. |
+| `workspace`    | the Gateway's `process.cwd()`      | The project directory for the secret index and path rules. A tool call's own `params.cwd` is never used for this, for any tool including `exec`: honouring one would let an agent point it at an empty directory and slip past a secret-egress guard.                                                                                                                                                 |
+| `timeoutMs`    | `10000`                            | How long Stroq gets to answer before the call is blocked.                                                                                                                                                                                                                                                                                                                                             |
+| `askTimeoutMs` | `120000`                           | How long an approval prompt stays open, clamped to OpenClaw's documented 1 000–600 000 ms range.                                                                                                                                                                                                                                                                                                      |
+| `logLevel`     | the Gateway's own                  | Declared for the plugin manager's UI; this entry logs at fixed levels (`warn` for a block, a suspect result, a failed post scan or a stale `stroq.json`, `info` for an approval resolution) and lets the Gateway's logger filter them.                                                                                                                                                                |
+
+Set `plugins.entries.stroq.enabled` to `true`, and add `stroq` to `plugins.allow` if
+an allowlist is configured. This directory has no dependencies and is plain ESM
+JavaScript, so nothing is installed or built when it is linked.

package/openclaw-plugin/index.js

@@ -0,0 +1,146 @@
+// Stroq plugin for OpenClaw: turns `before_tool_call` / `after_tool_call` into
+// `stroq hook openclaw pre|post` child-process calls (spawning is in run-stroq.js).
+// Fail-closed by construction — every one of these blocks the call: a missing binary,
+// a spawn error, a non-zero exit, a timeout, an aborted run, a reply larger than
+// 1 MiB, params that cannot be serialised, stdout that is not JSON or is JSON but not
+// an object, and a decision this file does not know.
+import { createRequire } from 'node:module';
+import { clip, runStroq, text } from './run-stroq.js';
+
+const DESCRIPTION =
+  'Local action firewall for OpenClaw: scans what the agent reads, taints the session, blocks or asks before dangerous tool calls.';
+const DEFAULT_ASK_TIMEOUT_MS = 120000;
+// OpenClaw's own documented bounds for an approval prompt. A `timeoutMs` past the
+// maximum is not a longer prompt, it is a `requireApproval` the Gateway may reject
+// outright — and a rejected approval is a call nobody was ever asked about.
+const MIN_ASK_TIMEOUT_MS = 1000;
+const MAX_ASK_TIMEOUT_MS = 600000;
+const MAX_TITLE = 80;
+const MAX_DESCRIPTION = 512;
+const load = createRequire(import.meta.url);
+
+/** `definePluginEntry`, from whichever SDK path this Gateway build exposes. */
+function resolveDefinePluginEntry() {
+  for (const id of ['openclaw/plugin-sdk/plugin-entry', 'openclaw/plugin-sdk/core']) {
+    try {
+      const mod = load(id);
+      const fn = mod?.definePluginEntry ?? mod?.default?.definePluginEntry;
+      if (typeof fn === 'function') return fn;
+    } catch {
+      // not exposed by this build; try the next id, then fall back to bare `register`
+    }
+  }
+  return null;
+}
+
+/** Logging never decides anything: an absent logger is skipped and a throwing one is swallowed. */
+function logAt(api, level, message) {
+  const fn = api && api.logger && api.logger[level];
+  try {
+    if (typeof fn === 'function') fn.call(api.logger, message);
+  } catch {}
+}
+
+/**
+ * Both phases' payload. `cwd` is always the plugin's OWN directory — `config.workspace`,
+ * else `process.cwd()` — and never a tool call's `params.cwd`: honouring a
+ * model-supplied `cwd` here would let any tool point the project directory (and so
+ * the secret index) at an empty one and walk straight past a secret-egress guard.
+ * `exec` is no exception: the CLI adapter also never reads `params.cwd` for this
+ * (Task 4.5 review, Critical — it used to, and that was the actual bypass). `params`
+ * is still forwarded whole regardless, `cwd` included, purely for the audit trail.
+ */
+function payloadFor(phase, event, ctx, config) {
+  const params = event.params && typeof event.params === 'object' ? event.params : {};
+  const c = ctx || {};
+  const base = {
+    sessionId: text(c.sessionKey) || text(c.sessionId) || 'openclaw',
+    agentId: c.agentId,
+    runId: c.runId ?? event.runId,
+    toolCallId: c.toolCallId ?? event.toolCallId,
+    toolKind: event.toolKind ?? c.toolKind,
+    requester: c.requester,
+    toolName: text(event.toolName),
+    params,
+    cwd: text(config.workspace) || process.cwd(),
+  };
+  if (phase === 'pre') return base;
+  return { ...base, result: event.result, error: event.error, durationMs: event.durationMs };
+}
+
+/** How long the prompt stays open, clamped to the range OpenClaw documents. */
+function askTimeout(config) {
+  const configured = Number(config.askTimeoutMs);
+  if (!(configured > 0)) return DEFAULT_ASK_TIMEOUT_MS;
+  return Math.min(Math.max(configured, MIN_ASK_TIMEOUT_MS), MAX_ASK_TIMEOUT_MS);
+}
+
+/** `ask` as OpenClaw's approval request, inside its documented 80/512/600 000 caps. */
+function approval(api, event, reply, config) {
+  const ms = askTimeout(config);
+  return {
+    title: clip(`Stroq: ${text(reply.ruleId) || 'policy'}`, MAX_TITLE),
+    description: clip(text(reply.reason) || 'Stroq asks before this action.', MAX_DESCRIPTION),
+    severity: 'warning',
+    // `allow-always` is deliberately not offered: Stroq audits every ask, and a
+    // remembered allow is one it would never be asked about again.
+    allowedDecisions: ['allow-once', 'deny'],
+    timeoutMs: ms,
+    onResolution: (decision) =>
+      logAt(api, 'info', `stroq: approval ${decision} for ${text(event.toolName)}`),
+  };
+}
+
+export function register(api) {
+  const config = (api && api.pluginConfig) || {};
+  // `detail` is clipped like a child's stderr: it is a block reason shown to a user.
+  const block = (event, detail) => {
+    const clipped = clip(String(detail), 300);
+    logAt(api, 'warn', `stroq: ${text(event && event.toolName) || 'tool'}: ${clipped}`);
+    return { block: true, blockReason: `Stroq internal error (fail-closed): ${clipped}` };
+  };
+  // A stale `stroq.json` entry is reported at `warn`: the operator should repair it.
+  const warn = (message) => logAt(api, 'warn', `stroq: ${message}`);
+  // Priority 100 so Stroq answers before ordinary hooks; no matcher, every tool goes through.
+  api.on(
+    'before_tool_call',
+    async (event, ctx) => {
+      let outcome;
+      try {
+        const payload = payloadFor('pre', event, ctx, config);
+        outcome = await runStroq(config, 'pre', payload, ctx?.abortSignal, warn);
+      } catch (err) {
+        return block(event, `cannot read the tool call: ${String(err)}`);
+      }
+      if (outcome.error) return block(event, outcome.error);
+      const reply = outcome.reply;
+      if (reply.decision === 'allow') return undefined;
+      if (reply.decision === 'ask') return { requireApproval: approval(api, event, reply, config) };
+      if (reply.decision === 'deny')
+        return {
+          block: true,
+          blockReason: `Stroq blocked this action (${text(reply.ruleId) || 'policy'}): ${text(reply.reason) || 'no reason given'}`,
+        };
+      return block(event, `unknown decision ${JSON.stringify(reply.decision)}`);
+    },
+    { priority: 100 },
+  );
+  // Observe-only and never throws; the taint it sets is enforced on the NEXT call. The
+  // abort signal is not forwarded: a cancelled run's result must still be scanned.
+  api.on('after_tool_call', async (event, ctx) => {
+    try {
+      const payload = payloadFor('post', event, ctx, config);
+      const outcome = await runStroq(config, 'post', payload, undefined, warn);
+      // `warn`: a scan nobody looked at leaves the session untainted; operators must see it.
+      if (outcome.error) logAt(api, 'warn', `stroq: post scan failed: ${outcome.error}`);
+      else if (text(outcome.reply.warning)) logAt(api, 'warn', `stroq: ${outcome.reply.warning}`);
+    } catch (err) {
+      logAt(api, 'warn', `stroq: post scan failed: ${String(err)}`);
+    }
+  });
+}
+
+const definePluginEntry = resolveDefinePluginEntry();
+export default definePluginEntry
+  ? definePluginEntry({ id: 'stroq', name: 'Stroq', description: DESCRIPTION, register })
+  : register;

package/openclaw-plugin/openclaw.plugin.json

@@ -0,0 +1,27 @@
+{
+  "id": "stroq",
+  "name": "Stroq",
+  "description": "Local action firewall for OpenClaw: scans what the agent reads, taints the session, blocks or asks before dangerous tool calls.",
+  "version": "0.10.1",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "stroqBin": { "type": "string" },
+      "workspace": { "type": "string" },
+      "timeoutMs": { "type": "integer", "minimum": 1000 },
+      "askTimeoutMs": { "type": "integer", "minimum": 1000 },
+      "logLevel": { "type": "string", "enum": ["warn", "info", "debug"] }
+    }
+  },
+  "uiHints": {
+    "stroqBin": {
+      "label": "stroq command",
+      "help": "Path to the stroq binary. Defaults to `stroq` on PATH, then the path recorded by `stroq init --agent openclaw`."
+    },
+    "workspace": {
+      "label": "Project directory",
+      "help": "Used for the secret index and path classification. A tool call's own cwd is never used for this — see the plugin README."
+    }
+  }
+}

package/openclaw-plugin/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "stroq-openclaw-plugin",
+  "version": "0.10.1",
+  "private": true,
+  "description": "Stroq's OpenClaw plugin entry: forwards before_tool_call and after_tool_call to the Stroq CLI.",
+  "type": "module",
+  "openclaw": {
+    "extensions": [
+      {
+        "entry": "index.js"
+      }
+    ]
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/openclaw-plugin/run-stroq.js

@@ -0,0 +1,166 @@
+// Spawns the Stroq CLI for one hook phase and resolves to `{ reply }` or `{ error }`,
+// never rejecting: every failure this plugin can see — a missing binary, a spawn
+// error, a non-zero exit, a timeout, an aborted run, an oversized reply, or stdout
+// that is not JSON — becomes an `{ error }` for index.js to turn into a block.
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, isAbsolute, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_TIMEOUT_MS = 10000;
+// A reply this large is not a decision Stroq ever sends; it is a hung or misbehaving
+// CLI, and buffering it further would only delay the same block.
+const MAX_OUTPUT_BYTES = 1024 * 1024;
+/** The launch command `stroq init --agent openclaw` records beside this file. */
+const COMMAND_FILE = 'stroq.json';
+/** The last resort: a bare name `spawn` resolves through PATH. */
+const PATH_FALLBACK = 'stroq';
+
+export const text = (value) => (typeof value === 'string' && value !== '' ? value : '');
+export const clip = (value, max) => (value.length <= max ? value : `${value.slice(0, max - 3)}...`);
+
+/** A launch command is a non-empty array of strings; anything else is not one. */
+const isArgv = (value) =>
+  Array.isArray(value) && value.length > 0 && value.every((a) => typeof a === 'string');
+
+/**
+ * The file a recorded command would actually run: the LAST absolute path in the argv,
+ * which is the entry rather than the interpreter — `['<node>', '--import', 'tsx',
+ * '/opt/stroq/src/index.ts']` names three paths and only the last one goes stale. A
+ * relative element is never treated as the entry: it resolves against a working
+ * directory this module does not know, so its absence would prove nothing.
+ */
+export const recordedEntry = (argv) => {
+  for (let i = argv.length - 1; i >= 0; i -= 1) if (isAbsolute(argv[i])) return argv[i];
+  return null;
+};
+
+/**
+ * argv of the Stroq CLI, and the recorded entry (if any) that turned out to be gone:
+ * this plugin's config, then `STROQ_BIN`, then the `stroq.json` `stroq init --agent
+ * openclaw` wrote beside this file, then `stroq` on PATH.
+ *
+ * The recorded command is SKIPPED when its entry file no longer exists. `npx
+ * @stroq/cli init --agent openclaw` records a path inside the npx cache, and pruning
+ * that cache used to leave every single tool call blocked on an ENOENT nobody could
+ * read — a firewall bricking the agent because its own installer's temp directory was
+ * cleaned up. Falling back to PATH turns that into one warning plus a working Stroq
+ * wherever one is installed; when there is none, the call still fails closed.
+ *
+ * `stroqBin`/`STROQ_BIN` is always ONE path, never split on whitespace (a real install
+ * path can legitimately contain a space, and a launch command needing extra arguments
+ * belongs in `stroq.json`'s array-shaped `command` instead) and never existence-
+ * checked: an operator who named a binary must see it fail rather than be silently
+ * redirected to some other Stroq that happens to be on PATH.
+ *
+ * Pure — the config, the environment, the recorded command and the existence check
+ * are all parameters — so the whole order is testable without a filesystem.
+ */
+export function resolveStroqArgv({ config = {}, env = {}, recorded = null, exists }) {
+  const configured = text(config.stroqBin) || text(env.STROQ_BIN);
+  if (configured) return { argv: [configured], staleEntry: null };
+  if (!isArgv(recorded)) return { argv: [PATH_FALLBACK], staleEntry: null };
+  const entry = recordedEntry(recorded);
+  if (entry !== null && !exists(entry)) return { argv: [PATH_FALLBACK], staleEntry: entry };
+  return { argv: [...recorded], staleEntry: null };
+}
+
+/** The `command` array `init` recorded, or `null` when there is none to read. */
+function readRecordedCommand(file) {
+  try {
+    return existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')).command : null;
+  } catch {
+    // unreadable or not JSON: fall through to PATH
+    return null;
+  }
+}
+
+/** A stale entry is one fact about this install, not one per tool call. */
+let warnedStale = false;
+
+function stroqArgv(config, warn) {
+  const { argv, staleEntry } = resolveStroqArgv({
+    config,
+    env: process.env,
+    recorded: readRecordedCommand(join(HERE, COMMAND_FILE)),
+    exists: existsSync,
+  });
+  if (staleEntry !== null && !warnedStale) {
+    warnedStale = true;
+    warn(
+      `${COMMAND_FILE} records ${staleEntry}, which no longer exists; falling back to ` +
+        `"${PATH_FALLBACK}" on PATH. Install @stroq/cli globally and re-run ` +
+        '"stroq init --agent openclaw".',
+    );
+  }
+  return argv;
+}
+
+/** The child's answer: a reply object, or the reason it is not one. */
+function replyOf(code, stdout, stderr) {
+  if (code !== 0)
+    return { error: `exit ${code}: ${clip(stderr.trim() || 'no reason given', 300)}` };
+  try {
+    const reply = JSON.parse(stdout);
+    if (reply && typeof reply === 'object') return { reply };
+  } catch {
+    // not an answer at all
+  }
+  return { error: `unreadable answer: ${clip(stdout.trim(), 200)}` };
+}
+
+/**
+ * Runs one phase and resolves to `{ reply }` or `{ error }`. Never rejects. `warn`
+ * carries the one message this module can produce that is not a decision — a
+ * `stroq.json` whose entry is gone — out to the Gateway's own logger.
+ */
+export function runStroq(config, phase, payload, abortSignal, warn = () => {}) {
+  return new Promise((resolve) => {
+    let argv;
+    let stdin;
+    try {
+      argv = stroqArgv(config, warn);
+      stdin = JSON.stringify(payload);
+    } catch (err) {
+      resolve({ error: `cannot build the hook call: ${String(err)}` });
+      return;
+    }
+    const [bin, ...rest] = argv;
+    const child = spawn(bin, [...rest, 'hook', 'openclaw', phase], { signal: abortSignal });
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(value);
+    };
+    const ms = Number(config.timeoutMs) > 0 ? Number(config.timeoutMs) : DEFAULT_TIMEOUT_MS;
+    const timer = setTimeout(() => {
+      child.kill('SIGKILL');
+      finish({ error: `no answer in ${ms} ms` });
+    }, ms);
+    // Bytes, not UTF-16 code units: a cap called BYTES that counted `String.length`
+    // would let a reply of multi-byte characters buffer several times its own limit.
+    const checkSize = () => {
+      if (Buffer.byteLength(stdout) + Buffer.byteLength(stderr) <= MAX_OUTPUT_BYTES) return;
+      child.kill('SIGKILL');
+      finish({ error: `the reply exceeded ${MAX_OUTPUT_BYTES} bytes and was cut off` });
+    };
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk;
+      checkSize();
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr += String(chunk);
+      checkSize();
+    });
+    child.stdin.on('error', () => {});
+    child.on('error', (err) => finish({ error: `cannot run ${bin}: ${err.message}` }));
+    child.on('close', (code) => finish(replyOf(code, stdout, stderr)));
+    child.stdin.end(stdin);
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stroq/cli",
-  "version": "0.1.0",
+  "version": "0.10.1",
   "description": "Local action firewall for AI agents: scans what the agent reads, taints the session, blocks dangerous follow-up actions",
   "license": "Apache-2.0",
   "type": "module",
@@ -9,9 +9,14 @@
   },
   "files": [
     "dist",
+    "openclaw-plugin",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "DISCLOSURE"
   ],
+  "contentPolicy": {
+    "class": "dual-use"
+  },
   "engines": {
     "node": ">=22"
   },