@denial-web/clawguard 0.1.12 → 0.1.14

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.
 
+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

package/docs/INTEGRATION_SPEC.md

@@ -78,6 +78,16 @@ 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:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@denial-web/clawguard",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "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";
@@ -42,7 +43,8 @@ if (![
   "approvals-decide",
   "approvals-poll-telegram",
   "approvals-apply",
-  "approvals-doctor"
+  "approvals-doctor",
+  "approvals-demo-flow"
 ].includes(command)) {
   console.error(`Unknown command: ${command}`);
   printHelp();
@@ -118,6 +120,17 @@ try {
     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);
@@ -184,6 +197,7 @@ Usage:
   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>
 
@@ -229,6 +243,8 @@ Options:
                           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
@@ -248,6 +264,7 @@ Examples:
   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
@@ -379,6 +396,14 @@ function parseCommand(values) {
     };
   }
 
+  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];
 
@@ -752,6 +777,154 @@ async function runApprovalDoctor(options) {
   };
 }
 
+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 {
@@ -1186,6 +1359,30 @@ function printApprovalDoctorResult(result) {
   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);
@@ -1623,6 +1820,10 @@ function commandLabel(commandName) {
     return "Approvals doctor";
   }
 
+  if (commandName === "approvals-demo-flow") {
+    return "Approvals demo flow";
+  }
+
   if (commandName === "gate") {
     return "Gate";
   }
@@ -2432,6 +2633,57 @@ function parseApprovalDoctorOptions(values) {
   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 });

package/web/app.js

@@ -40,6 +40,10 @@ const elements = {
   installVerdict: document.querySelector("#install-verdict"),
   installMessage: document.querySelector("#install-message"),
   installCommand: document.querySelector("#install-command"),
+  approvalTitle: document.querySelector("#approval-title"),
+  approvalSummary: document.querySelector("#approval-summary"),
+  approvalCommand: document.querySelector("#approval-command"),
+  demoCommand: document.querySelector("#demo-command"),
   actions: document.querySelector("#actions"),
   critical: document.querySelector("#critical-count"),
   high: document.querySelector("#high-count"),
@@ -239,6 +243,7 @@ function renderResult(result) {
   elements.downloadHtml.disabled = false;
 
   renderInstallGate(result);
+  renderApprovalFlow(result);
   renderFindings(scan.findings ?? []);
 }
 
@@ -268,6 +273,50 @@ function renderInstallGate(result) {
   elements.installMessage.textContent = "ClawGuard would require review, sandboxing, or approval before copying files.";
 }
 
+function renderApprovalFlow(result) {
+  const scan = result.scan;
+  const policy = scan.policy ?? {};
+  const decision = policy.decision ?? "allow";
+  const target = installTargetFor(result);
+  const installName = safeInstallName(result.displayTarget ?? "skill");
+  const preset = policy.preset ?? elements.policy.value;
+  const framework = "openclaw";
+
+  elements.demoCommand.textContent = "npx @denial-web/clawguard approvals demo-flow --keep";
+  elements.approvalCommand.textContent = [
+    "npx",
+    "@denial-web/clawguard",
+    framework,
+    "install",
+    target,
+    "--to",
+    "./.agents/skills",
+    "--name",
+    installName,
+    "--policy",
+    preset,
+    "--approval-out",
+    "./.clawguard/approvals.jsonl",
+    "--approval-mode",
+    "always"
+  ].join(" ");
+
+  if (decision === "allow") {
+    elements.approvalTitle.textContent = "Approval can still be required";
+    elements.approvalSummary.textContent = "Even a clean scan can pause before trust when you use approval-mode always. That gives the owner final control over autonomous skill installs.";
+    return;
+  }
+
+  if (decision === "block") {
+    elements.approvalTitle.textContent = "Blocked before trust";
+    elements.approvalSummary.textContent = "A blocked result should not be copied into a trusted skill folder. Send the report to the owner instead of applying the install.";
+    return;
+  }
+
+  elements.approvalTitle.textContent = "Pause and ask the owner";
+  elements.approvalSummary.textContent = "Warn, review, sandbox, and dual-approval decisions create a pending approval request before any files are copied into the trusted skill folder.";
+}
+
 function renderFindings(findings) {
   if (findings.length === 0) {
     elements.findings.className = "findings empty-state";

package/web/index.html

@@ -86,6 +86,28 @@
           </div>
         </section>
 
+        <section class="approval-panel" aria-label="Approval loop demo">
+          <div class="approval-copy">
+            <p class="eyebrow">Approval Loop Demo</p>
+            <h2 id="approval-title">Prove the full guarded install loop</h2>
+            <p id="approval-summary">Create a harmless temporary skill, scan it, write an approval request, record an owner approval, and install only after the decision is applied.</p>
+          </div>
+          <div class="approval-flow" aria-label="Approval flow">
+            <span>install hook</span>
+            <span>policy gate</span>
+            <span>owner approval</span>
+            <span>apply</span>
+          </div>
+          <div class="command-stack">
+            <div class="command-box">
+              <code id="demo-command">npx @denial-web/clawguard approvals demo-flow --keep</code>
+            </div>
+            <div class="command-box">
+              <code id="approval-command">npx @denial-web/clawguard openclaw install ./skill --to ./.agents/skills --approval-out ./.clawguard/approvals.jsonl --approval-mode always</code>
+            </div>
+          </div>
+        </section>
+
         <section class="metrics" aria-label="Finding summary">
           <div><span>Critical</span><strong id="critical-count">0</strong></div>
           <div><span>High</span><strong id="high-count">0</strong></div>

package/web/styles.css

@@ -264,7 +264,7 @@ input[type="file"] {
   align-items: stretch;
 }
 
-.score-ring, .decision, .install-panel, .metrics div, .metadata-grid div, .finding-card, .empty-state {
+.score-ring, .decision, .install-panel, .approval-panel, .metrics div, .metadata-grid div, .finding-card, .empty-state {
   border: 1px solid var(--line);
   border-radius: 8px;
   background: var(--panel);
@@ -339,6 +339,51 @@ input[type="file"] {
   overflow-wrap: anywhere;
 }
 
+.approval-panel {
+  display: grid;
+  grid-template-columns: minmax(220px, 0.9fr) minmax(160px, 0.65fr) minmax(0, 1.25fr);
+  gap: 14px;
+  align-items: stretch;
+  padding: 16px;
+}
+
+.approval-copy h2 {
+  margin-top: 5px;
+  font-size: 22px;
+  text-transform: uppercase;
+}
+
+#approval-summary {
+  margin-top: 6px;
+  color: var(--muted);
+  line-height: 1.4;
+}
+
+.approval-flow {
+  display: grid;
+  gap: 8px;
+}
+
+.approval-flow span {
+  min-height: 34px;
+  display: flex;
+  align-items: center;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  background: #edf1ea;
+  color: var(--ink);
+  padding: 7px 10px;
+  font-size: 12px;
+  font-weight: 900;
+  text-transform: uppercase;
+}
+
+.command-stack {
+  min-width: 0;
+  display: grid;
+  gap: 10px;
+}
+
 .action-tags {
   display: flex;
   flex-wrap: wrap;
@@ -459,7 +504,7 @@ input[type="file"] {
 }
 
 @media (max-width: 900px) {
-  .workbench, .score-panel, .install-panel {
+  .workbench, .score-panel, .install-panel, .approval-panel {
     grid-template-columns: 1fr;
   }