@denial-web/clawguard 0.1.11 → 0.1.13

package/README.md

@@ -68,6 +68,22 @@ 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.
 
+To prove the full approval loop locally without Telegram, WhatsApp, OpenClaw, or Hermes credentials, run:
+
+```bash
+npx @denial-web/clawguard approvals demo-flow --keep
+```
+
+The demo creates a harmless temporary skill, writes a pending approval, records a local owner approval, applies the decision, and installs the skill into a temporary trusted folder. Remove `--keep` when you want ClawGuard to clean up the temporary workspace automatically.
+
+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

package/docs/INTEGRATION_SPEC.md

@@ -78,6 +78,27 @@ 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.
 
+### Local Approval Demo
+
+For demos, onboarding, and smoke tests, users can prove the full approval loop without OpenClaw, Hermes, Telegram, WhatsApp, or Slack credentials:
+
+```bash
+clawguard approvals demo-flow --keep
+```
+
+The demo creates a harmless temporary skill, scans it with the governed policy, forces an approval request with `--approval-mode always`, writes a local `approve` decision, applies that decision, and copies the skill into a temporary trusted folder. By default it removes the temporary workspace after the run. Use `--keep` when recording a demo or inspecting the generated approval and decision logs.
+
+### 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:

package/package.json

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

package/src/cli.js

@@ -3,6 +3,7 @@
 import { promises as fs } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { execFile } from "node:child_process";
+import os from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
 import { loadConfig, mergeConfig, parseSize } from "./config.js";
@@ -41,7 +42,9 @@ if (![
   "approvals-watch",
   "approvals-decide",
   "approvals-poll-telegram",
-  "approvals-apply"
+  "approvals-apply",
+  "approvals-doctor",
+  "approvals-demo-flow"
 ].includes(command)) {
   console.error(`Unknown command: ${command}`);
   printHelp();
@@ -106,6 +109,28 @@ try {
     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);
+  }
+
+  if (command === "approvals-demo-flow") {
+    const demoOptions = parseApprovalDemoFlowOptions(optionValues);
+    const result = await runApprovalDemoFlow(demoOptions);
+    if (demoOptions.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      printApprovalDemoFlowResult(result);
+    }
+    process.exit(result.ok ? 0 : 1);
+  }
+
   const cliOptions = parseOptions(optionValues);
   cliOptions.framework = framework;
   const loadedConfig = await loadConfig(cliOptions.target, cliOptions.configPath);
@@ -171,6 +196,8 @@ Usage:
   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 approvals demo-flow [--keep]
   clawguard scan-workspace <path> [--json] [--policy <preset>]
   npm run scan -- <path>
 
@@ -214,6 +241,10 @@ 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.
+                          In approvals demo-flow, label the demo as openclaw or hermes.
+  --keep                  In approvals demo-flow, keep the temporary demo workspace.
 
 Gate exit codes:
   0 = allow
@@ -232,6 +263,8 @@ Examples:
   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
+  npx @denial-web/clawguard approvals demo-flow --keep
   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
@@ -355,6 +388,22 @@ function parseCommand(values) {
     };
   }
 
+  if (rawCommand === "approvals" && values[1] === "doctor") {
+    return {
+      command: "approvals-doctor",
+      framework: undefined,
+      optionValues: values.slice(2)
+    };
+  }
+
+  if (rawCommand === "approvals" && values[1] === "demo-flow") {
+    return {
+      command: "approvals-demo-flow",
+      framework: undefined,
+      optionValues: values.slice(2)
+    };
+  }
+
   if (["openclaw", "hermes"].includes(rawCommand)) {
     const nestedCommand = values[1];
 
@@ -662,6 +711,357 @@ async function applyApprovalDecision(options) {
   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
+  };
+}
+
+async function runApprovalDemoFlow(options) {
+  const workspace = await fs.mkdtemp(path.join(os.tmpdir(), "clawguard-demo-flow-"));
+  const candidatePath = path.join(workspace, "candidate-skill");
+  const installDir = path.join(workspace, "trusted-skills");
+  const approvalPath = path.join(workspace, ".clawguard", "approvals.jsonl");
+  const decisionsPath = path.join(workspace, ".clawguard", "decisions.jsonl");
+  const steps = [];
+
+  await fs.mkdir(candidatePath, { recursive: true });
+  await fs.writeFile(path.join(candidatePath, "SKILL.md"), [
+    "# ClawGuard Demo Skill",
+    "",
+    "A harmless local skill used to prove the approval gate flow.",
+    "",
+    "It does not execute code, fetch network resources, or install dependencies.",
+    ""
+  ].join("\n"));
+  steps.push({
+    name: "create-demo-skill",
+    status: "pass",
+    detail: candidatePath
+  });
+
+  const scan = await scanTarget(candidatePath, {
+    policy: options.policy
+  });
+  steps.push({
+    name: "scan",
+    status: "pass",
+    detail: `${formatDecision(scan.policy.decision)} / ${scan.level.toUpperCase()} (${scan.score}/100)`
+  });
+
+  const install = await handleInstall(scan, {
+    target: candidatePath,
+    installDir,
+    installName: "demo-skill",
+    dryRun: false,
+    approvalOut: approvalPath,
+    approvalMode: "always",
+    framework: options.framework
+  });
+
+  if (!install.approvalRequest) {
+    throw new Error("Demo flow expected an approval request but none was created.");
+  }
+
+  steps.push({
+    name: "write-approval",
+    status: "pass",
+    detail: install.approvalRequest.id
+  });
+
+  const approval = await readApprovalRequest(approvalPath, install.approvalRequest.id);
+  const decisionResult = await decideApproval({
+    approvalPath,
+    id: approval.id,
+    decision: "approve",
+    outPath: decisionsPath,
+    actor: "clawguard-demo-flow",
+    reason: "Local demo approval.",
+    json: false
+  });
+  steps.push({
+    name: "record-owner-decision",
+    status: "pass",
+    detail: formatDecision(decisionResult.decision.decision)
+  });
+
+  const apply = await applyApprovalDecision({
+    approvalPath,
+    id: approval.id,
+    decisionsPath,
+    dryRun: false,
+    json: false
+  });
+  steps.push({
+    name: "apply-decision",
+    status: apply.installed ? "pass" : "fail",
+    detail: apply.reason
+  });
+
+  const installedSkillPath = path.join(install.destination, "SKILL.md");
+  const installedSkill = await fs.readFile(installedSkillPath, "utf8");
+  const result = {
+    ok: apply.installed && installedSkill.includes("ClawGuard Demo Skill"),
+    cleanedUp: false,
+    kept: options.keep,
+    framework: options.framework,
+    policy: options.policy,
+    workspace,
+    paths: {
+      candidate: candidatePath,
+      installDir,
+      destination: install.destination,
+      installedSkill: installedSkillPath,
+      approvalPath,
+      decisionsPath
+    },
+    scan: {
+      decision: scan.policy.decision,
+      risk: {
+        level: scan.level,
+        score: scan.score
+      },
+      findings: scan.findings.length
+    },
+    approval: {
+      id: approval.id,
+      status: approval.status,
+      decision: approval.decision
+    },
+    decision: {
+      id: decisionResult.decision.id,
+      decision: decisionResult.decision.decision,
+      status: decisionResult.decision.status,
+      actor: decisionResult.decision.actor
+    },
+    apply: {
+      installed: apply.installed,
+      skipped: apply.skipped,
+      reason: apply.reason
+    },
+    steps
+  };
+
+  if (!options.keep) {
+    try {
+      await fs.rm(workspace, { recursive: true, force: true });
+      result.cleanedUp = true;
+      steps.push({
+        name: "cleanup",
+        status: "pass",
+        detail: "Temporary workspace removed."
+      });
+    } catch (error) {
+      result.ok = false;
+      result.cleanupError = error.message;
+      steps.push({
+        name: "cleanup",
+        status: "fail",
+        detail: error.message
+      });
+    }
+  }
+
+  return result;
+}
+
+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;
 
@@ -941,6 +1341,48 @@ function printApprovalApplyResult(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}`);
+}
+
+function printApprovalDemoFlowResult(result) {
+  console.log("ClawGuard approvals demo-flow");
+  console.log(`Framework: ${displayFramework(result.framework)}`);
+  console.log(`Policy: ${result.policy}`);
+  console.log(`Ready: ${result.ok ? "yes" : "no"}`);
+  console.log(`Workspace: ${result.workspace}${result.cleanedUp ? " (cleaned up)" : ""}`);
+  console.log(`Approval id: ${result.approval.id}`);
+  console.log(`Scan: ${formatDecision(result.scan.decision)} / ${result.scan.risk.level.toUpperCase()} (${result.scan.risk.score}/100)`);
+  console.log(`Decision: ${formatDecision(result.decision.decision)}`);
+  console.log(`Installed: ${result.apply.installed ? "yes" : "no"}`);
+
+  console.log("\nSteps:");
+  for (const step of result.steps) {
+    console.log(`- [${step.status.toUpperCase()}] ${step.name}: ${step.detail}`);
+  }
+
+  if (!result.cleanedUp) {
+    console.log("\nArtifacts:");
+    console.log(`Approval queue: ${result.paths.approvalPath}`);
+    console.log(`Decision log: ${result.paths.decisionsPath}`);
+    console.log(`Installed skill: ${result.paths.installedSkill}`);
+  }
+}
+
 async function readApprovalRequest(approvalPath, id) {
   const resolvedPath = path.resolve(approvalPath);
   const approvals = await readApprovalRequests(resolvedPath);
@@ -1374,6 +1816,14 @@ function commandLabel(commandName) {
     return "Approval apply";
   }
 
+  if (commandName === "approvals-doctor") {
+    return "Approvals doctor";
+  }
+
+  if (commandName === "approvals-demo-flow") {
+    return "Approvals demo flow";
+  }
+
   if (commandName === "gate") {
     return "Gate";
   }
@@ -2094,6 +2544,146 @@ function parseApprovalApplyOptions(values) {
   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;
+}
+
+function parseApprovalDemoFlowOptions(values) {
+  const options = {
+    framework: "openclaw",
+    policy: "governed",
+    keep: 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 === "--keep") {
+      options.keep = true;
+      continue;
+    }
+
+    if (value === "--framework") {
+      options.framework = requireNextValue(values, index, "--framework");
+      index += 1;
+      continue;
+    }
+
+    if (value === "--policy") {
+      options.policy = requireNextValue(values, index, "--policy");
+      index += 1;
+      continue;
+    }
+
+    if (value.startsWith("--")) {
+      throw new Error(`Unknown option: ${value}`);
+    }
+
+    throw new Error(`Unexpected argument for approvals demo-flow: ${value}`);
+  }
+
+  if (!["openclaw", "hermes"].includes(options.framework)) {
+    throw new Error("Invalid --framework value. Use one of: openclaw, hermes");
+  }
+
+  if (!policyPresets.includes(options.policy)) {
+    throw new Error(`Invalid --policy value. Use one of: ${policyPresets.join(", ")}`);
+  }
+
+  return options;
+}
+
 async function writeReportFile(outputPath, content) {
   const resolvedPath = path.resolve(outputPath);
   await fs.mkdir(path.dirname(resolvedPath), { recursive: true });