@denial-web/clawguard 0.1.9 → 0.1.11

package/README.md

@@ -99,6 +99,29 @@ npx @denial-web/clawguard approvals decide ./.clawguard/approvals.jsonl --id <ap
 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.
+
+Apply the recorded decision to continue or block the pending install:
+
+```bash
+npx @denial-web/clawguard approvals apply ./.clawguard/approvals.jsonl --id <approval-id> --decisions ./.clawguard/decisions.jsonl
+```
+
+If the latest decision is `approve`, ClawGuard copies the original scanned source to the original approved destination. If the latest decision is `deny`, it exits blocked without copying. If no decision exists yet, it stays paused.
+
 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

@@ -93,6 +93,42 @@ clawguard approvals decide ./.clawguard/approvals.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.
+
+### Approval Apply
+
+After a decision is recorded, ClawGuard can apply that decision to the original pending install:
+
+```bash
+clawguard approvals apply ./.clawguard/approvals.jsonl \
+  --id <approval-id> \
+  --decisions ./.clawguard/decisions.jsonl
+```
+
+Apply behavior:
+
+- If the latest matching decision is `approve`, copy the original scanned `target` to the original approval `destination`.
+- If the latest matching decision is `deny`, exit blocked and copy nothing.
+- If no matching decision exists, exit paused and copy nothing.
+- Never execute the skill or install dependencies during apply.
+- Refuse symlinked install sources and existing destinations, matching normal install safety.
+
 ### Skill Folder Scan
 
 Command:

package/package.json

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

package/src/cli.js

@@ -39,7 +39,9 @@ if (![
   "install",
   "approvals-send",
   "approvals-watch",
-  "approvals-decide"
+  "approvals-decide",
+  "approvals-poll-telegram",
+  "approvals-apply"
 ].includes(command)) {
   console.error(`Unknown command: ${command}`);
   printHelp();
@@ -82,6 +84,28 @@ try {
     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);
+  }
+
+  if (command === "approvals-apply") {
+    const applyOptions = parseApprovalApplyOptions(optionValues);
+    const result = await applyApprovalDecision(applyOptions);
+    if (applyOptions.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      printApprovalApplyResult(result);
+    }
+    process.exit(approvalApplyExitCode(result));
+  }
+
   const cliOptions = parseOptions(optionValues);
   cliOptions.framework = framework;
   const loadedConfig = await loadConfig(cliOptions.target, cliOptions.configPath);
@@ -145,6 +169,8 @@ Usage:
   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 approvals apply <approvals.jsonl> --id <id> --decisions <decisions.jsonl>
   clawguard scan-workspace <path> [--json] [--policy <preset>]
   npm run scan -- <path>
 
@@ -182,8 +208,12 @@ Options:
   --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
@@ -200,6 +230,8 @@ Examples:
   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
+  npx @denial-web/clawguard approvals apply ./.clawguard/approvals.jsonl --id <id> --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
@@ -307,6 +339,22 @@ function parseCommand(values) {
     };
   }
 
+  if (rawCommand === "approvals" && values[1] === "poll-telegram") {
+    return {
+      command: "approvals-poll-telegram",
+      framework: undefined,
+      optionValues: values.slice(2)
+    };
+  }
+
+  if (rawCommand === "approvals" && values[1] === "apply") {
+    return {
+      command: "approvals-apply",
+      framework: undefined,
+      optionValues: values.slice(2)
+    };
+  }
+
   if (["openclaw", "hermes"].includes(rawCommand)) {
     const nestedCommand = values[1];
 
@@ -471,8 +519,7 @@ async function decideApproval(options) {
   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`);
+  await appendApprovalDecision(outputPath, decision);
 
   return {
     approval: {
@@ -487,6 +534,246 @@ async function decideApproval(options) {
   };
 }
 
+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 applyApprovalDecision(options) {
+  const approval = await readApprovalRequest(options.approvalPath, options.id);
+  const decisionsPath = path.resolve(options.decisionsPath ?? `${options.approvalPath}.decisions.jsonl`);
+  const decision = await readLatestApprovalDecision(decisionsPath, approval.id);
+  const result = {
+    approval: {
+      id: approval.id,
+      status: approval.status,
+      decision: approval.decision,
+      risk: approval.risk,
+      framework: approval.framework
+    },
+    decision,
+    decisionsPath,
+    source: approval.target ? path.resolve(approval.target) : undefined,
+    destination: approval.destination ? path.resolve(approval.destination) : undefined,
+    dryRun: options.dryRun,
+    installed: false,
+    skipped: true,
+    reason: undefined
+  };
+
+  if (!decision) {
+    result.reason = "No decision has been recorded for this approval.";
+    return result;
+  }
+
+  if (decision.decision !== "approve") {
+    result.reason = decision.reason ?? "Approval was denied.";
+    return result;
+  }
+
+  if (!result.source) {
+    throw new Error("Approval request has no target path to install.");
+  }
+
+  if (!result.destination) {
+    throw new Error("Approval request has no destination path to install.");
+  }
+
+  if (options.dryRun) {
+    result.skipped = false;
+    result.reason = "Dry run passed; no files were copied.";
+    return result;
+  }
+
+  await assertInstallableSource(result.source);
+  await assertDestinationAvailable(result.destination);
+  await fs.mkdir(path.dirname(result.destination), { recursive: true });
+  await fs.cp(result.source, result.destination, {
+    recursive: true,
+    errorOnExist: true,
+    force: false,
+    verbatimSymlinks: true
+  });
+
+  result.installed = true;
+  result.skipped = false;
+  result.reason = "Copied after recorded approval.";
+  return result;
+}
+
+async function readLatestApprovalDecision(decisionsPath, approvalId) {
+  let decisions;
+
+  try {
+    decisions = await readApprovalDecisions(decisionsPath);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return undefined;
+    }
+
+    throw error;
+  }
+
+  return decisions.filter((decision) => decision.approvalId === approvalId).at(-1);
+}
+
+async function readApprovalDecisions(decisionsPath) {
+  const content = await fs.readFile(decisionsPath, "utf8");
+  const decisions = content.split(/\r?\n/).filter(Boolean).map((line) => JSON.parse(line));
+
+  for (const decision of decisions) {
+    if (decision.schemaVersion !== "clawguard.decision.v1") {
+      throw new Error("Unsupported approval decision schema.");
+    }
+  }
+
+  return decisions;
+}
+
+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";
@@ -624,6 +911,36 @@ function printApprovalDecisionResult(result) {
   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}`);
+    }
+  }
+}
+
+function printApprovalApplyResult(result) {
+  console.log(`ClawGuard approval apply: ${result.approval.id}`);
+  console.log(`Decision: ${result.decision ? formatDecision(result.decision.decision) : "PENDING"}`);
+  console.log(`Source: ${result.source ?? "not recorded"}`);
+  console.log(`Destination: ${result.destination ?? "not recorded"}`);
+  console.log(`Dry run: ${result.dryRun ? "yes" : "no"}`);
+  console.log(`Installed: ${result.installed ? "yes" : "no"}`);
+  console.log(`Exit code: ${approvalApplyExitCode(result)}`);
+  console.log(`Reason: ${result.reason}`);
+}
+
 async function readApprovalRequest(approvalPath, id) {
   const resolvedPath = path.resolve(approvalPath);
   const approvals = await readApprovalRequests(resolvedPath);
@@ -700,6 +1017,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}`);
@@ -1026,6 +1366,14 @@ function commandLabel(commandName) {
     return "Approval decision";
   }
 
+  if (commandName === "approvals-poll-telegram") {
+    return "Telegram approval poll";
+  }
+
+  if (commandName === "approvals-apply") {
+    return "Approval apply";
+  }
+
   if (commandName === "gate") {
     return "Gate";
   }
@@ -1104,6 +1452,18 @@ function installExitCode(decision, install) {
   return gateExitCode(decision);
 }
 
+function approvalApplyExitCode(result) {
+  if (!result.decision) {
+    return 1;
+  }
+
+  if (result.decision.decision !== "approve") {
+    return 2;
+  }
+
+  return 0;
+}
+
 function parseOptions(values) {
   const options = {
     json: false,
@@ -1580,6 +1940,160 @@ function parseApprovalDecisionOptions(values) {
   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;
+}
+
+function parseApprovalApplyOptions(values) {
+  const options = {
+    approvalPath: undefined,
+    id: undefined,
+    decisionsPath: undefined,
+    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 === "--id") {
+      options.id = requireNextValue(values, index, "--id");
+      index += 1;
+      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.startsWith("--")) {
+      throw new Error(`Unknown option: ${value}`);
+    }
+
+    paths.push(value);
+  }
+
+  options.approvalPath = paths[0];
+
+  if (!options.approvalPath) {
+    throw new Error("approvals apply requires <approval.json|approvals.jsonl>.");
+  }
+
+  if (!options.id) {
+    throw new Error("approvals apply requires --id <id>.");
+  }
+
+  return options;
+}
+
 async function writeReportFile(outputPath, content) {
   const resolvedPath = path.resolve(outputPath);
   await fs.mkdir(path.dirname(resolvedPath), { recursive: true });