openclaw-safeclaw-plugin 0.8.2 → 0.9.1

package/cli.tsx

@@ -267,7 +267,55 @@ if (command === 'connect') {
     }
   }
 
-  // 5. OpenClaw installed
+  // 5. Handshake — validates API key actually works
+  if (serviceHealthy && cfg.apiKey) {
+    try {
+      const res = await fetch(`${cfg.serviceUrl}/handshake`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Authorization': `Bearer ${cfg.apiKey}`,
+        },
+        body: JSON.stringify({ pluginVersion: '0.1.3', configHash: '' }),
+        signal: AbortSignal.timeout(cfg.timeoutMs),
+      });
+      if (res.ok) {
+        const data = await res.json() as Record<string, unknown>;
+        console.log(`[ok] Handshake: org=${data.orgId}, scope=${data.scope}, engine=${data.engineReady ? 'ready' : 'not ready'}`);
+      } else {
+        let detail = `HTTP ${res.status}`;
+        try {
+          const body = await res.json() as Record<string, unknown>;
+          detail = (body.error ?? body.detail ?? detail) as string;
+        } catch { /* ignore parse errors */ }
+        console.log(`[!!] Handshake failed: ${detail}`);
+        if (res.status === 401) {
+          console.log('     ↳ API key is invalid or revoked. Get a new key at https://safeclaw.eu/dashboard');
+        } else if (res.status === 403) {
+          console.log('     ↳ API key lacks required scope. Check key permissions in your dashboard.');
+        } else if (res.status === 500) {
+          console.log('     ↳ Server error — check service logs for details.');
+        }
+        allOk = false;
+      }
+    } catch (e) {
+      const isTimeout = e instanceof DOMException && e.name === 'TimeoutError';
+      if (isTimeout) {
+        console.log(`[!!] Handshake failed: timeout after ${cfg.timeoutMs}ms`);
+        console.log('     ↳ Service may be overloaded. Try increasing SAFECLAW_TIMEOUT_MS.');
+      } else {
+        console.log('[!!] Handshake failed: could not connect');
+        console.log(`     ↳ Is the service running at ${cfg.serviceUrl}?`);
+      }
+      allOk = false;
+    }
+  } else if (serviceHealthy && !cfg.apiKey) {
+    console.log('[!!] Handshake: skipped — no API key configured');
+    console.log('     ↳ Run: safeclaw connect <your-api-key>');
+    allOk = false;
+  }
+
+  // 6. OpenClaw installed
   try {
     execSync('which openclaw', { encoding: 'utf-8', stdio: 'pipe' });
     console.log('[ok] OpenClaw: installed');
@@ -276,7 +324,7 @@ if (command === 'connect') {
     allOk = false;
   }
 
-  // 6. Plugin extension files exist
+  // 7. Plugin extension files exist
   const extensionDir = join(homedir(), '.openclaw', 'extensions', 'safeclaw');
   const hasManifest = existsSync(join(extensionDir, 'openclaw.plugin.json'));
   const hasEntry = existsSync(join(extensionDir, 'index.js'));
@@ -295,7 +343,7 @@ if (command === 'connect') {
     allOk = false;
   }
 
-  // 7. Plugin enabled in OpenClaw config
+  // 8. Plugin enabled in OpenClaw config
   const ocConfigPath = join(homedir(), '.openclaw', 'openclaw.json');
   if (existsSync(ocConfigPath)) {
     const ocConfig = readJson(ocConfigPath);

package/dist/cli.js

@@ -261,7 +261,61 @@ else if (command === 'status') {
             allOk = false;
         }
     }
-    // 5. OpenClaw installed
+    // 5. Handshake — validates API key actually works
+    if (serviceHealthy && cfg.apiKey) {
+        try {
+            const res = await fetch(`${cfg.serviceUrl}/handshake`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Authorization': `Bearer ${cfg.apiKey}`,
+                },
+                body: JSON.stringify({ pluginVersion: '0.1.3', configHash: '' }),
+                signal: AbortSignal.timeout(cfg.timeoutMs),
+            });
+            if (res.ok) {
+                const data = await res.json();
+                console.log(`[ok] Handshake: org=${data.orgId}, scope=${data.scope}, engine=${data.engineReady ? 'ready' : 'not ready'}`);
+            }
+            else {
+                let detail = `HTTP ${res.status}`;
+                try {
+                    const body = await res.json();
+                    detail = (body.error ?? body.detail ?? detail);
+                }
+                catch { /* ignore parse errors */ }
+                console.log(`[!!] Handshake failed: ${detail}`);
+                if (res.status === 401) {
+                    console.log('     ↳ API key is invalid or revoked. Get a new key at https://safeclaw.eu/dashboard');
+                }
+                else if (res.status === 403) {
+                    console.log('     ↳ API key lacks required scope. Check key permissions in your dashboard.');
+                }
+                else if (res.status === 500) {
+                    console.log('     ↳ Server error — check service logs for details.');
+                }
+                allOk = false;
+            }
+        }
+        catch (e) {
+            const isTimeout = e instanceof DOMException && e.name === 'TimeoutError';
+            if (isTimeout) {
+                console.log(`[!!] Handshake failed: timeout after ${cfg.timeoutMs}ms`);
+                console.log('     ↳ Service may be overloaded. Try increasing SAFECLAW_TIMEOUT_MS.');
+            }
+            else {
+                console.log('[!!] Handshake failed: could not connect');
+                console.log(`     ↳ Is the service running at ${cfg.serviceUrl}?`);
+            }
+            allOk = false;
+        }
+    }
+    else if (serviceHealthy && !cfg.apiKey) {
+        console.log('[!!] Handshake: skipped — no API key configured');
+        console.log('     ↳ Run: safeclaw connect <your-api-key>');
+        allOk = false;
+    }
+    // 6. OpenClaw installed
     try {
         execSync('which openclaw', { encoding: 'utf-8', stdio: 'pipe' });
         console.log('[ok] OpenClaw: installed');
@@ -270,7 +324,7 @@ else if (command === 'status') {
         console.log('[!!] OpenClaw: not found in PATH');
         allOk = false;
     }
-    // 6. Plugin extension files exist
+    // 7. Plugin extension files exist
     const extensionDir = join(homedir(), '.openclaw', 'extensions', 'safeclaw');
     const hasManifest = existsSync(join(extensionDir, 'openclaw.plugin.json'));
     const hasEntry = existsSync(join(extensionDir, 'index.js'));
@@ -291,7 +345,7 @@ else if (command === 'status') {
         console.log('[!!] Plugin: not installed. Run: safeclaw setup');
         allOk = false;
     }
-    // 7. Plugin enabled in OpenClaw config
+    // 8. Plugin enabled in OpenClaw config
     const ocConfigPath = join(homedir(), '.openclaw', 'openclaw.json');
     if (existsSync(ocConfigPath)) {
         const ocConfig = readJson(ocConfigPath);

package/dist/index.js

@@ -53,6 +53,24 @@ async function post(path, body) {
         return null; // Caller checks failMode
     }
 }
+let handshakeCompleted = false;
+async function performHandshake() {
+    if (!config.apiKey) {
+        console.warn('[SafeClaw] No API key configured — skipping handshake');
+        return false;
+    }
+    const r = await post('/handshake', {
+        pluginVersion: '0.1.3',
+        configHash: configHash(config),
+    });
+    if (r === null) {
+        console.warn('[SafeClaw] ✗ Handshake failed — API key may be invalid or service unreachable');
+        return false;
+    }
+    console.log(`[SafeClaw] ✓ Handshake OK — org=${r.orgId}, scope=${r.scope}, engine=${r.engineReady ? 'ready' : 'not ready'}`);
+    handshakeCompleted = true;
+    return true;
+}
 async function checkConnection() {
     const label = `[SafeClaw]`;
     console.log(`${label} Connecting to ${config.serviceUrl} ...`);
@@ -82,7 +100,7 @@ async function checkConnection() {
 export default {
     id: 'safeclaw',
     name: 'SafeClaw Neurosymbolic Governance',
-    version: '0.1.2',
+    version: '0.1.3',
     register(api) {
         if (!config.enabled) {
             console.log('[SafeClaw] Plugin disabled');
@@ -106,8 +124,16 @@ export default {
                 // Heartbeat failure is non-fatal
             }
         };
-        // Start heartbeat after connection check
-        checkConnection().then(() => sendHeartbeat()).catch(() => { });
+        // Start heartbeat after connection check + handshake
+        checkConnection()
+            .then(() => performHandshake())
+            .then((ok) => {
+            if (!ok && config.failMode === 'closed') {
+                console.warn('[SafeClaw] ⚠ Handshake failed with fail-mode=closed — tool calls will be BLOCKED');
+            }
+            return sendHeartbeat();
+        })
+            .catch(() => { });
         const heartbeatInterval = setInterval(sendHeartbeat, 30000);
         // Clean shutdown: send shutdown heartbeat and clear interval
         const shutdown = () => {
@@ -127,6 +153,9 @@ export default {
         process.on('SIGTERM', () => { shutdown(); process.exit(0); });
         // THE GATE — constraint checking on every tool call
         api.on('before_tool_call', async (event, ctx) => {
+            if (!handshakeCompleted && config.failMode === 'closed' && config.enforcement === 'enforce') {
+                return { block: true, blockReason: 'SafeClaw handshake not completed (fail-closed)' };
+            }
             const r = await post('/evaluate/tool-call', {
                 sessionId: ctx.sessionId ?? event.sessionId,
                 userId: ctx.userId ?? event.userId,

package/index.ts

@@ -79,6 +79,29 @@ interface PluginApi {
   ): void;
 }
 
+let handshakeCompleted = false;
+
+async function performHandshake(): Promise<boolean> {
+  if (!config.apiKey) {
+    console.warn('[SafeClaw] No API key configured — skipping handshake');
+    return false;
+  }
+
+  const r = await post('/handshake', {
+    pluginVersion: '0.1.3',
+    configHash: configHash(config),
+  });
+
+  if (r === null) {
+    console.warn('[SafeClaw] ✗ Handshake failed — API key may be invalid or service unreachable');
+    return false;
+  }
+
+  console.log(`[SafeClaw] ✓ Handshake OK — org=${r.orgId}, scope=${r.scope}, engine=${r.engineReady ? 'ready' : 'not ready'}`);
+  handshakeCompleted = true;
+  return true;
+}
+
 async function checkConnection(): Promise<void> {
   const label = `[SafeClaw]`;
   console.log(`${label} Connecting to ${config.serviceUrl} ...`);
@@ -107,7 +130,7 @@ async function checkConnection(): Promise<void> {
 export default {
   id: 'safeclaw',
   name: 'SafeClaw Neurosymbolic Governance',
-  version: '0.1.2',
+  version: '0.1.3',
 
   register(api: PluginApi) {
     if (!config.enabled) {
@@ -133,8 +156,16 @@ export default {
       }
     };
 
-    // Start heartbeat after connection check
-    checkConnection().then(() => sendHeartbeat()).catch(() => {});
+    // Start heartbeat after connection check + handshake
+    checkConnection()
+      .then(() => performHandshake())
+      .then((ok) => {
+        if (!ok && config.failMode === 'closed') {
+          console.warn('[SafeClaw] ⚠ Handshake failed with fail-mode=closed — tool calls will be BLOCKED');
+        }
+        return sendHeartbeat();
+      })
+      .catch(() => {});
     const heartbeatInterval = setInterval(sendHeartbeat, 30000);
 
     // Clean shutdown: send shutdown heartbeat and clear interval
@@ -156,6 +187,10 @@ export default {
 
     // THE GATE — constraint checking on every tool call
     api.on('before_tool_call', async (event: PluginEvent, ctx: PluginContext) => {
+      if (!handshakeCompleted && config.failMode === 'closed' && config.enforcement === 'enforce') {
+        return { block: true, blockReason: 'SafeClaw handshake not completed (fail-closed)' };
+      }
+
       const r = await post('/evaluate/tool-call', {
         sessionId: ctx.sessionId ?? event.sessionId,
         userId: ctx.userId ?? event.userId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-safeclaw-plugin",
-  "version": "0.8.2",
+  "version": "0.9.1",
   "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",