@denial-web/clawguard 0.1.7 → 0.1.9

package/README.md

@@ -80,6 +80,25 @@ If you want ClawGuard to own the approval channel separately, send directly thro
 TELEGRAM_BOT_TOKEN=123456:token npx @denial-web/clawguard approvals send ./.clawguard/approvals.jsonl --via telegram --chat-id 123456789
 ```
 
+For an automatic bridge, keep a watcher running. It forwards each new pending approval once and stores sent approval ids in `./.clawguard/approvals.jsonl.sent.json` by default:
+
+```bash
+TELEGRAM_BOT_TOKEN=123456:token npx @denial-web/clawguard approvals watch ./.clawguard/approvals.jsonl --via telegram --chat-id 123456789
+```
+
+Use `--once --dry-run` to verify the message flow without sending anything:
+
+```bash
+TELEGRAM_BOT_TOKEN=123456:token npx @denial-web/clawguard approvals watch ./.clawguard/approvals.jsonl --via telegram --chat-id 123456789 --once --dry-run
+```
+
+Record the owner's decision in a durable decision log:
+
+```bash
+npx @denial-web/clawguard approvals decide ./.clawguard/approvals.jsonl --id <approval-id> --decision approve --out ./.clawguard/decisions.jsonl
+npx @denial-web/clawguard approvals decide ./.clawguard/approvals.jsonl --id <approval-id> --decision deny --reason "Unexpected shell access" --out ./.clawguard/decisions.jsonl
+```
+
 When testing the published package, run `npx` from outside this repository. From inside the ClawGuard source checkout, use the local commands instead:
 
 ```bash

package/docs/INTEGRATION_SPEC.md

@@ -68,6 +68,31 @@ TELEGRAM_BOT_TOKEN=123456:token clawguard approvals send ./.clawguard/approvals.
 
 That path is better when the user wants the approval channel to stay independent from the agent runtime. Use `--dry-run` first to verify the redacted endpoint and message payload before sending.
 
+For long-running installs, ClawGuard can watch the approval queue and forward each new pending request once:
+
+```bash
+TELEGRAM_BOT_TOKEN=123456:token clawguard approvals watch ./.clawguard/approvals.jsonl \
+  --via telegram \
+  --chat-id 123456789
+```
+
+The watcher keeps search and discovery unrestricted. It only reacts after a guarded install writes a pending approval request. By default it records sent ids in `./.clawguard/approvals.jsonl.sent.json`, so restarting the bridge does not resend the same request. Use `--once --dry-run` for setup checks and CI smoke tests.
+
+### Approval Decisions
+
+Owner decisions are stored separately from approval requests. This keeps the original scan evidence immutable and gives messaging bridges a simple append-only target:
+
+```bash
+clawguard approvals decide ./.clawguard/approvals.jsonl \
+  --id <approval-id> \
+  --decision approve \
+  --actor owner \
+  --reason "Reviewed and acceptable" \
+  --out ./.clawguard/decisions.jsonl
+```
+
+The decision log uses `schemaVersion: "clawguard.decision.v1"` and stores the approval id, normalized decision, actor, reason, target, destination, risk summary, policy summary, and source approval path. Later Telegram, WhatsApp, OpenClaw, or Hermes bridges should write this same decision format after parsing owner replies.
+
 ### Skill Folder Scan
 
 Command:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@denial-web/clawguard",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Explainable security scanner for OpenClaw-style skills and MCP tool configs.",
   "type": "module",
   "repository": {

package/src/cli.js

@@ -32,7 +32,15 @@ if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
 const commandContext = parseCommand(args);
 const { command, framework, optionValues } = commandContext;
 
-if (!["scan", "scan-workspace", "gate", "install", "approvals-send"].includes(command)) {
+if (![
+  "scan",
+  "scan-workspace",
+  "gate",
+  "install",
+  "approvals-send",
+  "approvals-watch",
+  "approvals-decide"
+].includes(command)) {
   console.error(`Unknown command: ${command}`);
   printHelp();
   process.exit(1);
@@ -50,6 +58,30 @@ try {
     process.exit(0);
   }
 
+  if (command === "approvals-watch") {
+    const watchOptions = parseApprovalWatchOptions(optionValues);
+    const result = await watchApprovals(watchOptions, {
+      onSend: watchOptions.json ? undefined : printApprovalWatchSend
+    });
+    if (watchOptions.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      printApprovalWatchResult(result);
+    }
+    process.exit(0);
+  }
+
+  if (command === "approvals-decide") {
+    const decisionOptions = parseApprovalDecisionOptions(optionValues);
+    const result = await decideApproval(decisionOptions);
+    if (decisionOptions.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      printApprovalDecisionResult(result);
+    }
+    process.exit(0);
+  }
+
   const cliOptions = parseOptions(optionValues);
   cliOptions.framework = framework;
   const loadedConfig = await loadConfig(cliOptions.target, cliOptions.configPath);
@@ -111,6 +143,8 @@ Usage:
   clawguard hermes install <path> --to <dir> [--approval-out <path>]
   clawguard approvals send <approval.json|approvals.jsonl> --via openclaw --channel <name> --target <id>
   clawguard approvals send <approval.json|approvals.jsonl> --via telegram --chat-id <id>
+  clawguard approvals watch <approvals.jsonl> --via telegram --chat-id <id>
+  clawguard approvals decide <approval.json|approvals.jsonl> --id <id> --decision approve|deny
   clawguard scan-workspace <path> [--json] [--policy <preset>]
   npm run scan -- <path>
 
@@ -142,6 +176,14 @@ Options:
   --sender-arg <value>    Extra argument before the generated sender command. Repeatable.
   --bot-token <token>     Telegram bot token. Default: TELEGRAM_BOT_TOKEN.
   --chat-id <id>          Telegram chat id. Alias for --target with --via telegram.
+  --interval <ms>         Approval watch poll interval. Default: 2000.
+  --state <path>          Approval watch sent-id state file.
+  --once                  Run approval watch once and exit.
+  --id <id>               Approval id for send or decide.
+  --decision <value>      Approval decision: approve, deny.
+  --out <path>            Decision JSONL output file.
+  --actor <name>          Decision actor. Default: local-user.
+  --reason <text>         Decision reason.
 
 Gate exit codes:
   0 = allow
@@ -156,6 +198,8 @@ Examples:
   npx @denial-web/clawguard hermes install ./skills/my-skill --to ~/.hermes/skills --approval-out ./.clawguard/approvals.jsonl
   npx @denial-web/clawguard approvals send ./.clawguard/approvals.jsonl --via openclaw --channel telegram --target 123456789
   npx @denial-web/clawguard approvals send ./.clawguard/approvals.jsonl --via telegram --chat-id 123456789
+  npx @denial-web/clawguard approvals watch ./.clawguard/approvals.jsonl --via telegram --chat-id 123456789
+  npx @denial-web/clawguard approvals decide ./.clawguard/approvals.jsonl --id <id> --decision approve
   npm run scan -- examples/risky-skill
   npm run scan -- examples/metadata-mismatch-skill --policy governed --fail-on-policy
   npm run scan -- examples/metadata-mismatch-skill --html clawguard.html
@@ -247,6 +291,22 @@ function parseCommand(values) {
     };
   }
 
+  if (rawCommand === "approvals" && values[1] === "watch") {
+    return {
+      command: "approvals-watch",
+      framework: undefined,
+      optionValues: values.slice(2)
+    };
+  }
+
+  if (rawCommand === "approvals" && values[1] === "decide") {
+    return {
+      command: "approvals-decide",
+      framework: undefined,
+      optionValues: values.slice(2)
+    };
+  }
+
   if (["openclaw", "hermes"].includes(rawCommand)) {
     const nestedCommand = values[1];
 
@@ -282,6 +342,10 @@ function parseCommand(values) {
 
 async function sendApproval(options) {
   const approval = await readApprovalRequest(options.approvalPath, options.id);
+  return sendApprovalRequest(approval, options);
+}
+
+async function sendApprovalRequest(approval, options) {
   const message = String(approval.message ?? "").trim();
 
   if (!message) {
@@ -341,6 +405,113 @@ async function sendApproval(options) {
   return result;
 }
 
+async function watchApprovals(options, hooks = {}) {
+  const statePath = path.resolve(options.statePath ?? `${options.approvalPath}.sent.json`);
+  const persistedIds = await readApprovalWatchState(statePath);
+  const sessionIds = new Set();
+  const result = {
+    approvalPath: path.resolve(options.approvalPath),
+    statePath,
+    once: options.once,
+    intervalMs: options.intervalMs,
+    dryRun: options.dryRun,
+    checked: 0,
+    matched: 0,
+    sent: 0,
+    skipped: 0,
+    deliveries: []
+  };
+
+  do {
+    const approvals = await readApprovalRequestsIfPresent(options.approvalPath);
+    result.checked += approvals.length;
+
+    for (const approval of approvals) {
+      if (approval.status !== "pending") {
+        result.skipped += 1;
+        continue;
+      }
+
+      if (!approval.id) {
+        result.skipped += 1;
+        continue;
+      }
+
+      if (persistedIds.has(approval.id) || sessionIds.has(approval.id)) {
+        result.skipped += 1;
+        continue;
+      }
+
+      result.matched += 1;
+      const delivery = await sendApprovalRequest(approval, options);
+      result.deliveries.push(delivery);
+      sessionIds.add(approval.id);
+
+      if (delivery.sent) {
+        result.sent += 1;
+        persistedIds.add(approval.id);
+        await writeApprovalWatchState(statePath, persistedIds);
+      }
+
+      if (hooks.onSend) {
+        hooks.onSend(delivery);
+      }
+    }
+
+    if (options.once) {
+      return result;
+    }
+
+    await sleep(options.intervalMs);
+  } while (true);
+}
+
+async function decideApproval(options) {
+  const approval = await readApprovalRequest(options.approvalPath, options.id);
+  const outputPath = path.resolve(options.outPath ?? `${options.approvalPath}.decisions.jsonl`);
+  const decision = createApprovalDecision(approval, options);
+
+  await fs.mkdir(path.dirname(outputPath), { recursive: true });
+  await fs.appendFile(outputPath, `${JSON.stringify(decision)}\n`);
+
+  return {
+    approval: {
+      id: approval.id,
+      status: approval.status,
+      decision: approval.decision,
+      risk: approval.risk,
+      framework: approval.framework
+    },
+    outputPath,
+    decision
+  };
+}
+
+function createApprovalDecision(approval, options) {
+  const decision = normalizeApprovalDecision(options.decision);
+  const status = decision === "approve" ? "approved" : "denied";
+
+  return {
+    schemaVersion: "clawguard.decision.v1",
+    id: randomUUID(),
+    approvalId: approval.id,
+    status,
+    decision,
+    decidedAt: new Date().toISOString(),
+    actor: options.actor,
+    reason: options.reason,
+    framework: approval.framework,
+    target: approval.target,
+    destination: approval.destination,
+    risk: approval.risk,
+    policy: approval.policy,
+    source: {
+      path: path.resolve(options.approvalPath),
+      approvalCreatedAt: approval.createdAt
+    }
+  };
+}
+
 async function sendTelegramApproval(approval, message, options) {
   const botToken = options.botToken ?? process.env.TELEGRAM_BOT_TOKEN;
 
@@ -421,12 +592,41 @@ function printApprovalSendResult(result) {
   }
 }
 
+function printApprovalWatchSend(result) {
+  console.log(`ClawGuard approval watch sent: ${result.approval.id}`);
+  console.log(`Via: ${result.via}`);
+  console.log(`Target: ${result.target}`);
+  console.log(`Sent: ${result.sent ? "yes" : "no"}`);
+  if (result.dryRun && result.endpoint) {
+    console.log(`Endpoint: ${result.endpoint}`);
+  }
+}
+
+function printApprovalWatchResult(result) {
+  console.log(`ClawGuard approval watch: ${result.approvalPath}`);
+  console.log(`State: ${result.statePath}`);
+  console.log(`Once: ${result.once ? "yes" : "no"}`);
+  console.log(`Dry run: ${result.dryRun ? "yes" : "no"}`);
+  console.log(`Checked: ${result.checked}`);
+  console.log(`Matched pending: ${result.matched}`);
+  console.log(`Sent: ${result.sent}`);
+  console.log(`Skipped: ${result.skipped}`);
+}
+
+function printApprovalDecisionResult(result) {
+  console.log(`ClawGuard approval decision: ${result.approval.id}`);
+  console.log(`Decision: ${formatDecision(result.decision.decision)}`);
+  console.log(`Status: ${result.decision.status}`);
+  console.log(`Actor: ${result.decision.actor}`);
+  if (result.decision.reason) {
+    console.log(`Reason: ${result.decision.reason}`);
+  }
+  console.log(`Output: ${result.outputPath}`);
+}
+
 async function readApprovalRequest(approvalPath, id) {
   const resolvedPath = path.resolve(approvalPath);
-  const content = await fs.readFile(resolvedPath, "utf8");
-  const approvals = resolvedPath.endsWith(".jsonl")
-    ? content.split(/\r?\n/).filter(Boolean).map((line) => JSON.parse(line))
-    : [JSON.parse(content)];
+  const approvals = await readApprovalRequests(resolvedPath);
 
   if (approvals.length === 0) {
     throw new Error(`No approval requests found in ${resolvedPath}`);
@@ -447,6 +647,59 @@ async function readApprovalRequest(approvalPath, id) {
   return approval;
 }
 
+async function readApprovalRequestsIfPresent(approvalPath) {
+  const resolvedPath = path.resolve(approvalPath);
+
+  try {
+    return await readApprovalRequests(resolvedPath);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return [];
+    }
+
+    throw error;
+  }
+}
+
+async function readApprovalRequests(resolvedPath) {
+  const content = await fs.readFile(resolvedPath, "utf8");
+  const approvals = resolvedPath.endsWith(".jsonl")
+    ? content.split(/\r?\n/).filter(Boolean).map((line) => JSON.parse(line))
+    : [JSON.parse(content)];
+
+  for (const approval of approvals) {
+    if (approval.schemaVersion !== "clawguard.approval.v1") {
+      throw new Error("Unsupported approval request schema.");
+    }
+  }
+
+  return approvals;
+}
+
+async function readApprovalWatchState(statePath) {
+  try {
+    const content = await fs.readFile(statePath, "utf8");
+    const state = JSON.parse(content);
+    const ids = Array.isArray(state) ? state : state.sentIds;
+    return new Set(Array.isArray(ids) ? ids : []);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return new Set();
+    }
+
+    throw error;
+  }
+}
+
+async function writeApprovalWatchState(statePath, sentIds) {
+  await fs.mkdir(path.dirname(statePath), { recursive: true });
+  await fs.writeFile(statePath, `${JSON.stringify({
+    schemaVersion: "clawguard.approval-watch-state.v1",
+    updatedAt: new Date().toISOString(),
+    sentIds: [...sentIds].sort()
+  }, null, 2)}\n`);
+}
+
 function printGateResult(result, options) {
   const decision = result.policy.decision;
   console.log(`ClawGuard gate: ${result.target}`);
@@ -761,6 +1014,18 @@ async function assertDestinationAvailable(destination) {
 }
 
 function commandLabel(commandName) {
+  if (commandName === "approvals-send") {
+    return "Approval send";
+  }
+
+  if (commandName === "approvals-watch") {
+    return "Approval watch";
+  }
+
+  if (commandName === "approvals-decide") {
+    return "Approval decision";
+  }
+
   if (commandName === "gate") {
     return "Gate";
   }
@@ -801,6 +1066,24 @@ function redactTelegramToken(value) {
   return String(value).replace(/\/bot[^/]+\/sendMessage$/, "/bot<redacted>/sendMessage");
 }
 
+function sleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+function normalizeApprovalDecision(value) {
+  if (value === "approved") {
+    return "approve";
+  }
+
+  if (value === "denied") {
+    return "deny";
+  }
+
+  return value;
+}
+
 function gateExitCode(decision) {
   if (decision === "allow") {
     return 0;
@@ -1079,6 +1362,224 @@ function parseApprovalSendOptions(values) {
   return options;
 }
 
+function parseApprovalWatchOptions(values) {
+  const options = {
+    approvalPath: undefined,
+    via: "telegram",
+    channel: undefined,
+    target: undefined,
+    chatId: undefined,
+    botToken: undefined,
+    telegramApiBase: undefined,
+    senderBin: undefined,
+    senderArgs: [],
+    dryRun: false,
+    json: false,
+    once: false,
+    intervalMs: 2000,
+    statePath: undefined
+  };
+  const paths = [];
+
+  for (let index = 0; index < values.length; index += 1) {
+    const value = values[index];
+
+    if (value === "--json") {
+      options.json = true;
+      continue;
+    }
+
+    if (value === "--dry-run") {
+      options.dryRun = true;
+      continue;
+    }
+
+    if (value === "--once") {
+      options.once = true;
+      continue;
+    }
+
+    if (value === "--interval") {
+      const interval = Number.parseInt(requireNextValue(values, index, "--interval"), 10);
+      if (!Number.isSafeInteger(interval) || interval < 250) {
+        throw new Error("--interval must be an integer of at least 250 milliseconds.");
+      }
+      options.intervalMs = interval;
+      index += 1;
+      continue;
+    }
+
+    if (value === "--state") {
+      options.statePath = requireNextValue(values, index, "--state");
+      index += 1;
+      continue;
+    }
+
+    if (value === "--via") {
+      options.via = requireNextValue(values, index, "--via");
+      index += 1;
+      continue;
+    }
+
+    if (value === "--channel") {
+      options.channel = requireNextValue(values, index, "--channel");
+      index += 1;
+      continue;
+    }
+
+    if (value === "--target") {
+      options.target = requireNextValue(values, index, "--target");
+      index += 1;
+      continue;
+    }
+
+    if (value === "--chat-id") {
+      options.chatId = requireNextValue(values, index, "--chat-id");
+      index += 1;
+      continue;
+    }
+
+    if (value === "--bot-token") {
+      options.botToken = requireNextValue(values, index, "--bot-token");
+      index += 1;
+      continue;
+    }
+
+    if (value === "--telegram-api-base") {
+      options.telegramApiBase = requireNextValue(values, index, "--telegram-api-base");
+      index += 1;
+      continue;
+    }
+
+    if (value === "--sender-bin") {
+      options.senderBin = requireNextValue(values, index, "--sender-bin");
+      index += 1;
+      continue;
+    }
+
+    if (value === "--sender-arg") {
+      options.senderArgs.push(requireNextValue(values, index, "--sender-arg"));
+      index += 1;
+      continue;
+    }
+
+    if (value.startsWith("--")) {
+      throw new Error(`Unknown option: ${value}`);
+    }
+
+    paths.push(value);
+  }
+
+  options.approvalPath = paths[0];
+
+  if (!options.approvalPath) {
+    throw new Error("approvals watch requires <approval.jsonl>.");
+  }
+
+  if (!["openclaw", "telegram"].includes(options.via)) {
+    throw new Error("Invalid --via value. Use one of: openclaw, telegram");
+  }
+
+  if (options.via === "openclaw" && !options.channel) {
+    throw new Error("approvals watch --via openclaw requires --channel <name>.");
+  }
+
+  if (options.via === "openclaw" && !options.target) {
+    throw new Error("approvals watch --via openclaw requires --target <id>.");
+  }
+
+  if (options.via === "telegram") {
+    options.chatId = options.chatId ?? options.target;
+    if (!options.chatId) {
+      throw new Error("approvals watch --via telegram requires --chat-id <id>.");
+    }
+    options.channel = "telegram";
+    options.target = options.chatId;
+  }
+
+  return options;
+}
+
+function parseApprovalDecisionOptions(values) {
+  const options = {
+    approvalPath: undefined,
+    id: undefined,
+    decision: undefined,
+    outPath: undefined,
+    actor: "local-user",
+    reason: undefined,
+    json: false
+  };
+  const paths = [];
+
+  for (let index = 0; index < values.length; index += 1) {
+    const value = values[index];
+
+    if (value === "--json") {
+      options.json = true;
+      continue;
+    }
+
+    if (value === "--id") {
+      options.id = requireNextValue(values, index, "--id");
+      index += 1;
+      continue;
+    }
+
+    if (value === "--decision") {
+      options.decision = requireNextValue(values, index, "--decision");
+      index += 1;
+      continue;
+    }
+
+    if (value === "--out") {
+      options.outPath = requireNextValue(values, index, "--out");
+      index += 1;
+      continue;
+    }
+
+    if (value === "--actor") {
+      options.actor = requireNextValue(values, index, "--actor");
+      index += 1;
+      continue;
+    }
+
+    if (value === "--reason") {
+      options.reason = requireNextValue(values, index, "--reason");
+      index += 1;
+      continue;
+    }
+
+    if (value.startsWith("--")) {
+      throw new Error(`Unknown option: ${value}`);
+    }
+
+    paths.push(value);
+  }
+
+  options.approvalPath = paths[0];
+
+  if (!options.approvalPath) {
+    throw new Error("approvals decide requires <approval.json|approvals.jsonl>.");
+  }
+
+  if (!options.id) {
+    throw new Error("approvals decide requires --id <id>.");
+  }
+
+  if (!options.decision) {
+    throw new Error("approvals decide requires --decision approve|deny.");
+  }
+
+  options.decision = normalizeApprovalDecision(options.decision);
+
+  if (!["approve", "deny"].includes(options.decision)) {
+    throw new Error("Invalid --decision value. Use one of: approve, deny");
+  }
+
+  return options;
+}
+
 async function writeReportFile(outputPath, content) {
   const resolvedPath = path.resolve(outputPath);
   await fs.mkdir(path.dirname(resolvedPath), { recursive: true });