@denial-web/clawguard 0.1.8 → 0.1.10

package/README.md

@@ -92,6 +92,28 @@ Use `--once --dry-run` to verify the message flow without sending anything:
 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
+```
+
+To turn Telegram replies into decision records, ask the owner to reply with one of:
+
+```text
+approve <approval-id> optional reason
+deny <approval-id> optional reason
+```
+
+Then poll Telegram updates:
+
+```bash
+TELEGRAM_BOT_TOKEN=123456:token npx @denial-web/clawguard approvals poll-telegram ./.clawguard/approvals.jsonl --decisions ./.clawguard/decisions.jsonl
+```
+
+The poller records the Telegram update offset in `./.clawguard/decisions.jsonl.telegram-state.json` by default so the same reply is not processed again.
+
 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

@@ -78,6 +78,39 @@ TELEGRAM_BOT_TOKEN=123456:token clawguard approvals watch ./.clawguard/approvals
 
 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.
+
+### Telegram Reply Polling
+
+The first reply bridge is Telegram polling. Owners can respond to the approval message with:
+
+```text
+approve <approval-id> optional reason
+deny <approval-id> optional reason
+```
+
+Command:
+
+```bash
+TELEGRAM_BOT_TOKEN=123456:token clawguard approvals poll-telegram ./.clawguard/approvals.jsonl \
+  --decisions ./.clawguard/decisions.jsonl
+```
+
+The poller calls Telegram `getUpdates`, parses approval commands, looks up the referenced approval request, and appends a `clawguard.decision.v1` decision. It records the next Telegram update offset in `./.clawguard/decisions.jsonl.telegram-state.json` by default. For tests and offline replay, `--telegram-updates-file <path>` can read a captured Telegram-style update payload instead of calling the Telegram API.
+
 ### Skill Folder Scan
 
 Command:

package/package.json

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

package/src/cli.js

@@ -32,7 +32,16 @@ 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", "approvals-watch"].includes(command)) {
+if (![
+  "scan",
+  "scan-workspace",
+  "gate",
+  "install",
+  "approvals-send",
+  "approvals-watch",
+  "approvals-decide",
+  "approvals-poll-telegram"
+].includes(command)) {
   console.error(`Unknown command: ${command}`);
   printHelp();
   process.exit(1);
@@ -63,6 +72,28 @@ try {
     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);
+  }
+
+  if (command === "approvals-poll-telegram") {
+    const pollOptions = parseApprovalTelegramPollOptions(optionValues);
+    const result = await pollTelegramApprovals(pollOptions);
+    if (pollOptions.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      printApprovalTelegramPollResult(result);
+    }
+    process.exit(0);
+  }
+
   const cliOptions = parseOptions(optionValues);
   cliOptions.framework = framework;
   const loadedConfig = await loadConfig(cliOptions.target, cliOptions.configPath);
@@ -125,6 +156,8 @@ Usage:
   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 approvals poll-telegram <approvals.jsonl> --decisions <decisions.jsonl>
   clawguard scan-workspace <path> [--json] [--policy <preset>]
   npm run scan -- <path>
 
@@ -159,6 +192,15 @@ Options:
   --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.
+  --decisions <path>      Decision JSONL output file for reply polling.
+  --actor <name>          Decision actor. Default: local-user.
+  --reason <text>         Decision reason.
+  --offset-state <path>   Telegram update offset state file.
+  --telegram-updates-file <path>
+                          Read Telegram updates from a JSON file for tests or offline replay.
 
 Gate exit codes:
   0 = allow
@@ -174,6 +216,8 @@ Examples:
   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
+  npx @denial-web/clawguard approvals poll-telegram ./.clawguard/approvals.jsonl --decisions ./.clawguard/decisions.jsonl
   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
@@ -273,6 +317,22 @@ function parseCommand(values) {
     };
   }
 
+  if (rawCommand === "approvals" && values[1] === "decide") {
+    return {
+      command: "approvals-decide",
+      framework: undefined,
+      optionValues: values.slice(2)
+    };
+  }
+
+  if (rawCommand === "approvals" && values[1] === "poll-telegram") {
+    return {
+      command: "approvals-poll-telegram",
+      framework: undefined,
+      optionValues: values.slice(2)
+    };
+  }
+
   if (["openclaw", "hermes"].includes(rawCommand)) {
     const nestedCommand = values[1];
 
@@ -432,6 +492,200 @@ async function watchApprovals(options, hooks = {}) {
   } 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 appendApprovalDecision(outputPath, decision);
+
+  return {
+    approval: {
+      id: approval.id,
+      status: approval.status,
+      decision: approval.decision,
+      risk: approval.risk,
+      framework: approval.framework
+    },
+    outputPath,
+    decision
+  };
+}
+
+async function appendApprovalDecision(outputPath, decision) {
+  await fs.mkdir(path.dirname(outputPath), { recursive: true });
+  await fs.appendFile(outputPath, `${JSON.stringify(decision)}\n`);
+}
+
+async function pollTelegramApprovals(options) {
+  const offsetStatePath = path.resolve(options.offsetStatePath ?? `${options.decisionsPath}.telegram-state.json`);
+  const offset = await readTelegramOffsetState(offsetStatePath);
+  const updates = await fetchTelegramUpdates(options, offset);
+  const outputPath = path.resolve(options.decisionsPath);
+  const result = {
+    approvalPath: path.resolve(options.approvalPath),
+    decisionsPath: outputPath,
+    offsetStatePath,
+    dryRun: options.dryRun,
+    checked: updates.length,
+    commands: 0,
+    decided: 0,
+    skipped: 0,
+    errors: [],
+    decisions: [],
+    nextOffset: offset
+  };
+
+  for (const update of updates) {
+    const parsed = parseTelegramApprovalUpdate(update);
+
+    if (!parsed) {
+      result.skipped += 1;
+      result.nextOffset = nextTelegramOffset(result.nextOffset, update.update_id);
+      continue;
+    }
+
+    result.commands += 1;
+    result.nextOffset = nextTelegramOffset(result.nextOffset, update.update_id);
+
+    try {
+      const approval = await readApprovalRequest(options.approvalPath, parsed.approvalId);
+      const decision = createApprovalDecision(approval, {
+        approvalPath: options.approvalPath,
+        decision: parsed.decision,
+        actor: parsed.actor,
+        reason: parsed.reason
+      });
+      result.decisions.push(decision);
+
+      if (!options.dryRun) {
+        await appendApprovalDecision(outputPath, decision);
+        result.decided += 1;
+      }
+    } catch (error) {
+      result.errors.push({
+        updateId: update.update_id,
+        approvalId: parsed.approvalId,
+        message: error.message
+      });
+    }
+  }
+
+  if (!options.dryRun && result.nextOffset !== offset) {
+    await writeTelegramOffsetState(offsetStatePath, result.nextOffset);
+  }
+
+  return result;
+}
+
+async function fetchTelegramUpdates(options, offset) {
+  if (options.telegramUpdatesPath) {
+    const content = await fs.readFile(path.resolve(options.telegramUpdatesPath), "utf8");
+    const payload = JSON.parse(content);
+    const updates = Array.isArray(payload) ? payload : payload.result;
+
+    if (!Array.isArray(updates)) {
+      throw new Error("Telegram updates file must be an array or an object with a result array.");
+    }
+
+    return updates.filter((update) => !offset || !Number.isSafeInteger(update.update_id) || update.update_id >= offset);
+  }
+
+  const botToken = options.botToken ?? process.env.TELEGRAM_BOT_TOKEN;
+
+  if (!botToken) {
+    throw new Error("Telegram poll requires --bot-token or TELEGRAM_BOT_TOKEN.");
+  }
+
+  const apiBase = options.telegramApiBase ?? "https://api.telegram.org";
+  const endpoint = new URL(`${apiBase.replace(/\/$/, "")}/bot${botToken}/getUpdates`);
+  endpoint.searchParams.set("timeout", String(options.timeoutSeconds));
+
+  if (offset) {
+    endpoint.searchParams.set("offset", String(offset));
+  }
+
+  const response = await fetch(endpoint);
+  const text = await response.text();
+  let payload;
+
+  try {
+    payload = text ? JSON.parse(text) : null;
+  } catch {
+    throw new Error(`Telegram poll returned invalid JSON: ${text}`);
+  }
+
+  if (!response.ok || payload?.ok === false) {
+    throw new Error(`Telegram poll failed with HTTP ${response.status}: ${text}`);
+  }
+
+  if (!Array.isArray(payload?.result)) {
+    throw new Error("Telegram poll response did not include a result array.");
+  }
+
+  return payload.result;
+}
+
+function parseTelegramApprovalUpdate(update) {
+  const message = update.message ?? update.edited_message ?? update.channel_post;
+  const text = message?.text;
+
+  if (!text) {
+    return undefined;
+  }
+
+  const match = text.trim().match(/^\/?(approve|approved|deny|denied)\s+([A-Za-z0-9_.:@-]+)(?:\s+(.+))?$/i);
+
+  if (!match) {
+    return undefined;
+  }
+
+  const decision = normalizeApprovalDecision(match[1].toLowerCase());
+  const actorName = message.from?.username ?? message.from?.id ?? message.chat?.username ?? message.chat?.id ?? "telegram-user";
+  const reason = match[3]?.trim();
+
+  return {
+    updateId: update.update_id,
+    approvalId: match[2],
+    decision,
+    actor: `telegram:${actorName}`,
+    reason
+  };
+}
+
+function nextTelegramOffset(currentOffset, updateId) {
+  if (!Number.isSafeInteger(updateId)) {
+    return currentOffset;
+  }
+
+  return Math.max(currentOffset ?? 0, updateId + 1);
+}
+
+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;
 
@@ -533,6 +787,36 @@ function printApprovalWatchResult(result) {
   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}`);
+}
+
+function printApprovalTelegramPollResult(result) {
+  console.log(`ClawGuard Telegram approval poll: ${result.approvalPath}`);
+  console.log(`Decisions: ${result.decisionsPath}`);
+  console.log(`Offset state: ${result.offsetStatePath}`);
+  console.log(`Dry run: ${result.dryRun ? "yes" : "no"}`);
+  console.log(`Updates checked: ${result.checked}`);
+  console.log(`Commands found: ${result.commands}`);
+  console.log(`Decisions written: ${result.decided}`);
+  console.log(`Skipped: ${result.skipped}`);
+  console.log(`Next offset: ${result.nextOffset ?? "none"}`);
+
+  if (result.errors.length > 0) {
+    console.log("Errors:");
+    for (const error of result.errors) {
+      console.log(`- update ${error.updateId}: ${error.message}`);
+    }
+  }
+}
+
 async function readApprovalRequest(approvalPath, id) {
   const resolvedPath = path.resolve(approvalPath);
   const approvals = await readApprovalRequests(resolvedPath);
@@ -609,6 +893,29 @@ async function writeApprovalWatchState(statePath, sentIds) {
   }, null, 2)}\n`);
 }
 
+async function readTelegramOffsetState(statePath) {
+  try {
+    const content = await fs.readFile(statePath, "utf8");
+    const state = JSON.parse(content);
+    return Number.isSafeInteger(state.nextOffset) ? state.nextOffset : undefined;
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return undefined;
+    }
+
+    throw error;
+  }
+}
+
+async function writeTelegramOffsetState(statePath, nextOffset) {
+  await fs.mkdir(path.dirname(statePath), { recursive: true });
+  await fs.writeFile(statePath, `${JSON.stringify({
+    schemaVersion: "clawguard.telegram-offset.v1",
+    updatedAt: new Date().toISOString(),
+    nextOffset
+  }, null, 2)}\n`);
+}
+
 function printGateResult(result, options) {
   const decision = result.policy.decision;
   console.log(`ClawGuard gate: ${result.target}`);
@@ -931,6 +1238,14 @@ function commandLabel(commandName) {
     return "Approval watch";
   }
 
+  if (commandName === "approvals-decide") {
+    return "Approval decision";
+  }
+
+  if (commandName === "approvals-poll-telegram") {
+    return "Telegram approval poll";
+  }
+
   if (commandName === "gate") {
     return "Gate";
   }
@@ -977,6 +1292,18 @@ function sleep(ms) {
   });
 }
 
+function normalizeApprovalDecision(value) {
+  if (value === "approved") {
+    return "approve";
+  }
+
+  if (value === "denied") {
+    return "deny";
+  }
+
+  return value;
+}
+
 function gateExitCode(decision) {
   if (decision === "allow") {
     return 0;
@@ -1393,6 +1720,179 @@ function parseApprovalWatchOptions(values) {
   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;
+}
+
+function parseApprovalTelegramPollOptions(values) {
+  const options = {
+    approvalPath: undefined,
+    decisionsPath: undefined,
+    offsetStatePath: undefined,
+    botToken: undefined,
+    telegramApiBase: undefined,
+    telegramUpdatesPath: undefined,
+    timeoutSeconds: 0,
+    dryRun: false,
+    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 === "--dry-run") {
+      options.dryRun = true;
+      continue;
+    }
+
+    if (value === "--decisions") {
+      options.decisionsPath = requireNextValue(values, index, "--decisions");
+      index += 1;
+      continue;
+    }
+
+    if (value === "--out") {
+      options.decisionsPath = requireNextValue(values, index, "--out");
+      index += 1;
+      continue;
+    }
+
+    if (value === "--offset-state") {
+      options.offsetStatePath = requireNextValue(values, index, "--offset-state");
+      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 === "--telegram-updates-file") {
+      options.telegramUpdatesPath = requireNextValue(values, index, "--telegram-updates-file");
+      index += 1;
+      continue;
+    }
+
+    if (value === "--timeout") {
+      const timeout = Number.parseInt(requireNextValue(values, index, "--timeout"), 10);
+      if (!Number.isSafeInteger(timeout) || timeout < 0) {
+        throw new Error("--timeout must be a non-negative integer.");
+      }
+      options.timeoutSeconds = timeout;
+      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 poll-telegram requires <approval.json|approvals.jsonl>.");
+  }
+
+  if (!options.decisionsPath) {
+    throw new Error("approvals poll-telegram requires --decisions <path>.");
+  }
+
+  return options;
+}
+
 async function writeReportFile(outputPath, content) {
   const resolvedPath = path.resolve(outputPath);
   await fs.mkdir(path.dirname(resolvedPath), { recursive: true });