@denial-web/clawguard 0.1.10 → 0.1.12

package/README.md

@@ -68,6 +68,14 @@ npx @denial-web/clawguard hermes install ./candidate-skill --to ~/.hermes/skills
 
 The approval JSONL payload is designed for a bot or daemon to forward to WhatsApp, Telegram, Slack, Discord, or another owner channel before any files are copied into a trusted skill folder.
 
+Check the approval setup and print the exact command flow:
+
+```bash
+npx @denial-web/clawguard approvals doctor --chat-id 123456789
+```
+
+Use `--framework hermes` to print Hermes install commands, or `--check-telegram` when you want ClawGuard to call Telegram `getMe` and verify the bot token.
+
 If OpenClaw already has messaging configured, ClawGuard can hand the approval message to OpenClaw:
 
 ```bash
@@ -114,6 +122,14 @@ TELEGRAM_BOT_TOKEN=123456:token npx @denial-web/clawguard approvals poll-telegra
 
 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

@@ -78,6 +78,17 @@ 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 Doctor
+
+Before wiring a real agent into the approval loop, users can run:
+
+```bash
+clawguard approvals doctor \
+  --chat-id 123456789
+```
+
+The doctor checks local runtime readiness, writable approval and decision paths, install destination writability, Telegram token presence, and Telegram chat id presence. It does not call Telegram by default. With `--check-telegram`, it calls Telegram `getMe` to verify the configured bot token. The command prints suggested guarded install, watcher, poller, and apply commands for OpenClaw by default; `--framework hermes` switches the guarded install example to Hermes.
+
 ### 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:
@@ -111,6 +122,24 @@ TELEGRAM_BOT_TOKEN=123456:token clawguard approvals poll-telegram ./.clawguard/a
 
 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.10",
+  "version": "0.1.12",
   "description": "Explainable security scanner for OpenClaw-style skills and MCP tool configs.",
   "type": "module",
   "repository": {

package/src/cli.js

@@ -40,7 +40,9 @@ if (![
   "approvals-send",
   "approvals-watch",
   "approvals-decide",
-  "approvals-poll-telegram"
+  "approvals-poll-telegram",
+  "approvals-apply",
+  "approvals-doctor"
 ].includes(command)) {
   console.error(`Unknown command: ${command}`);
   printHelp();
@@ -94,6 +96,28 @@ try {
     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));
+  }
+
+  if (command === "approvals-doctor") {
+    const doctorOptions = parseApprovalDoctorOptions(optionValues);
+    const result = await runApprovalDoctor(doctorOptions);
+    if (doctorOptions.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      printApprovalDoctorResult(result);
+    }
+    process.exit(result.ok ? 0 : 1);
+  }
+
   const cliOptions = parseOptions(optionValues);
   cliOptions.framework = framework;
   const loadedConfig = await loadConfig(cliOptions.target, cliOptions.configPath);
@@ -158,6 +182,8 @@ Usage:
   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 approvals doctor [--chat-id <id>]
   clawguard scan-workspace <path> [--json] [--policy <preset>]
   npm run scan -- <path>
 
@@ -201,6 +227,8 @@ Options:
   --offset-state <path>   Telegram update offset state file.
   --telegram-updates-file <path>
                           Read Telegram updates from a JSON file for tests or offline replay.
+  --check-telegram        In approvals doctor, call Telegram getMe to verify the bot token.
+  --framework <name>      In approvals doctor, show openclaw or hermes commands. Default: openclaw.
 
 Gate exit codes:
   0 = allow
@@ -218,6 +246,8 @@ Examples:
   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
+  npx @denial-web/clawguard approvals doctor --chat-id 123456789
   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
@@ -333,6 +363,22 @@ function parseCommand(values) {
     };
   }
 
+  if (rawCommand === "approvals" && values[1] === "apply") {
+    return {
+      command: "approvals-apply",
+      framework: undefined,
+      optionValues: values.slice(2)
+    };
+  }
+
+  if (rawCommand === "approvals" && values[1] === "doctor") {
+    return {
+      command: "approvals-doctor",
+      framework: undefined,
+      optionValues: values.slice(2)
+    };
+  }
+
   if (["openclaw", "hermes"].includes(rawCommand)) {
     const nestedCommand = values[1];
 
@@ -578,6 +624,300 @@ async function pollTelegramApprovals(options) {
   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 runApprovalDoctor(options) {
+  const approvalPath = path.resolve(options.approvalPath);
+  const decisionsPath = path.resolve(options.decisionsPath);
+  const installDir = path.resolve(options.installDir);
+  const target = options.target;
+  const token = options.botToken ?? process.env.TELEGRAM_BOT_TOKEN;
+  const checks = [
+    checkNodeVersion(),
+    {
+      id: "approval-path-format",
+      status: approvalPath.endsWith(".jsonl") ? "pass" : "warn",
+      message: approvalPath.endsWith(".jsonl")
+        ? "Approval queue uses JSONL."
+        : "Approval queue is not .jsonl; JSONL is recommended for watcher integrations.",
+      detail: approvalPath
+    },
+    {
+      id: "telegram-token",
+      status: token ? "pass" : "warn",
+      message: token
+        ? "Telegram bot token is configured."
+        : "Telegram bot token is not configured. Set TELEGRAM_BOT_TOKEN or pass --bot-token.",
+      detail: token ? "present" : "missing"
+    },
+    {
+      id: "telegram-chat",
+      status: options.chatId ? "pass" : "warn",
+      message: options.chatId
+        ? "Telegram chat id is configured."
+        : "Telegram chat id is missing. Pass --chat-id before running the watcher.",
+      detail: options.chatId ?? "missing"
+    }
+  ];
+
+  checks.push(await checkWritablePath("approval-directory-writable", path.dirname(approvalPath)));
+  checks.push(await checkWritablePath("decision-directory-writable", path.dirname(decisionsPath)));
+  checks.push(await checkWritablePath("install-directory-writable", installDir));
+
+  if (options.checkTelegram) {
+    checks.push(await checkTelegramBot(token, options));
+  }
+
+  const commands = createApprovalDoctorCommands({
+    framework: options.framework,
+    target,
+    installDir,
+    approvalPath,
+    decisionsPath,
+    chatId: options.chatId ?? "<telegram-chat-id>"
+  });
+  const ok = checks.every((check) => check.status !== "fail");
+
+  return {
+    ok,
+    framework: options.framework,
+    paths: {
+      target,
+      installDir,
+      approvalPath,
+      decisionsPath
+    },
+    checks,
+    commands
+  };
+}
+
+function checkNodeVersion() {
+  const major = Number.parseInt(process.versions.node.split(".")[0], 10);
+  return {
+    id: "node-version",
+    status: major >= 20 ? "pass" : "fail",
+    message: major >= 20
+      ? `Node.js ${process.versions.node} satisfies ClawGuard's runtime requirement.`
+      : `Node.js ${process.versions.node} is too old. ClawGuard requires Node.js 20 or newer.`,
+    detail: process.versions.node
+  };
+}
+
+async function checkWritablePath(id, directory) {
+  const resolved = path.resolve(directory);
+  const probePath = path.join(resolved, `.clawguard-doctor-${process.pid}.tmp`);
+
+  try {
+    await fs.mkdir(resolved, { recursive: true });
+    await fs.writeFile(probePath, "ok\n", { flag: "wx" });
+    await fs.unlink(probePath);
+    return {
+      id,
+      status: "pass",
+      message: "Directory is writable.",
+      detail: resolved
+    };
+  } catch (error) {
+    return {
+      id,
+      status: "fail",
+      message: `Directory is not writable: ${error.message}`,
+      detail: resolved
+    };
+  }
+}
+
+async function checkTelegramBot(botToken, options) {
+  if (!botToken) {
+    return {
+      id: "telegram-api",
+      status: "warn",
+      message: "Skipped Telegram API check because no bot token is configured.",
+      detail: "missing token"
+    };
+  }
+
+  const apiBase = options.telegramApiBase ?? "https://api.telegram.org";
+  const endpoint = `${apiBase.replace(/\/$/, "")}/bot${botToken}/getMe`;
+
+  try {
+    const response = await fetch(endpoint);
+    const text = await response.text();
+    let payload;
+
+    try {
+      payload = text ? JSON.parse(text) : null;
+    } catch {
+      payload = undefined;
+    }
+
+    if (!response.ok || payload?.ok === false) {
+      return {
+        id: "telegram-api",
+        status: "fail",
+        message: `Telegram getMe failed with HTTP ${response.status}.`,
+        detail: redactTelegramToken(endpoint)
+      };
+    }
+
+    return {
+      id: "telegram-api",
+      status: "pass",
+      message: "Telegram bot API responded successfully.",
+      detail: payload?.result?.username ? `@${payload.result.username}` : redactTelegramToken(endpoint)
+    };
+  } catch (error) {
+    return {
+      id: "telegram-api",
+      status: "fail",
+      message: `Telegram getMe failed: ${error.message}`,
+      detail: redactTelegramToken(endpoint)
+    };
+  }
+}
+
+function createApprovalDoctorCommands(details) {
+  const installArgs = [
+    "npx",
+    "@denial-web/clawguard",
+    details.framework,
+    "install",
+    details.target,
+    "--to",
+    details.installDir,
+    "--approval-out",
+    details.approvalPath
+  ];
+  const watchArgs = [
+    "npx",
+    "@denial-web/clawguard",
+    "approvals",
+    "watch",
+    details.approvalPath,
+    "--via",
+    "telegram",
+    "--chat-id",
+    details.chatId
+  ];
+  const pollArgs = [
+    "npx",
+    "@denial-web/clawguard",
+    "approvals",
+    "poll-telegram",
+    details.approvalPath,
+    "--decisions",
+    details.decisionsPath
+  ];
+  const applyArgs = [
+    "npx",
+    "@denial-web/clawguard",
+    "approvals",
+    "apply",
+    details.approvalPath,
+    "--id",
+    "<approval-id>",
+    "--decisions",
+    details.decisionsPath
+  ];
+
+  return {
+    guardedInstall: installArgs.map(shellQuote).join(" "),
+    watchTelegram: `TELEGRAM_BOT_TOKEN=<token> ${watchArgs.map(shellQuote).join(" ")}`,
+    pollTelegram: `TELEGRAM_BOT_TOKEN=<token> ${pollArgs.map(shellQuote).join(" ")}`,
+    applyDecision: applyArgs.map(shellQuote).join(" ")
+  };
+}
+
+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");
@@ -817,6 +1157,35 @@ function printApprovalTelegramPollResult(result) {
   }
 }
 
+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}`);
+}
+
+function printApprovalDoctorResult(result) {
+  console.log("ClawGuard approvals doctor");
+  console.log(`Framework: ${displayFramework(result.framework)}`);
+  console.log(`Ready: ${result.ok ? "yes" : "no"}`);
+  console.log("\nChecks:");
+  for (const check of result.checks) {
+    console.log(`- [${check.status.toUpperCase()}] ${check.message}`);
+    if (check.detail) {
+      console.log(`  ${check.detail}`);
+    }
+  }
+  console.log("\nSuggested commands:");
+  console.log(`1. ${result.commands.guardedInstall}`);
+  console.log(`2. ${result.commands.watchTelegram}`);
+  console.log(`3. ${result.commands.pollTelegram}`);
+  console.log(`4. ${result.commands.applyDecision}`);
+}
+
 async function readApprovalRequest(approvalPath, id) {
   const resolvedPath = path.resolve(approvalPath);
   const approvals = await readApprovalRequests(resolvedPath);
@@ -1246,6 +1615,14 @@ function commandLabel(commandName) {
     return "Telegram approval poll";
   }
 
+  if (commandName === "approvals-apply") {
+    return "Approval apply";
+  }
+
+  if (commandName === "approvals-doctor") {
+    return "Approvals doctor";
+  }
+
   if (commandName === "gate") {
     return "Gate";
   }
@@ -1324,6 +1701,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,
@@ -1893,6 +2282,156 @@ function parseApprovalTelegramPollOptions(values) {
   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;
+}
+
+function parseApprovalDoctorOptions(values) {
+  const options = {
+    approvalPath: ".clawguard/approvals.jsonl",
+    decisionsPath: ".clawguard/decisions.jsonl",
+    installDir: ".agents/skills",
+    target: "./candidate-skill",
+    framework: "openclaw",
+    chatId: undefined,
+    botToken: undefined,
+    telegramApiBase: undefined,
+    checkTelegram: false,
+    json: false
+  };
+
+  for (let index = 0; index < values.length; index += 1) {
+    const value = values[index];
+
+    if (value === "--json") {
+      options.json = true;
+      continue;
+    }
+
+    if (value === "--approval-out") {
+      options.approvalPath = requireNextValue(values, index, "--approval-out");
+      index += 1;
+      continue;
+    }
+
+    if (value === "--decisions") {
+      options.decisionsPath = requireNextValue(values, index, "--decisions");
+      index += 1;
+      continue;
+    }
+
+    if (value === "--to") {
+      options.installDir = requireNextValue(values, index, "--to");
+      index += 1;
+      continue;
+    }
+
+    if (value === "--target") {
+      options.target = requireNextValue(values, index, "--target");
+      index += 1;
+      continue;
+    }
+
+    if (value === "--framework") {
+      options.framework = requireNextValue(values, index, "--framework");
+      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 === "--check-telegram") {
+      options.checkTelegram = true;
+      continue;
+    }
+
+    if (value.startsWith("--")) {
+      throw new Error(`Unknown option: ${value}`);
+    }
+
+    throw new Error(`Unexpected argument for approvals doctor: ${value}`);
+  }
+
+  if (!["openclaw", "hermes"].includes(options.framework)) {
+    throw new Error("Invalid --framework value. Use one of: openclaw, hermes");
+  }
+
+  return options;
+}
+
 async function writeReportFile(outputPath, content) {
   const resolvedPath = path.resolve(outputPath);
   await fs.mkdir(path.dirname(resolvedPath), { recursive: true });