openclaw-safeclaw-plugin 0.1.0

package/README.md

@@ -0,0 +1,77 @@
+# openclaw-safeclaw-plugin
+
+Neurosymbolic governance plugin for OpenClaw AI agents. Validates every tool call, message, and action against OWL ontologies and SHACL constraints before execution.
+
+## Install
+
+```bash
+npm install openclaw-safeclaw-plugin
+```
+
+## Quick Start (SaaS)
+
+Point the plugin at the hosted SafeClaw service:
+
+```bash
+export SAFECLAW_URL="https://api.safeclaw.eu/api/v1"
+export SAFECLAW_ENFORCEMENT="enforce"
+```
+
+No server setup needed — the plugin connects to SafeClaw's hosted service.
+
+## Quick Start (Self-Hosted)
+
+```bash
+# Start the SafeClaw service
+git clone https://github.com/tendlyeu/SafeClaw.git
+cd SafeClaw/safeclaw-service
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+safeclaw init --user-id yourname
+safeclaw serve
+# Engine ready on http://localhost:8420
+```
+
+The plugin auto-connects to `http://localhost:8420/api/v1` by default.
+
+## What It Does
+
+- **Blocks dangerous actions** — force push, deleting root, exposing secrets
+- **Enforces dependencies** — tests must pass before git push
+- **Checks user preferences** — confirmation for irreversible actions
+- **Governs messages** — blocks sensitive data leaks
+- **Full audit trail** — every decision logged with ontological justification
+
+## How It Works
+
+The plugin registers hooks on OpenClaw events:
+
+1. **before_tool_call** — validates against SHACL shapes, policies, preferences, dependencies
+2. **before_agent_start** — injects governance context into the agent's system prompt
+3. **message_sending** — checks outbound messages for sensitive data
+4. **after_tool_call** — records action outcomes for dependency tracking
+5. **llm_input/output** — logs LLM interactions for audit
+
+## Configuration
+
+Set via environment variables or `~/.safeclaw/config.json`:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SAFECLAW_URL` | `http://localhost:8420/api/v1` | SafeClaw service URL |
+| `SAFECLAW_API_KEY` | *(empty)* | API key for cloud mode |
+| `SAFECLAW_TIMEOUT_MS` | `500` | Request timeout in ms |
+| `SAFECLAW_ENABLED` | `true` | Set `false` to disable |
+| `SAFECLAW_ENFORCEMENT` | `enforce` | `enforce`, `warn-only`, `audit-only`, or `disabled` |
+| `SAFECLAW_FAIL_MODE` | `closed` | `open` (allow on failure) or `closed` (block on failure) |
+
+## Enforcement Modes
+
+- **`enforce`** — block actions that violate constraints (recommended)
+- **`warn-only`** — log warnings but allow all actions
+- **`audit-only`** — server-side logging only, no client-side action
+- **`disabled`** — plugin is completely inactive
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,59 @@
+# SafeClaw — Neurosymbolic Governance for OpenClaw
+
+SafeClaw adds ontology-based constraint checking to your OpenClaw agent. Every tool call, message, and action is validated against OWL ontologies and SHACL shapes before execution.
+
+## What it does
+
+- **Blocks dangerous actions** — force push, deleting root, exposing secrets
+- **Enforces dependencies** — tests must pass before git push
+- **Checks user preferences** — confirmation for irreversible actions based on autonomy level
+- **Governs messages** — blocks sensitive data leaks, enforces never-contact lists
+- **Full audit trail** — every decision logged with ontological justification
+
+## Setup
+
+### Option A: Local mode (self-hosted)
+
+```bash
+# 1. Start the SafeClaw service
+pip install safeclaw
+safeclaw init
+uvicorn safeclaw.main:app --port 8420
+
+# 2. Install this plugin (done if you're reading this via clawhub)
+# The plugin auto-connects to http://localhost:8420
+```
+
+### Option B: Cloud mode (safeclaw.eu)
+
+```bash
+# 1. Sign up at safeclaw.eu and get your API key
+
+# 2. Set your API key
+export SAFECLAW_URL="https://api.safeclaw.eu/api/v1"
+export SAFECLAW_API_KEY="sc_live_your_key_here"
+```
+
+## Configuration
+
+Set via environment variables or `~/.safeclaw/config.json`:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SAFECLAW_URL` | `http://localhost:8420/api/v1` | SafeClaw service URL |
+| `SAFECLAW_API_KEY` | (empty) | API key for remote/cloud mode |
+| `SAFECLAW_TIMEOUT_MS` | `500` | Request timeout in milliseconds |
+| `SAFECLAW_ENABLED` | `true` | Set to `false` to disable |
+| `SAFECLAW_ENFORCEMENT` | `enforce` | `enforce`, `warn-only`, `audit-only`, or `disabled` |
+
+## How it works
+
+This plugin registers hooks on every OpenClaw event:
+
+1. **before_tool_call** — validates against SHACL shapes, policies, preferences, dependencies
+2. **before_agent_start** — injects governance context into the agent's system prompt
+3. **message_sending** — checks outbound messages for sensitive data and contact rules
+4. **after_tool_call** — records action outcomes for dependency tracking
+5. **llm_input/output** — logs LLM interactions for audit
+
+If the SafeClaw service is unavailable, the plugin degrades gracefully — no blocks, no crashes.

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * SafeClaw — Neurosymbolic Governance Plugin for OpenClaw
+ *
+ * This TypeScript file is the ENTIRE client-side codebase.
+ * All governance logic lives in the SafeClaw Python service.
+ * This plugin is a thin HTTP bridge that forwards OpenClaw events
+ * to the SafeClaw service and acts on the responses.
+ */
+interface PluginEvent {
+    sessionId?: string;
+    userId?: string;
+    [key: string]: unknown;
+}
+interface PluginContext {
+    sessionId?: string;
+    userId?: string;
+    [key: string]: unknown;
+}
+interface PluginApi {
+    on(event: string, handler: (event: PluginEvent, ctx: PluginContext) => Promise<Record<string, unknown> | void> | void, options?: {
+        priority?: number;
+    }): void;
+}
+declare const _default: {
+    id: string;
+    name: string;
+    version: string;
+    register(api: PluginApi): void;
+};
+export default _default;

package/dist/index.js

@@ -0,0 +1,178 @@
+/**
+ * SafeClaw — Neurosymbolic Governance Plugin for OpenClaw
+ *
+ * This TypeScript file is the ENTIRE client-side codebase.
+ * All governance logic lives in the SafeClaw Python service.
+ * This plugin is a thin HTTP bridge that forwards OpenClaw events
+ * to the SafeClaw service and acts on the responses.
+ */
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+function loadConfig() {
+    const defaults = {
+        serviceUrl: process.env.SAFECLAW_URL ?? 'http://localhost:8420/api/v1',
+        apiKey: process.env.SAFECLAW_API_KEY ?? '',
+        timeoutMs: parseInt(process.env.SAFECLAW_TIMEOUT_MS ?? '500', 10),
+        enabled: process.env.SAFECLAW_ENABLED !== 'false',
+        enforcement: process.env.SAFECLAW_ENFORCEMENT ?? 'enforce',
+        failMode: process.env.SAFECLAW_FAIL_MODE ?? 'closed',
+        agentId: process.env.SAFECLAW_AGENT_ID ?? '',
+        agentToken: process.env.SAFECLAW_AGENT_TOKEN ?? '',
+    };
+    // Try loading from config file
+    const configPath = join(homedir(), '.safeclaw', 'config.json');
+    if (existsSync(configPath)) {
+        try {
+            const raw = JSON.parse(readFileSync(configPath, 'utf-8'));
+            if (raw.enabled === false)
+                defaults.enabled = false;
+            if (raw.remote?.serviceUrl)
+                defaults.serviceUrl = raw.remote.serviceUrl;
+            if (raw.remote?.apiKey)
+                defaults.apiKey = raw.remote.apiKey;
+            if (raw.remote?.timeoutMs)
+                defaults.timeoutMs = raw.remote.timeoutMs;
+            if (raw.enforcement?.mode)
+                defaults.enforcement = raw.enforcement.mode;
+            if (raw.enforcement?.failMode)
+                defaults.failMode = raw.enforcement.failMode;
+            if (raw.agentId)
+                defaults.agentId = raw.agentId;
+            if (raw.agentToken)
+                defaults.agentToken = raw.agentToken;
+        }
+        catch {
+            // Config file unreadable — use defaults
+        }
+    }
+    defaults.serviceUrl = defaults.serviceUrl.replace(/\/+$/, '');
+    const validModes = ['enforce', 'warn-only', 'audit-only', 'disabled'];
+    if (!validModes.includes(defaults.enforcement)) {
+        console.warn(`[SafeClaw] Invalid enforcement mode "${defaults.enforcement}", defaulting to "enforce"`);
+        defaults.enforcement = 'enforce';
+    }
+    const validFailModes = ['open', 'closed'];
+    if (!validFailModes.includes(defaults.failMode)) {
+        console.warn(`[SafeClaw] Invalid fail mode "${defaults.failMode}", defaulting to "closed"`);
+        defaults.failMode = 'closed';
+    }
+    return defaults;
+}
+const config = loadConfig();
+// --- HTTP Client ---
+async function post(path, body) {
+    if (!config.enabled)
+        return null;
+    const headers = { 'Content-Type': 'application/json' };
+    if (config.apiKey) {
+        headers['Authorization'] = `Bearer ${config.apiKey}`;
+    }
+    const agentFields = config.agentId ? { agentId: config.agentId, agentToken: config.agentToken } : {};
+    try {
+        const res = await fetch(`${config.serviceUrl}${path}`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({ ...body, ...agentFields }),
+            signal: AbortSignal.timeout(config.timeoutMs),
+        });
+        if (!res.ok) {
+            console.warn(`[SafeClaw] HTTP ${res.status} from ${path}`);
+            return null; // Caller checks failMode
+        }
+        return await res.json();
+    }
+    catch (e) {
+        if (e instanceof DOMException && e.name === 'TimeoutError') {
+            console.debug(`[SafeClaw] Timeout on ${path}`);
+        }
+        else {
+            console.debug(`[SafeClaw] Service unavailable: ${path}`);
+        }
+        return null; // Caller checks failMode
+    }
+}
+export default {
+    id: 'openclaw-safeclaw-plugin',
+    name: 'SafeClaw Neurosymbolic Governance',
+    version: '0.1.0',
+    register(api) {
+        if (!config.enabled)
+            return;
+        // THE GATE — constraint checking on every tool call
+        api.on('before_tool_call', async (event, ctx) => {
+            const r = await post('/evaluate/tool-call', {
+                sessionId: ctx.sessionId ?? event.sessionId,
+                userId: ctx.userId ?? event.userId,
+                toolName: event.toolName ?? event.tool_name,
+                params: event.params ?? {},
+                sessionHistory: event.sessionHistory ?? [],
+            });
+            if (r === null && config.failMode === 'closed' && config.enforcement === 'enforce') {
+                return { block: true, blockReason: 'SafeClaw service unavailable (fail-closed)' };
+            }
+            else if (r === null && config.failMode === 'closed' && config.enforcement === 'warn-only') {
+                console.warn('[SafeClaw] Service unavailable (fail-closed mode, warn-only)');
+            }
+            if (r?.block) {
+                if (config.enforcement === 'enforce') {
+                    return { block: true, blockReason: r.reason };
+                }
+                if (config.enforcement === 'warn-only') {
+                    console.warn(`[SafeClaw] Warning: ${r.reason}`);
+                }
+                // audit-only: logged server-side, no action here
+            }
+        }, { priority: 100 });
+        // Context injection — prepend governance context to agent system prompt
+        api.on('before_agent_start', async (event, ctx) => {
+            const r = await post('/context/build', {
+                sessionId: ctx.sessionId ?? event.sessionId,
+                userId: ctx.userId ?? event.userId,
+            });
+            if (r?.prependContext) {
+                return { prependContext: r.prependContext };
+            }
+        }, { priority: 100 });
+        // Message governance — check outbound messages
+        api.on('message_sending', async (event, ctx) => {
+            const r = await post('/evaluate/message', {
+                sessionId: ctx.sessionId ?? event.sessionId,
+                userId: ctx.userId ?? event.userId,
+                to: event.to,
+                content: event.content,
+            });
+            if (r === null && config.failMode === 'closed' && config.enforcement === 'enforce') {
+                return { cancel: true };
+            }
+            else if (r === null && config.failMode === 'closed' && config.enforcement === 'warn-only') {
+                console.warn('[SafeClaw] Service unavailable (fail-closed mode, warn-only)');
+            }
+            if (r?.block && config.enforcement === 'enforce') {
+                return { cancel: true };
+            }
+        }, { priority: 100 });
+        // Async logging — fire-and-forget, no return value needed
+        api.on('llm_input', (event, ctx) => {
+            post('/log/llm-input', {
+                sessionId: ctx.sessionId ?? event.sessionId,
+                content: event.content,
+            }).catch(() => { });
+        });
+        api.on('llm_output', (event, ctx) => {
+            post('/log/llm-output', {
+                sessionId: ctx.sessionId ?? event.sessionId,
+                content: event.content,
+            }).catch(() => { });
+        });
+        api.on('after_tool_call', (event, ctx) => {
+            post('/record/tool-result', {
+                sessionId: ctx.sessionId ?? event.sessionId,
+                toolName: event.toolName ?? event.tool_name,
+                params: event.params ?? {},
+                result: event.result ?? '',
+                success: event.success ?? true,
+            }).catch(() => { });
+        });
+    },
+};

package/index.ts

@@ -0,0 +1,222 @@
+/**
+ * SafeClaw — Neurosymbolic Governance Plugin for OpenClaw
+ *
+ * This TypeScript file is the ENTIRE client-side codebase.
+ * All governance logic lives in the SafeClaw Python service.
+ * This plugin is a thin HTTP bridge that forwards OpenClaw events
+ * to the SafeClaw service and acts on the responses.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+// --- Configuration ---
+
+interface SafeClawPluginConfig {
+  serviceUrl: string;
+  apiKey: string;
+  timeoutMs: number;
+  enabled: boolean;
+  enforcement: 'enforce' | 'warn-only' | 'audit-only' | 'disabled';
+  failMode: 'open' | 'closed';
+  agentId: string;
+  agentToken: string;
+}
+
+function loadConfig(): SafeClawPluginConfig {
+  const defaults: SafeClawPluginConfig = {
+    serviceUrl: process.env.SAFECLAW_URL ?? 'http://localhost:8420/api/v1',
+    apiKey: process.env.SAFECLAW_API_KEY ?? '',
+    timeoutMs: parseInt(process.env.SAFECLAW_TIMEOUT_MS ?? '500', 10),
+    enabled: process.env.SAFECLAW_ENABLED !== 'false',
+    enforcement: (process.env.SAFECLAW_ENFORCEMENT as SafeClawPluginConfig['enforcement']) ?? 'enforce',
+    failMode: (process.env.SAFECLAW_FAIL_MODE as SafeClawPluginConfig['failMode']) ?? 'closed',
+    agentId: process.env.SAFECLAW_AGENT_ID ?? '',
+    agentToken: process.env.SAFECLAW_AGENT_TOKEN ?? '',
+  };
+
+  // Try loading from config file
+  const configPath = join(homedir(), '.safeclaw', 'config.json');
+  if (existsSync(configPath)) {
+    try {
+      const raw = JSON.parse(readFileSync(configPath, 'utf-8'));
+      if (raw.enabled === false) defaults.enabled = false;
+      if (raw.remote?.serviceUrl) defaults.serviceUrl = raw.remote.serviceUrl;
+      if (raw.remote?.apiKey) defaults.apiKey = raw.remote.apiKey;
+      if (raw.remote?.timeoutMs) defaults.timeoutMs = raw.remote.timeoutMs;
+      if (raw.enforcement?.mode) defaults.enforcement = raw.enforcement.mode;
+      if (raw.enforcement?.failMode) defaults.failMode = raw.enforcement.failMode;
+      if (raw.agentId) defaults.agentId = raw.agentId;
+      if (raw.agentToken) defaults.agentToken = raw.agentToken;
+    } catch {
+      // Config file unreadable — use defaults
+    }
+  }
+
+  defaults.serviceUrl = defaults.serviceUrl.replace(/\/+$/, '');
+
+  const validModes = ['enforce', 'warn-only', 'audit-only', 'disabled'] as const;
+  if (!validModes.includes(defaults.enforcement as any)) {
+    console.warn(`[SafeClaw] Invalid enforcement mode "${defaults.enforcement}", defaulting to "enforce"`);
+    defaults.enforcement = 'enforce';
+  }
+
+  const validFailModes = ['open', 'closed'] as const;
+  if (!validFailModes.includes(defaults.failMode as any)) {
+    console.warn(`[SafeClaw] Invalid fail mode "${defaults.failMode}", defaulting to "closed"`);
+    defaults.failMode = 'closed';
+  }
+
+  return defaults;
+}
+
+const config = loadConfig();
+
+// --- HTTP Client ---
+
+async function post(path: string, body: Record<string, unknown>): Promise<Record<string, unknown> | null> {
+  if (!config.enabled) return null;
+
+  const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+  if (config.apiKey) {
+    headers['Authorization'] = `Bearer ${config.apiKey}`;
+  }
+
+  const agentFields = config.agentId ? { agentId: config.agentId, agentToken: config.agentToken } : {};
+
+  try {
+    const res = await fetch(`${config.serviceUrl}${path}`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({ ...body, ...agentFields }),
+      signal: AbortSignal.timeout(config.timeoutMs),
+    });
+    if (!res.ok) {
+      console.warn(`[SafeClaw] HTTP ${res.status} from ${path}`);
+      return null;  // Caller checks failMode
+    }
+    return await res.json() as Record<string, unknown>;
+  } catch (e) {
+    if (e instanceof DOMException && e.name === 'TimeoutError') {
+      console.debug(`[SafeClaw] Timeout on ${path}`);
+    } else {
+      console.debug(`[SafeClaw] Service unavailable: ${path}`);
+    }
+    return null;  // Caller checks failMode
+  }
+}
+
+// --- Plugin Definition ---
+
+interface PluginEvent {
+  sessionId?: string;
+  userId?: string;
+  [key: string]: unknown;
+}
+
+interface PluginContext {
+  sessionId?: string;
+  userId?: string;
+  [key: string]: unknown;
+}
+
+interface PluginApi {
+  on(
+    event: string,
+    handler: (event: PluginEvent, ctx: PluginContext) => Promise<Record<string, unknown> | void> | void,
+    options?: { priority?: number },
+  ): void;
+}
+
+export default {
+  id: 'openclaw-safeclaw-plugin',
+  name: 'SafeClaw Neurosymbolic Governance',
+  version: '0.1.0',
+
+  register(api: PluginApi) {
+    if (!config.enabled) return;
+
+    // THE GATE — constraint checking on every tool call
+    api.on('before_tool_call', async (event: PluginEvent, ctx: PluginContext) => {
+      const r = await post('/evaluate/tool-call', {
+        sessionId: ctx.sessionId ?? event.sessionId,
+        userId: ctx.userId ?? event.userId,
+        toolName: event.toolName ?? event.tool_name,
+        params: event.params ?? {},
+        sessionHistory: event.sessionHistory ?? [],
+      });
+
+      if (r === null && config.failMode === 'closed' && config.enforcement === 'enforce') {
+        return { block: true, blockReason: 'SafeClaw service unavailable (fail-closed)' };
+      } else if (r === null && config.failMode === 'closed' && config.enforcement === 'warn-only') {
+        console.warn('[SafeClaw] Service unavailable (fail-closed mode, warn-only)');
+      }
+      if (r?.block) {
+        if (config.enforcement === 'enforce') {
+          return { block: true, blockReason: r.reason as string };
+        }
+        if (config.enforcement === 'warn-only') {
+          console.warn(`[SafeClaw] Warning: ${r.reason}`);
+        }
+        // audit-only: logged server-side, no action here
+      }
+    }, { priority: 100 });
+
+    // Context injection — prepend governance context to agent system prompt
+    api.on('before_agent_start', async (event: PluginEvent, ctx: PluginContext) => {
+      const r = await post('/context/build', {
+        sessionId: ctx.sessionId ?? event.sessionId,
+        userId: ctx.userId ?? event.userId,
+      });
+
+      if (r?.prependContext) {
+        return { prependContext: r.prependContext as string };
+      }
+    }, { priority: 100 });
+
+    // Message governance — check outbound messages
+    api.on('message_sending', async (event: PluginEvent, ctx: PluginContext) => {
+      const r = await post('/evaluate/message', {
+        sessionId: ctx.sessionId ?? event.sessionId,
+        userId: ctx.userId ?? event.userId,
+        to: event.to,
+        content: event.content,
+      });
+
+      if (r === null && config.failMode === 'closed' && config.enforcement === 'enforce') {
+        return { cancel: true };
+      } else if (r === null && config.failMode === 'closed' && config.enforcement === 'warn-only') {
+        console.warn('[SafeClaw] Service unavailable (fail-closed mode, warn-only)');
+      }
+      if (r?.block && config.enforcement === 'enforce') {
+        return { cancel: true };
+      }
+    }, { priority: 100 });
+
+    // Async logging — fire-and-forget, no return value needed
+    api.on('llm_input', (event: PluginEvent, ctx: PluginContext) => {
+      post('/log/llm-input', {
+        sessionId: ctx.sessionId ?? event.sessionId,
+        content: event.content,
+      }).catch(() => {});
+    });
+
+    api.on('llm_output', (event: PluginEvent, ctx: PluginContext) => {
+      post('/log/llm-output', {
+        sessionId: ctx.sessionId ?? event.sessionId,
+        content: event.content,
+      }).catch(() => {});
+    });
+
+    api.on('after_tool_call', (event: PluginEvent, ctx: PluginContext) => {
+      post('/record/tool-result', {
+        sessionId: ctx.sessionId ?? event.sessionId,
+        toolName: event.toolName ?? event.tool_name,
+        params: event.params ?? {},
+        result: event.result ?? '',
+        success: event.success ?? true,
+      }).catch(() => {});
+    });
+  },
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "openclaw-safeclaw-plugin",
+  "version": "0.1.0",
+  "description": "SafeClaw Neurosymbolic Governance plugin for OpenClaw — validates AI agent actions against OWL ontologies and SHACL constraints",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "dist/",
+    "index.ts",
+    "SKILL.md",
+    "README.md"
+  ],
+  "keywords": [
+    "openclaw",
+    "safeclaw",
+    "governance",
+    "neurosymbolic",
+    "ai-safety",
+    "owl",
+    "shacl",
+    "ontology",
+    "ai-agent",
+    "tool-validation"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tendlyeu/SafeClaw.git",
+    "directory": "openclaw-safeclaw-plugin"
+  },
+  "homepage": "https://safeclaw.eu",
+  "bugs": {
+    "url": "https://github.com/tendlyeu/SafeClaw/issues"
+  },
+  "author": "Tendly EU",
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "@types/node": "^20.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}