@randromeda/arbiter-openclaw 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to `@randromeda/arbiter-openclaw` will be documented in this file.
+
+## [0.1.0] - 2026-04-02
+
+- Initial native OpenClaw plugin implementation.
+- `before_tool_call` enforcement with Arbiter intercept + verify.
+- `after_tool_call` state recording support.
+- Config schema, package metadata, and local/npm install docs.
+- Unit tests for config, deny/allow paths, and state recording.

package/README.md

@@ -0,0 +1,109 @@
+# OpenClaw Native Plugin
+
+This package provides a native OpenClaw plugin that enforces Arbiter policy decisions for protected tool calls.
+
+Behavior:
+
+- Intercepts protected tools in `before_tool_call`.
+- Calls Arbiter `POST /v1/intercept/framework/generic`.
+- Requires successful Arbiter verify via `POST /v1/execute/verify/canonical` before execution.
+- Records post-call outcomes to `POST /v1/state/actions` (enabled by default).
+
+## Install
+
+Published package target:
+
+1. `@randromeda/arbiter-openclaw`
+
+Install from npm:
+
+```bash
+openclaw plugins install @randromeda/arbiter-openclaw
+```
+
+Install from local path:
+
+```bash
+openclaw plugins install ./integrations/openclaw-plugin
+```
+
+## Config
+
+Add plugin config under `plugins.entries.arbiter-openclaw.config` in your OpenClaw config:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "arbiter-openclaw": {
+        "enabled": true,
+        "config": {
+          "arbiterUrl": "http://localhost:8080",
+          "tenantId": "tenant-demo",
+          "gatewayKey": "gw-key",
+          "serviceKey": "svc-key",
+          "protectTools": ["exec", "process", "write", "edit", "apply_patch"],
+          "recordState": true,
+          "failClosed": true
+        }
+      }
+    }
+  }
+}
+```
+
+Config options:
+
+- `arbiterUrl`: Arbiter base URL.
+- `tenantId`: Tenant ID for canonical requests and state records.
+- `gatewayKey`: Optional key for intercept routes.
+- `serviceKey`: Optional key for verify/state routes.
+- `actorIdMode`: `agent-id` (default) or `config`.
+- `actorId`: Required only when `actorIdMode=config`.
+- `protectTools`: Tool names guarded by Arbiter.
+- `recordState`: Record outcomes to `/v1/state/actions` (default `true`).
+- `failClosed`: Block on Arbiter errors (default `true`).
+- `timeoutMs`: Per-request timeout (default `5000`).
+
+## Stock OpenClaw Tool Mapping
+
+The default protected tools are:
+
+- `exec`
+- `process`
+- `write`
+- `edit`
+- `apply_patch`
+
+Use Arbiter policy to allow or deny these tools. The included Arbiter filesystem policy denies destructive delete commands and `apply_patch` file-deletion directives.
+
+## Development
+
+Run plugin tests:
+
+```bash
+cd integrations/openclaw-plugin
+npm test
+```
+
+Verify package metadata:
+
+```bash
+cd integrations/openclaw-plugin
+npm run pack:check
+```
+
+## CI Publish
+
+GitHub Actions can publish this package to npm via `.github/workflows/openclaw-plugin-publish.yml`.
+
+Requirements:
+
+- Repository secret `NPM_TOKEN` with publish access to `@randromeda/arbiter-openclaw`.
+
+Publish options:
+
+- Run `npm run release:tag` from `integrations/openclaw-plugin` to create and push `openclaw-plugin-v<version>` automatically.
+- For validation without changing git state, run `npm run release:tag -- --dry-run`.
+- Or push tag `openclaw-plugin-v<version>` manually (must match `package.json` version), for example `openclaw-plugin-v0.1.0`.
+- Or run the `openclaw-plugin-publish` workflow manually from the Actions UI.

package/SEMVER.md

@@ -0,0 +1,27 @@
+# Versioning Policy
+
+`@randromeda/arbiter-openclaw` uses Semantic Versioning (`MAJOR.MINOR.PATCH`).
+
+## Rules
+
+- `MAJOR`: breaking config contract, hook behavior, or install/runtime expectations.
+- `MINOR`: backward-compatible features, new guardrail options, new supported tools.
+- `PATCH`: backward-compatible bug fixes, policy mapping fixes, docs corrections.
+
+## Stability Notes
+
+- Current status is pre-1.0 (`0.x`), so minor versions may include breaking changes.
+- After `1.0.0`, breaking changes move to major version bumps.
+
+## Release Checklist
+
+1. Update package version in `package.json`.
+2. Add changelog entry in `CHANGELOG.md`.
+3. Run tests:
+   - `npm test`
+4. Validate package metadata:
+   - `npm run pack:check`
+5. Publish:
+   - run `npm run release:tag` (or `npm run release:tag -- --dry-run`) from `integrations/openclaw-plugin`.
+   - alternatively, push git tag `openclaw-plugin-v<version>` manually to trigger CI publish.
+   - workflow `openclaw-plugin-publish` can also be run manually.

package/index.js

@@ -0,0 +1,19 @@
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { createArbiterGuardrail } from "./src/guardrail.js";
+
+export default definePluginEntry({
+  id: "arbiter-openclaw",
+  name: "Arbiter Guardrails",
+  description: "Enforce Arbiter policy decisions before OpenClaw tool execution.",
+  register(api) {
+    const guardrail = createArbiterGuardrail({
+      pluginConfig: api.pluginConfig,
+      logger: api.logger,
+      fetchImpl: globalThis.fetch,
+      env: process.env
+    });
+
+    api.on("before_tool_call", guardrail.beforeToolCall);
+    api.on("after_tool_call", guardrail.afterToolCall);
+  }
+});

package/openclaw.plugin.json

@@ -0,0 +1,110 @@
+{
+  "id": "arbiter-openclaw",
+  "name": "Arbiter Guardrails",
+  "description": "Enforce Arbiter policy decisions for OpenClaw tool calls before execution.",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "arbiterUrl": {
+        "type": "string",
+        "format": "uri",
+        "pattern": "^[Hh][Tt][Tt][Pp][Ss]?://"
+      },
+      "tenantId": {
+        "type": "string",
+        "minLength": 1
+      },
+      "gatewayKey": {
+        "type": "string"
+      },
+      "serviceKey": {
+        "type": "string"
+      },
+      "actorIdMode": {
+        "type": "string",
+        "enum": [
+          "agent-id",
+          "config"
+        ],
+        "default": "agent-id"
+      },
+      "actorId": {
+        "type": "string"
+      },
+      "protectTools": {
+        "type": "array",
+        "items": {
+          "type": "string",
+          "minLength": 1
+        },
+        "default": [
+          "exec",
+          "process",
+          "write",
+          "edit",
+          "apply_patch"
+        ]
+      },
+      "recordState": {
+        "type": "boolean",
+        "default": true
+      },
+      "failClosed": {
+        "type": "boolean",
+        "default": true
+      },
+      "timeoutMs": {
+        "type": "integer",
+        "minimum": 250,
+        "maximum": 60000,
+        "default": 5000
+      }
+    }
+  },
+  "uiHints": {
+    "arbiterUrl": {
+      "label": "Arbiter Base URL",
+      "help": "Base URL for the Arbiter interceptor, for example http://localhost:8080."
+    },
+    "tenantId": {
+      "label": "Tenant ID",
+      "help": "Tenant identifier included in canonical requests and state records."
+    },
+    "gatewayKey": {
+      "label": "Gateway Shared Key",
+      "help": "Optional key for /v1/intercept routes when Arbiter gateway auth is enabled.",
+      "sensitive": true
+    },
+    "serviceKey": {
+      "label": "Service Shared Key",
+      "help": "Optional key for /v1/execute/verify and /v1/state/actions routes.",
+      "sensitive": true
+    },
+    "actorIdMode": {
+      "label": "Actor ID Source",
+      "help": "Use OpenClaw agent ID by default or force a fixed actor ID from plugin config."
+    },
+    "actorId": {
+      "label": "Fixed Actor ID",
+      "help": "Used only when actorIdMode is config."
+    },
+    "protectTools": {
+      "label": "Protected Tool Names",
+      "help": "Only tools in this list are intercepted by Arbiter."
+    },
+    "recordState": {
+      "label": "Record Action State",
+      "help": "When enabled, sends /v1/state/actions after guarded tool calls."
+    },
+    "failClosed": {
+      "label": "Fail Closed",
+      "help": "Block protected tool calls when Arbiter is unavailable or responses are invalid."
+    },
+    "timeoutMs": {
+      "label": "HTTP Timeout (ms)",
+      "help": "Per-request timeout for Arbiter intercept, verify, and state calls.",
+      "advanced": true
+    }
+  }
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@randromeda/arbiter-openclaw",
+  "version": "0.1.0",
+  "description": "OpenClaw native plugin that enforces Arbiter guardrails before tool execution.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "index.js",
+    "openclaw.plugin.json",
+    "src",
+    "scripts",
+    "README.md",
+    "CHANGELOG.md",
+    "SEMVER.md"
+  ],
+  "exports": {
+    ".": "./index.js"
+  },
+  "scripts": {
+    "test": "node --test ./test/*.test.js",
+    "pack:check": "npm pack --dry-run",
+    "release:tag": "bash ./scripts/release-tag.sh"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.js"
+    ]
+  }
+}

package/scripts/release-tag.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+DRY_RUN="${1:-}"
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../../.." && pwd)"
+PACKAGE_JSON="${REPO_ROOT}/integrations/openclaw-plugin/package.json"
+
+if ! command -v node >/dev/null 2>&1; then
+  echo "node is required but not found in PATH."
+  exit 1
+fi
+
+VERSION="$(node -e "console.log(require(process.argv[1]).version)" "$PACKAGE_JSON")"
+TAG="openclaw-plugin-v${VERSION}"
+
+if [[ -z "${VERSION}" ]]; then
+  echo "failed to resolve version from ${PACKAGE_JSON}."
+  exit 1
+fi
+
+if [[ "${DRY_RUN}" == "--dry-run" ]]; then
+  if ! git -C "${REPO_ROOT}" diff --quiet || ! git -C "${REPO_ROOT}" diff --cached --quiet; then
+    echo "dry run: working tree is not clean; a real tag run would fail."
+  fi
+  echo "dry run: would run 'git tag -a ${TAG} -m \"OpenClaw plugin ${VERSION}\"'"
+  echo "dry run: would run 'git push origin ${TAG}'"
+  exit 0
+fi
+
+if ! git -C "${REPO_ROOT}" diff --quiet || ! git -C "${REPO_ROOT}" diff --cached --quiet; then
+  echo "working tree is not clean. commit or stash changes before tagging."
+  exit 1
+fi
+
+if git -C "${REPO_ROOT}" rev-parse -q --verify "refs/tags/${TAG}" >/dev/null; then
+  echo "tag ${TAG} already exists."
+  exit 1
+fi
+
+if [[ -n "${DRY_RUN}" ]]; then
+  echo "unknown argument: ${DRY_RUN}"
+  echo "usage: npm run release:tag [-- --dry-run]"
+  exit 1
+fi
+
+git -C "${REPO_ROOT}" tag -a "${TAG}" -m "OpenClaw plugin ${VERSION}"
+git -C "${REPO_ROOT}" push origin "${TAG}"
+echo "created and pushed ${TAG}"

package/src/canonical.js

@@ -0,0 +1,56 @@
+import { resolveSessionMetadata } from "./config.js";
+
+const SCHEMA_VERSION = "v1alpha1";
+
+function randomSuffix() {
+  if (globalThis.crypto && typeof globalThis.crypto.randomUUID === "function") {
+    return globalThis.crypto.randomUUID();
+  }
+  return `${Date.now()}-${Math.random().toString(16).slice(2)}`;
+}
+
+export function createRequestId(event) {
+  const runId = typeof event.runId === "string" ? event.runId.trim() : "";
+  const toolCallId = typeof event.toolCallId === "string" ? event.toolCallId.trim() : "";
+
+  if (runId && toolCallId) {
+    return `${runId}:${toolCallId}`;
+  }
+  if (toolCallId) {
+    return `tool:${toolCallId}`;
+  }
+  if (runId) {
+    return `${runId}:${randomSuffix()}`;
+  }
+  return `arbiter-${randomSuffix()}`;
+}
+
+export function buildCanonicalRequest({ config, event, ctx, actorId, requestId }) {
+  const session = resolveSessionMetadata(ctx);
+  const metadata = {
+    request_id: requestId,
+    tenant_id: config.tenantId,
+    provider: "framework"
+  };
+
+  if (session.sessionId) {
+    metadata.session_id = session.sessionId;
+  } else if (session.sessionKey) {
+    metadata.session_id = session.sessionKey;
+  }
+  if (typeof event.runId === "string" && event.runId.trim()) {
+    metadata.trace_id = event.runId.trim();
+  }
+
+  return {
+    schema_version: SCHEMA_VERSION,
+    metadata,
+    agent_context: {
+      actor: {
+        id: actorId
+      }
+    },
+    tool_name: event.toolName,
+    parameters: event.params ?? {}
+  };
+}

package/src/config.js

@@ -0,0 +1,95 @@
+export const DEFAULT_PROTECT_TOOLS = ["exec", "process", "write", "edit", "apply_patch"];
+export const DEFAULT_TIMEOUT_MS = 5000;
+
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+
+function asString(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function asBool(value, fallback) {
+  return typeof value === "boolean" ? value : fallback;
+}
+
+function asTimeoutMs(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return DEFAULT_TIMEOUT_MS;
+  }
+  if (value < 250) {
+    return 250;
+  }
+  if (value > 60000) {
+    return 60000;
+  }
+  return Math.round(value);
+}
+
+function normalizeToolList(value) {
+  if (!Array.isArray(value)) {
+    return DEFAULT_PROTECT_TOOLS.slice();
+  }
+  const tools = value
+    .map((entry) => asString(entry))
+    .filter(Boolean);
+  return tools.length > 0 ? Array.from(new Set(tools)) : DEFAULT_PROTECT_TOOLS.slice();
+}
+
+export function resolvePluginConfig(pluginConfig, env = process.env) {
+  const cfg = asRecord(pluginConfig);
+  const runtimeEnv = asRecord(env);
+
+  const arbiterUrl = asString(cfg.arbiterUrl) || asString(runtimeEnv.ARBITER_URL);
+  const tenantId = asString(cfg.tenantId) || asString(runtimeEnv.ARBITER_TENANT_ID);
+  const gatewayKey = asString(cfg.gatewayKey) || asString(runtimeEnv.ARBITER_GATEWAY_SHARED_KEY);
+  const serviceKey = asString(cfg.serviceKey) || asString(runtimeEnv.ARBITER_SERVICE_SHARED_KEY);
+  const actorId = asString(cfg.actorId) || asString(runtimeEnv.ARBITER_ACTOR_ID);
+
+  const actorIdMode = asString(cfg.actorIdMode) === "config" ? "config" : "agent-id";
+  const protectTools = normalizeToolList(cfg.protectTools);
+  const recordState = asBool(cfg.recordState, true);
+  const failClosed = asBool(cfg.failClosed, true);
+  const timeoutMs = asTimeoutMs(cfg.timeoutMs);
+
+  const missing = [];
+  if (!arbiterUrl) {
+    missing.push("arbiterUrl");
+  }
+  if (!tenantId) {
+    missing.push("tenantId");
+  }
+  if (actorIdMode === "config" && !actorId) {
+    missing.push("actorId");
+  }
+
+  return {
+    arbiterUrl: arbiterUrl.replace(/\/$/, ""),
+    tenantId,
+    gatewayKey,
+    serviceKey,
+    actorIdMode,
+    actorId,
+    protectTools,
+    recordState,
+    failClosed,
+    timeoutMs,
+    missing
+  };
+}
+
+export function resolveActorId(config, ctx) {
+  const hookCtx = asRecord(ctx);
+  if (config.actorIdMode === "config") {
+    return config.actorId;
+  }
+  return asString(hookCtx.agentId) || config.actorId || "openclaw-agent";
+}
+
+export function resolveSessionMetadata(ctx) {
+  const hookCtx = asRecord(ctx);
+  return {
+    sessionId: asString(hookCtx.sessionId),
+    sessionKey: asString(hookCtx.sessionKey)
+  };
+}

package/src/guardrail.js

@@ -0,0 +1,187 @@
+import { buildCanonicalRequest, createRequestId } from "./canonical.js";
+import { resolveActorId, resolvePluginConfig } from "./config.js";
+import { postJSON } from "./http.js";
+
+function isProtectedTool(toolSet, toolName) {
+  return typeof toolName === "string" && toolSet.has(toolName);
+}
+
+function decisionReason(body) {
+  if (!body || typeof body !== "object") {
+    return "";
+  }
+  if (typeof body.error === "string" && body.error.trim()) {
+    return body.error.trim();
+  }
+  const decision = body.decision;
+  if (decision && typeof decision === "object" && typeof decision.reason === "string") {
+    return decision.reason.trim();
+  }
+  return "";
+}
+
+function block(reason) {
+  return {
+    block: true,
+    blockReason: reason
+  };
+}
+
+function configError(config) {
+  if (!config.missing.length) {
+    return "";
+  }
+  return `arbiter plugin misconfigured: missing ${config.missing.join(", ")}`;
+}
+
+function serviceHeaders(config) {
+  return config.serviceKey ? { "X-Arbiter-Service-Key": config.serviceKey } : {};
+}
+
+function gatewayHeaders(config) {
+  return config.gatewayKey ? { "X-Arbiter-Gateway-Key": config.gatewayKey } : {};
+}
+
+export function createArbiterGuardrail({
+  pluginConfig,
+  logger,
+  fetchImpl = globalThis.fetch,
+  env = process.env
+}) {
+  const config = resolvePluginConfig(pluginConfig, env);
+  const protectedTools = new Set(config.protectTools);
+
+  async function beforeToolCall(event, ctx) {
+    if (!isProtectedTool(protectedTools, event?.toolName)) {
+      return;
+    }
+
+    const cfgError = configError(config);
+    if (cfgError) {
+      if (config.failClosed) {
+        return block(cfgError);
+      }
+      logger?.warn?.(`${cfgError}; allowing because failClosed=false`);
+      return;
+    }
+
+    const actorId = resolveActorId(config, ctx);
+    const requestId = createRequestId(event);
+    const canonical = buildCanonicalRequest({
+      config,
+      event,
+      ctx,
+      actorId,
+      requestId
+    });
+
+    let intercept;
+    try {
+      intercept = await postJSON({
+        fetchImpl,
+        baseUrl: config.arbiterUrl,
+        path: "/v1/intercept/framework/generic",
+        headers: gatewayHeaders(config),
+        payload: canonical,
+        timeoutMs: config.timeoutMs
+      });
+    } catch (err) {
+      if (config.failClosed) {
+        return block(`arbiter intercept failed: ${String(err)}`);
+      }
+      logger?.warn?.(`arbiter intercept failed; allowing because failClosed=false: ${String(err)}`);
+      return;
+    }
+
+    const interceptReason = decisionReason(intercept.body);
+    if (intercept.status !== 200) {
+      if (intercept.status === 403) {
+        return block(interceptReason || "blocked by arbiter policy");
+      }
+      if (config.failClosed) {
+        return block(`arbiter intercept failed (${intercept.status})${interceptReason ? `: ${interceptReason}` : ""}`);
+      }
+      logger?.warn?.(`arbiter intercept status=${intercept.status}; allowing because failClosed=false`);
+      return;
+    }
+
+    const token = intercept.body?.token;
+    if (typeof token !== "string" || !token.trim()) {
+      if (config.failClosed) {
+        return block("arbiter intercept response missing token");
+      }
+      logger?.warn?.("arbiter intercept response missing token; allowing because failClosed=false");
+      return;
+    }
+
+    let verify;
+    try {
+      verify = await postJSON({
+        fetchImpl,
+        baseUrl: config.arbiterUrl,
+        path: "/v1/execute/verify/canonical",
+        headers: serviceHeaders(config),
+        payload: {
+          token,
+          request: canonical
+        },
+        timeoutMs: config.timeoutMs
+      });
+    } catch (err) {
+      if (config.failClosed) {
+        return block(`arbiter verify failed: ${String(err)}`);
+      }
+      logger?.warn?.(`arbiter verify failed; allowing because failClosed=false: ${String(err)}`);
+      return;
+    }
+
+    if (verify.status !== 200) {
+      const verifyReason = decisionReason(verify.body);
+      return block(`arbiter verify denied${verifyReason ? `: ${verifyReason}` : ""}`);
+    }
+  }
+
+  async function afterToolCall(event, ctx) {
+    if (!config.recordState || !isProtectedTool(protectedTools, event?.toolName)) {
+      return;
+    }
+    if (!config.tenantId) {
+      return;
+    }
+
+    const actorId = resolveActorId(config, ctx);
+    const outcome = event?.error ? "error" : "allowed";
+    const payload = {
+      tenant_id: config.tenantId,
+      actor_id: actorId,
+      tool_name: event.toolName,
+      outcome
+    };
+    if (ctx?.sessionId && typeof ctx.sessionId === "string") {
+      payload.session_id = ctx.sessionId;
+    } else if (ctx?.sessionKey && typeof ctx.sessionKey === "string") {
+      payload.session_id = ctx.sessionKey;
+    }
+
+    try {
+      const response = await postJSON({
+        fetchImpl,
+        baseUrl: config.arbiterUrl,
+        path: "/v1/state/actions",
+        headers: serviceHeaders(config),
+        payload,
+        timeoutMs: config.timeoutMs
+      });
+      if (response.status !== 202 && response.status !== 200) {
+        logger?.warn?.(`arbiter state record returned status=${response.status}`);
+      }
+    } catch (err) {
+      logger?.warn?.(`arbiter state record failed: ${String(err)}`);
+    }
+  }
+
+  return {
+    beforeToolCall,
+    afterToolCall
+  };
+}

package/src/http.js

@@ -0,0 +1,43 @@
+function joinUrl(baseUrl, path) {
+  const base = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+  const normalized = path.startsWith("/") ? path.slice(1) : path;
+  return new URL(normalized, base).toString();
+}
+
+async function parseJSONResponse(resp) {
+  const text = await resp.text();
+  if (!text) {
+    return null;
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { error: text };
+  }
+}
+
+export async function postJSON({ fetchImpl, baseUrl, path, headers, payload, timeoutMs }) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetchImpl(joinUrl(baseUrl, path), {
+      method: "POST",
+      headers: {
+        Accept: "application/json",
+        "Content-Type": "application/json",
+        ...headers
+      },
+      body: JSON.stringify(payload),
+      signal: controller.signal
+    });
+
+    const body = await parseJSONResponse(response);
+    return {
+      status: response.status,
+      ok: response.ok,
+      body
+    };
+  } finally {
+    clearTimeout(timeout);
+  }
+}