@soulguard/openclaw 0.1.0

package/openclaw.plugin.json

@@ -0,0 +1,11 @@
+{
+  "id": "soulguard",
+  "name": "Soulguard",
+  "description": "Identity protection for AI agents",
+  "version": "0.1.0",
+  "configSchema": {
+    "type": "object",
+    "properties": {},
+    "additionalProperties": false
+  }
+}

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@soulguard/openclaw",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "bun build src/index.ts --outdir dist --target node",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@soulguard/core": "workspace:^0.1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.7.0"
+  }
+}

package/src/guard.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "bun:test";
+import { guardToolCall, type GuardOptions } from "./guard.js";
+
+const defaultOpts: GuardOptions = {
+  vaultFiles: ["SOUL.md", "IDENTITY.md"],
+};
+
+describe("guardToolCall", () => {
+  it("blocks Write to a vault file", () => {
+    const result = guardToolCall("Write", { file_path: "SOUL.md" }, defaultOpts);
+    expect(result.blocked).toBe(true);
+    expect(result.reason).toContain("vault-protected");
+    expect(result.reason).toContain(".soulguard/staging/SOUL.md");
+    expect(result.reason).toContain("reviewed and approved by the owner");
+  });
+
+  it("blocks Edit to a vault file", () => {
+    const result = guardToolCall("Edit", { path: "IDENTITY.md" }, defaultOpts);
+    expect(result.blocked).toBe(true);
+    expect(result.reason).toContain("vault-protected");
+  });
+
+  it("allows Write to a non-vault file", () => {
+    const result = guardToolCall("Write", { file_path: "README.md" }, defaultOpts);
+    expect(result.blocked).toBe(false);
+  });
+
+  it("allows Write to staging copy of a vault file", () => {
+    const result = guardToolCall("Write", { file_path: ".soulguard/staging/SOUL.md" }, defaultOpts);
+    expect(result.blocked).toBe(false);
+  });
+
+  it("allows non-write tools (e.g. Read)", () => {
+    const result = guardToolCall("Read", { file_path: "SOUL.md" }, defaultOpts);
+    expect(result.blocked).toBe(false);
+  });
+
+  // TODO: re-enable when glob matching is delegated to @soulguard/core isVaulted() API
+  // For 0.1, only exact matches are supported — globs are not evaluated.
+
+  it("handles ./prefix in file paths", () => {
+    const result = guardToolCall("Write", { path: "./SOUL.md" }, defaultOpts);
+    expect(result.blocked).toBe(true);
+  });
+
+  it("allows when no path param is present", () => {
+    const result = guardToolCall("Write", { content: "hello" }, defaultOpts);
+    expect(result.blocked).toBe(false);
+  });
+
+  it("checks file param key as well", () => {
+    const result = guardToolCall("Edit", { file: "SOUL.md" }, defaultOpts);
+    expect(result.blocked).toBe(true);
+  });
+
+  // TODO: glob pattern tests — re-enable when delegated to @soulguard/core isVaulted() API
+  // For 0.1, "*.md" in vaultFiles is treated as a literal string, not a glob.
+});

package/src/guard.ts

@@ -0,0 +1,74 @@
+/**
+ * before_tool_call guard — blocks writes to vault-protected files and
+ * returns a helpful message pointing the agent to the staging workflow.
+ */
+
+import { basename } from "node:path";
+import { isVaultedFile, normalizePath } from "@soulguard/core";
+
+// ── Types ──────────────────────────────────────────────────────────────
+
+export type GuardOptions = {
+  /** Vault file paths/patterns from soulguard.json */
+  vaultFiles: string[];
+};
+
+export type GuardResult = {
+  blocked: boolean;
+  reason?: string;
+};
+
+// ── Constants ──────────────────────────────────────────────────────────
+
+/** OpenClaw tool names that write files. */
+const WRITE_TOOLS = new Set(["Write", "Edit"]);
+
+/** Param keys that carry the target file path. */
+const PATH_KEYS = ["file_path", "path", "file"] as const;
+
+/** Staging directory — writes here are always allowed. */
+const STAGING_PREFIX = ".soulguard/staging/";
+
+// ── Main guard ─────────────────────────────────────────────────────────
+
+/**
+ * Evaluate whether a tool call should be blocked.
+ *
+ * Returns `{ blocked: false }` to allow, or `{ blocked: true, reason }` to block.
+ */
+export function guardToolCall(
+  toolName: string,
+  params: Record<string, unknown>,
+  options: GuardOptions,
+): GuardResult {
+  // Only intercept file-writing tools
+  if (!WRITE_TOOLS.has(toolName)) return { blocked: false };
+
+  // Extract target path from params
+  let targetPath: string | undefined;
+  for (const key of PATH_KEYS) {
+    const v = params[key];
+    if (typeof v === "string" && v.length > 0) {
+      targetPath = v;
+      break;
+    }
+  }
+
+  if (!targetPath) return { blocked: false };
+
+  // Never block writes to staging
+  const norm = normalizePath(targetPath);
+  if (norm.startsWith(STAGING_PREFIX)) return { blocked: false };
+
+  // Check against vault using core SDK
+  if (!isVaultedFile(options.vaultFiles, targetPath)) return { blocked: false };
+
+  const fileName = basename(targetPath);
+  return {
+    blocked: true,
+    reason:
+      `${fileName} is vault-protected by soulguard. ` +
+      `To modify it, edit .soulguard/staging/${norm} instead. ` +
+      `Your changes will be reviewed and approved by the owner.`,
+  };
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+/**
+ * @soulguard/openclaw — OpenClaw framework plugin
+ *
+ * Provides:
+ * - Configuration templates (default, paranoid, relaxed)
+ * - before_tool_call hooks to intercept writes to vault files
+ * - Cron and extension directory gating
+ */
+
+export { templates, defaultTemplate, paranoidTemplate, relaxedTemplate } from "./templates.js";
+export type { TemplateName, Template } from "./templates.js";
+
+export { createSoulguardPlugin } from "./plugin.js";
+export type { SoulguardPluginOptions } from "./plugin.js";
+
+// Default export for OpenClaw plugin discovery
+// createSoulguardPlugin() returns { id, activate(api) } which matches OpenClaw's plugin shape
+import { createSoulguardPlugin } from "./plugin.js";
+export default createSoulguardPlugin();
+
+export { guardToolCall } from "./guard.js";
+export type { GuardOptions, GuardResult } from "./guard.js";
+
+export type {
+  OpenClawPluginDefinition,
+  OpenClawPluginApi,
+  AgentTool,
+  AgentToolResult,
+  BeforeToolCallEvent,
+  BeforeToolCallResult,
+} from "./openclaw-types.js";

package/src/openclaw-types.ts

@@ -0,0 +1,50 @@
+/**
+ * Minimal types from the OpenClaw plugin API.
+ *
+ * We vendor just the surface soulguard touches so the package has zero
+ * runtime dependency on openclaw itself.
+ */
+
+export type OpenClawPluginDefinition = {
+  id?: string;
+  name?: string;
+  description?: string;
+  version?: string;
+  register?: (api: OpenClawPluginApi) => void | Promise<void>;
+  activate?: (api: OpenClawPluginApi) => void | Promise<void>;
+};
+
+export type OpenClawPluginApi = {
+  on: (hookName: string, handler: (...args: unknown[]) => unknown) => void;
+  registerHook: (
+    events: string | string[],
+    handler: (...args: unknown[]) => unknown,
+    opts?: { priority?: number },
+  ) => void;
+  registerTool: (tool: AgentTool, opts?: { optional?: boolean }) => void;
+  config: Record<string, unknown>;
+  runtime: { workspaceDir?: string };
+  resolvePath?: (input: string) => string;
+  logger?: { warn: (msg: string) => void; error: (msg: string) => void };
+};
+
+export type AgentTool = {
+  name: string;
+  description: string;
+  parameters: Record<string, unknown>;
+  execute: (id: string, params: Record<string, unknown>) => Promise<AgentToolResult>;
+};
+
+export type AgentToolResult = {
+  content: Array<{ type: "text"; text: string }>;
+};
+
+export type BeforeToolCallEvent = {
+  toolName: string;
+  params: Record<string, unknown>;
+};
+
+export type BeforeToolCallResult = {
+  block?: boolean;
+  blockReason?: string;
+};

package/src/plugin.ts

@@ -0,0 +1,162 @@
+/**
+ * Soulguard OpenClaw plugin — protects vault files from direct writes.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { status, diff, parseConfig, NodeSystemOps, type SoulguardConfig } from "@soulguard/core";
+
+/** OpenClaw-specific default config — also vaults openclaw.json */
+const OPENCLAW_DEFAULT_CONFIG: SoulguardConfig = {
+  vault: ["openclaw.json", "soulguard.json"],
+  ledger: [],
+};
+import { guardToolCall } from "./guard.js";
+import type {
+  BeforeToolCallEvent,
+  BeforeToolCallResult,
+  OpenClawPluginDefinition,
+} from "./openclaw-types.js";
+
+/** Shared plugin description (plugin.json keeps its own copy). */
+export const PLUGIN_DESCRIPTION = "Identity protection for AI agents";
+
+export type SoulguardPluginOptions = {
+  /** Path to soulguard.json (relative to workspace or absolute). */
+  configPath?: string;
+};
+
+/**
+ * Create the soulguard OpenClaw plugin definition.
+ */
+export function createSoulguardPlugin(options?: SoulguardPluginOptions): OpenClawPluginDefinition {
+  return {
+    id: "soulguard",
+    name: "Soulguard",
+    description: PLUGIN_DESCRIPTION,
+    version: "0.1.0",
+
+    activate(api) {
+      const workspaceDir = api.resolvePath?.(".") ?? api.runtime.workspaceDir ?? ".";
+      const configFile = options?.configPath ?? "soulguard.json";
+      const configPath = api.resolvePath?.(configFile) ?? join(workspaceDir, configFile);
+
+      // Load config — fall back to OpenClaw defaults if missing
+      let config: SoulguardConfig;
+      let vaultFiles: string[];
+      try {
+        const raw = JSON.parse(readFileSync(configPath, "utf-8"));
+        config = parseConfig(raw);
+        vaultFiles = config.vault;
+      } catch {
+        // No config file — use OpenClaw defaults (includes openclaw.json)
+        config = OPENCLAW_DEFAULT_CONFIG;
+        vaultFiles = config.vault;
+        api.logger?.warn("soulguard: no soulguard.json found — using OpenClaw defaults");
+      }
+
+      if (vaultFiles.length === 0) return;
+
+      // Helper to create ops for the workspace
+      const createOps = () => new NodeSystemOps(workspaceDir);
+
+      // Status tool
+      api.registerTool(
+        {
+          name: "soulguard_status",
+          description: "Check soulguard protection status of vault and ledger files",
+          parameters: { type: "object", properties: {}, required: [] },
+          async execute(_id, _params) {
+            const ops = createOps();
+            const result = await status({
+              config,
+              expectedVaultOwnership: { user: "soulguardian", group: "soulguard", mode: "444" },
+              // TODO: ledger ownership should come from config, not hardcoded (agent user varies per init)
+              expectedLedgerOwnership: { user: "agent", group: "staff", mode: "644" },
+              ops,
+            });
+            if (!result.ok) {
+              return { content: [{ type: "text" as const, text: "Status check failed" }] };
+            }
+            const lines: string[] = ["Soulguard Status:", ""];
+            for (const f of [...result.value.vault, ...result.value.ledger]) {
+              if (f.status === "ok") lines.push(`  ✅ ${f.file.path}`);
+              else if (f.status === "drifted")
+                lines.push(`  ⚠️  ${f.file.path} — ${f.issues.map((i) => i.kind).join(", ")}`);
+              else if (f.status === "missing") lines.push(`  ❌ ${f.path} — missing`);
+              else if (f.status === "error") lines.push(`  ❌ ${f.path} — error: ${f.error.kind}`);
+            }
+            if (result.value.issues.length === 0) lines.push("", "All files ok.");
+            else lines.push("", `${result.value.issues.length} issue(s) found.`);
+            return { content: [{ type: "text" as const, text: lines.join("\n") }] };
+          },
+        },
+        { optional: true },
+      );
+
+      // Diff tool
+      api.registerTool(
+        {
+          name: "soulguard_diff",
+          description: "Show differences between vault files and their staging copies",
+          parameters: {
+            type: "object",
+            properties: {
+              files: {
+                type: "array",
+                items: { type: "string" },
+                description: "Specific files to diff (default: all vault files)",
+              },
+            },
+            required: [],
+          },
+          async execute(_id, params) {
+            const ops = createOps();
+            const files = Array.isArray(params.files) ? (params.files as string[]) : undefined;
+            const result = await diff({ ops, config, files });
+            if (!result.ok) {
+              return {
+                content: [{ type: "text" as const, text: `Diff failed: ${result.error.kind}` }],
+              };
+            }
+            if (!result.value.hasChanges) {
+              return {
+                content: [
+                  { type: "text" as const, text: "No differences — staging matches vault." },
+                ],
+              };
+            }
+            const lines = result.value.files
+              .filter((d) => d.status === "modified" && d.diff)
+              .map((d) => `--- ${d.path}\n${d.diff}`);
+            let text = lines.join("\n\n") || "No modified files.";
+            if (result.value.approvalHash) {
+              text += `\n\n────────────────────────────────────────\nApproval hash: ${result.value.approvalHash}\nTo approve: soulguard approve --hash ${result.value.approvalHash}`;
+            }
+            return { content: [{ type: "text" as const, text }] };
+          },
+        },
+        { optional: true },
+      );
+
+      // Register the guard hook
+      // Use registerHook (OpenClaw's actual API) with fallback to on()
+      const hookFn = api.registerHook ?? api.on;
+      hookFn("before_tool_call", (...args: unknown[]) => {
+        const event = args[0];
+        // Defense in depth — verify event shape before casting
+        if (!event || typeof event !== "object" || !("toolName" in event)) {
+          return undefined;
+        }
+        const e = event as BeforeToolCallEvent;
+        const result = guardToolCall(e.toolName, e.params, {
+          vaultFiles,
+        });
+        if (result.blocked) {
+          return { block: true, blockReason: result.reason } satisfies BeforeToolCallResult;
+        }
+        return undefined;
+      });
+    },
+  };
+}

package/src/templates.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, test } from "bun:test";
+import { ALL_KNOWN_PATHS, templates } from "./templates.js";
+
+describe("templates", () => {
+  for (const [name, template] of Object.entries(templates)) {
+    test(`${name}: accounts for all known paths`, () => {
+      const allInTemplate = [...template.vault, ...template.ledger, ...template.unprotected];
+      const sorted = (arr: string[]) => [...arr].sort();
+
+      expect(sorted(allInTemplate)).toEqual(sorted([...ALL_KNOWN_PATHS]));
+    });
+
+    test(`${name}: no path appears in multiple tiers`, () => {
+      const vaultSet = new Set(template.vault);
+      const ledgerSet = new Set(template.ledger);
+      const unprotectedSet = new Set(template.unprotected);
+
+      for (const path of template.vault) {
+        expect(ledgerSet.has(path)).toBe(false);
+        expect(unprotectedSet.has(path)).toBe(false);
+      }
+      for (const path of template.ledger) {
+        expect(vaultSet.has(path)).toBe(false);
+        expect(unprotectedSet.has(path)).toBe(false);
+      }
+      for (const path of template.unprotected) {
+        expect(vaultSet.has(path)).toBe(false);
+        expect(ledgerSet.has(path)).toBe(false);
+      }
+    });
+
+    test(`${name}: soulguard.json is always in vault`, () => {
+      expect(template.vault).toContain("soulguard.json");
+    });
+  }
+});

package/src/templates.ts

@@ -0,0 +1,113 @@
+/**
+ * OpenClaw configuration templates for Soulguard.
+ *
+ * Every known path is explicitly placed in vault, ledger, or unprotected.
+ * Tests validate that all paths are accounted for in every template.
+ */
+
+import type { SoulguardConfig } from "@soulguard/core";
+
+// ── Known path groups ──────────────────────────────────────────────────
+
+export const SOULGUARD_CONFIG = ["soulguard.json"] as const;
+export const CORE_IDENTITY = ["SOUL.md", "AGENTS.md", "IDENTITY.md", "USER.md"] as const;
+export const CORE_SESSION = ["TOOLS.md", "HEARTBEAT.md", "BOOTSTRAP.md"] as const;
+export const CORE_MEMORY = ["MEMORY.md"] as const;
+export const MEMORY_DIR = ["memory/**"] as const;
+export const SKILLS = ["skills/**"] as const;
+export const OPENCLAW_CONFIG = ["openclaw.json"] as const;
+export const CRON = ["cron/jobs.json"] as const;
+export const EXTENSIONS = ["extensions/**"] as const;
+export const SESSIONS = ["sessions/**"] as const;
+
+/** All known paths — every template must account for all of these */
+export const ALL_KNOWN_PATHS = [
+  ...SOULGUARD_CONFIG,
+  ...CORE_IDENTITY,
+  ...CORE_SESSION,
+  ...CORE_MEMORY,
+  ...MEMORY_DIR,
+  ...SKILLS,
+  ...OPENCLAW_CONFIG,
+  ...CRON,
+  ...EXTENSIONS,
+  ...SESSIONS,
+] as const;
+
+// ── Template type ──────────────────────────────────────────────────────
+
+export type TemplateName = "default" | "paranoid" | "relaxed";
+
+export type Template = {
+  name: TemplateName;
+  description: string;
+  vault: readonly string[];
+  ledger: readonly string[];
+  unprotected: readonly string[];
+};
+
+/** Extract just the SoulguardConfig from a template */
+export function templateToConfig(template: Template): SoulguardConfig {
+  return {
+    vault: [...template.vault],
+    ledger: [...template.ledger],
+  };
+}
+
+// ── Templates ──────────────────────────────────────────────────────────
+
+export const defaultTemplate: Template = {
+  name: "default",
+  description: "Core identity and config in vault, memory and skills tracked in ledger",
+  vault: [
+    ...SOULGUARD_CONFIG,
+    ...CORE_IDENTITY,
+    ...CORE_SESSION,
+    ...OPENCLAW_CONFIG,
+    ...CRON,
+    ...EXTENSIONS,
+  ],
+  ledger: [...CORE_MEMORY, ...MEMORY_DIR, ...SKILLS],
+  unprotected: [...SESSIONS],
+};
+
+export const paranoidTemplate: Template = {
+  name: "paranoid",
+  description: "Everything possible in vault, only skills in ledger",
+  vault: [
+    ...SOULGUARD_CONFIG,
+    ...CORE_IDENTITY,
+    ...CORE_SESSION,
+    ...CORE_MEMORY,
+    ...MEMORY_DIR,
+    ...SKILLS,
+    ...OPENCLAW_CONFIG,
+    ...CRON,
+    ...EXTENSIONS,
+  ],
+  ledger: [...SESSIONS],
+  unprotected: [],
+};
+
+export const relaxedTemplate: Template = {
+  name: "relaxed",
+  description: "Only soulguard config locked, everything else tracked — good for initial setup",
+  vault: [...SOULGUARD_CONFIG],
+  ledger: [
+    ...CORE_IDENTITY,
+    ...CORE_SESSION,
+    ...CORE_MEMORY,
+    ...MEMORY_DIR,
+    ...SKILLS,
+    ...OPENCLAW_CONFIG,
+    ...CRON,
+    ...EXTENSIONS,
+  ],
+  unprotected: [...SESSIONS],
+};
+
+export const templates: Record<TemplateName, Template> = {
+  default: defaultTemplate,
+  paranoid: paranoidTemplate,
+  relaxed: relaxedTemplate,
+};

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "paths": {
+      "@soulguard/core": ["../core/src/index.ts"]
+    }
+  },
+  "include": ["src"]
+}