@plusplus7/clawclamp 0.1.0

package/src/audit.ts

@@ -0,0 +1,94 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import type { AuditEntry } from "./types.js";
+import { withStateFileLock } from "./storage.js";
+
+const AUDIT_FILE = "audit.jsonl";
+const AUDIT_ROTATE_MAX_LINES = 5000;
+const AUDIT_ROTATE_KEEP_LINES = 2500;
+
+function resolveAuditPath(stateDir: string): string {
+  return path.join(stateDir, "clawclamp", AUDIT_FILE);
+}
+
+function resolveAuditArchivePath(stateDir: string, timestamp: string): string {
+  return path.join(stateDir, "clawclamp", `audit-${timestamp}.jsonl`);
+}
+
+export function createAuditEntryId(): string {
+  return randomUUID();
+}
+
+export async function appendAuditEntry(stateDir: string, entry: AuditEntry): Promise<void> {
+  await withStateFileLock(stateDir, "audit", async () => {
+    const filePath = resolveAuditPath(stateDir);
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.appendFile(filePath, `${JSON.stringify(entry)}\n`, "utf8");
+    await rotateAuditLogIfNeeded(stateDir, filePath);
+  });
+}
+
+async function rotateAuditLogIfNeeded(stateDir: string, filePath: string): Promise<void> {
+  let raw: string;
+  try {
+    raw = await fs.readFile(filePath, "utf8");
+  } catch (error) {
+    const code = (error as { code?: string }).code;
+    if (code === "ENOENT") {
+      return;
+    }
+    throw error;
+  }
+  const lines = raw.split("\n").filter(Boolean);
+  if (lines.length <= AUDIT_ROTATE_MAX_LINES) {
+    return;
+  }
+  const cutoff = Math.max(0, lines.length - AUDIT_ROTATE_KEEP_LINES);
+  const archived = lines.slice(0, cutoff);
+  const current = lines.slice(cutoff);
+  const archivePath = resolveAuditArchivePath(stateDir, new Date().toISOString().replace(/[:.]/g, "-"));
+  await fs.writeFile(archivePath, `${archived.join("\n")}\n`, "utf8");
+  await fs.writeFile(filePath, current.length ? `${current.join("\n")}\n` : "", "utf8");
+}
+
+export async function readAuditEntries(
+  stateDir: string,
+  page: number,
+  pageSize: number,
+): Promise<{ entries: AuditEntry[]; total: number; page: number }> {
+  return withStateFileLock(stateDir, "audit", async () => {
+    const filePath = resolveAuditPath(stateDir);
+    let raw: string;
+    try {
+      raw = await fs.readFile(filePath, "utf8");
+    } catch (error) {
+      const code = (error as { code?: string }).code;
+      if (code === "ENOENT") {
+        return { entries: [], total: 0, page: 1 };
+      }
+      throw error;
+    }
+
+    const lines = raw.trim().split("\n").filter(Boolean);
+    const total = lines.length;
+    const safePageSize = Math.max(1, pageSize);
+    const totalPages = Math.max(1, Math.ceil(total / safePageSize));
+    const safePage = Math.min(Math.max(1, page), totalPages);
+    const start = Math.max(0, total - safePage * safePageSize);
+    const end = total - (safePage - 1) * safePageSize;
+    const recent = lines.slice(start, end);
+    const entries: AuditEntry[] = [];
+    for (const line of recent) {
+      try {
+        const parsed = JSON.parse(line) as AuditEntry;
+        if (parsed && typeof parsed === "object") {
+          entries.push(parsed);
+        }
+      } catch {
+        // Ignore malformed lines.
+      }
+    }
+    return { entries, total, page: safePage };
+  });
+}

package/src/cedarling.ts

@@ -0,0 +1,46 @@
+import initWasm, { init } from "@janssenproject/cedarling_wasm";
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+
+export type CedarlingConfig = Record<string, string | number | boolean>;
+
+export type CedarlingAuthorizeResult = {
+  json_string: () => string;
+};
+
+export type CedarlingInstance = {
+  authorize_unsigned: (request: unknown) => Promise<CedarlingAuthorizeResult>;
+  pop_logs: () => unknown[];
+};
+
+const require = createRequire(import.meta.url);
+let cedarlingPromise: Promise<CedarlingInstance> | null = null;
+let wasmInitPromise: Promise<void> | null = null;
+
+export async function getCedarling(config: CedarlingConfig): Promise<CedarlingInstance> {
+  if (!cedarlingPromise) {
+    cedarlingPromise = createCedarling(config);
+  }
+  return cedarlingPromise;
+}
+
+export function resetCedarlingInstance(): void {
+  cedarlingPromise = null;
+}
+
+async function ensureWasmInitialized(): Promise<void> {
+  if (!wasmInitPromise) {
+    wasmInitPromise = (async () => {
+      const wasmPath = require.resolve("@janssenproject/cedarling_wasm/cedarling_wasm_bg.wasm");
+      const wasmBytes = await readFile(wasmPath);
+      await initWasm(wasmBytes);
+    })();
+  }
+  return wasmInitPromise;
+}
+
+async function createCedarling(config: CedarlingConfig): Promise<CedarlingInstance> {
+  await ensureWasmInitialized();
+  const instance = await init(config);
+  return instance as CedarlingInstance;
+}

package/src/config.ts

@@ -0,0 +1,249 @@
+import type { OpenClawPluginConfigSchema } from "openclaw/plugin-sdk";
+import type { ClawClampConfig, ClawClampMode, RiskLevel } from "./types.js";
+
+const DEFAULT_RISK_OVERRIDES: Record<string, RiskLevel> = {
+  read: "low",
+  memory_get: "low",
+  memory_search: "low",
+  sessions_list: "low",
+  sessions_history: "low",
+  session_status: "low",
+  agents_list: "low",
+  web_search: "medium",
+  web_fetch: "medium",
+  image: "medium",
+  tts: "medium",
+  canvas: "medium",
+  browser: "high",
+  write: "high",
+  edit: "high",
+  apply_patch: "high",
+  exec: "high",
+  process: "high",
+  message: "high",
+  cron: "high",
+  gateway: "high",
+  nodes: "high",
+  sessions_send: "high",
+  sessions_spawn: "high",
+  subagents: "high",
+};
+
+export const DEFAULT_CLAWCLAMP_CONFIG: ClawClampConfig = {
+  enabled: true,
+  mode: "gray",
+  principalId: "openclaw",
+  policyFailOpen: false,
+  risk: {
+    default: "high",
+    overrides: DEFAULT_RISK_OVERRIDES,
+  },
+  grants: {
+    defaultTtlSeconds: 900,
+    maxTtlSeconds: 3600,
+  },
+  audit: {
+    maxEntries: 500,
+    includeParams: true,
+    maxParamLength: 2048,
+  },
+};
+
+const RISK_LEVELS = ["low", "medium", "high"] as const;
+
+const CEDAR_GUARD_CONFIG_JSON_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    enabled: { type: "boolean", default: DEFAULT_CLAWCLAMP_CONFIG.enabled },
+    mode: {
+      type: "string",
+      enum: ["enforce", "gray"],
+      default: DEFAULT_CLAWCLAMP_CONFIG.mode,
+    },
+    principalId: { type: "string", default: DEFAULT_CLAWCLAMP_CONFIG.principalId },
+    policyStoreUri: { type: "string" },
+    policyStoreLocal: { type: "string" },
+    uiToken: { type: "string" },
+    policyFailOpen: { type: "boolean", default: DEFAULT_CLAWCLAMP_CONFIG.policyFailOpen },
+    risk: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        default: {
+          type: "string",
+          enum: [...RISK_LEVELS],
+          default: DEFAULT_CLAWCLAMP_CONFIG.risk.default,
+        },
+        overrides: {
+          type: "object",
+          additionalProperties: {
+            type: "string",
+            enum: [...RISK_LEVELS],
+          },
+          default: DEFAULT_CLAWCLAMP_CONFIG.risk.overrides,
+        },
+      },
+    },
+    grants: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        defaultTtlSeconds: {
+          type: "number",
+          minimum: 60,
+          maximum: 86_400,
+          default: DEFAULT_CLAWCLAMP_CONFIG.grants.defaultTtlSeconds,
+        },
+        maxTtlSeconds: {
+          type: "number",
+          minimum: 60,
+          maximum: 86_400,
+          default: DEFAULT_CLAWCLAMP_CONFIG.grants.maxTtlSeconds,
+        },
+      },
+    },
+    audit: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        maxEntries: {
+          type: "number",
+          minimum: 50,
+          maximum: 10_000,
+          default: DEFAULT_CLAWCLAMP_CONFIG.audit.maxEntries,
+        },
+        includeParams: {
+          type: "boolean",
+          default: DEFAULT_CLAWCLAMP_CONFIG.audit.includeParams,
+        },
+        maxParamLength: {
+          type: "number",
+          minimum: 256,
+          maximum: 32_000,
+          default: DEFAULT_CLAWCLAMP_CONFIG.audit.maxParamLength,
+        },
+      },
+    },
+  },
+} as const;
+
+export const clawClampConfigSchema: OpenClawPluginConfigSchema = {
+  safeParse(value: unknown) {
+    if (value === undefined) {
+      return { success: true, data: undefined };
+    }
+    try {
+      return { success: true, data: resolveClawClampConfig(value) };
+    } catch (error) {
+      return {
+        success: false,
+        error: {
+          issues: [{ path: [], message: error instanceof Error ? error.message : String(error) }],
+        },
+      };
+    }
+  },
+  jsonSchema: CEDAR_GUARD_CONFIG_JSON_SCHEMA,
+};
+
+function isRiskLevel(value: unknown): value is RiskLevel {
+  return typeof value === "string" && (RISK_LEVELS as readonly string[]).includes(value);
+}
+
+function isMode(value: unknown): value is ClawClampMode {
+  return value === "enforce" || value === "gray";
+}
+
+export function resolveClawClampConfig(input: unknown): ClawClampConfig {
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    return { ...DEFAULT_CLAWCLAMP_CONFIG };
+  }
+
+  const raw = input as Record<string, unknown>;
+  const riskOverrides = { ...DEFAULT_CLAWCLAMP_CONFIG.risk.overrides };
+
+  if (raw.risk && typeof raw.risk === "object" && !Array.isArray(raw.risk)) {
+    const risk = raw.risk as Record<string, unknown>;
+    if (risk.overrides && typeof risk.overrides === "object" && !Array.isArray(risk.overrides)) {
+      for (const [tool, level] of Object.entries(risk.overrides)) {
+        if (isRiskLevel(level)) {
+          riskOverrides[tool] = level;
+        }
+      }
+    }
+  }
+
+  const resolved: ClawClampConfig = {
+    enabled: typeof raw.enabled === "boolean" ? raw.enabled : DEFAULT_CLAWCLAMP_CONFIG.enabled,
+    mode: isMode(raw.mode) ? raw.mode : DEFAULT_CLAWCLAMP_CONFIG.mode,
+    principalId:
+      typeof raw.principalId === "string" && raw.principalId.trim()
+        ? raw.principalId.trim()
+        : DEFAULT_CLAWCLAMP_CONFIG.principalId,
+    policyStoreUri:
+      typeof raw.policyStoreUri === "string" && raw.policyStoreUri.trim()
+        ? raw.policyStoreUri.trim()
+        : undefined,
+    policyStoreLocal:
+      typeof raw.policyStoreLocal === "string" && raw.policyStoreLocal.trim()
+        ? raw.policyStoreLocal.trim()
+        : undefined,
+    uiToken:
+      typeof raw.uiToken === "string" && raw.uiToken.trim()
+        ? raw.uiToken.trim()
+        : undefined,
+    policyFailOpen:
+      typeof raw.policyFailOpen === "boolean"
+        ? raw.policyFailOpen
+        : DEFAULT_CLAWCLAMP_CONFIG.policyFailOpen,
+    risk: {
+      default:
+        raw.risk && typeof raw.risk === "object" && !Array.isArray(raw.risk)
+          ? isRiskLevel((raw.risk as Record<string, unknown>).default)
+            ? ((raw.risk as Record<string, unknown>).default as RiskLevel)
+            : DEFAULT_CLAWCLAMP_CONFIG.risk.default
+          : DEFAULT_CLAWCLAMP_CONFIG.risk.default,
+      overrides: riskOverrides,
+    },
+    grants: {
+      defaultTtlSeconds:
+        raw.grants && typeof raw.grants === "object" && !Array.isArray(raw.grants)
+          ? Number((raw.grants as Record<string, unknown>).defaultTtlSeconds) ||
+            DEFAULT_CLAWCLAMP_CONFIG.grants.defaultTtlSeconds
+          : DEFAULT_CLAWCLAMP_CONFIG.grants.defaultTtlSeconds,
+      maxTtlSeconds:
+        raw.grants && typeof raw.grants === "object" && !Array.isArray(raw.grants)
+          ? Number((raw.grants as Record<string, unknown>).maxTtlSeconds) ||
+            DEFAULT_CLAWCLAMP_CONFIG.grants.maxTtlSeconds
+          : DEFAULT_CLAWCLAMP_CONFIG.grants.maxTtlSeconds,
+    },
+    audit: {
+      maxEntries:
+        raw.audit && typeof raw.audit === "object" && !Array.isArray(raw.audit)
+          ? Number((raw.audit as Record<string, unknown>).maxEntries) ||
+            DEFAULT_CLAWCLAMP_CONFIG.audit.maxEntries
+          : DEFAULT_CLAWCLAMP_CONFIG.audit.maxEntries,
+      includeParams:
+        raw.audit && typeof raw.audit === "object" && !Array.isArray(raw.audit)
+          ? (raw.audit as Record<string, unknown>).includeParams === true
+          : DEFAULT_CLAWCLAMP_CONFIG.audit.includeParams,
+      maxParamLength:
+        raw.audit && typeof raw.audit === "object" && !Array.isArray(raw.audit)
+          ? Number((raw.audit as Record<string, unknown>).maxParamLength) ||
+            DEFAULT_CLAWCLAMP_CONFIG.audit.maxParamLength
+          : DEFAULT_CLAWCLAMP_CONFIG.audit.maxParamLength,
+    },
+  };
+
+  resolved.grants.defaultTtlSeconds = Math.min(
+    Math.max(60, resolved.grants.defaultTtlSeconds),
+    resolved.grants.maxTtlSeconds,
+  );
+  resolved.grants.maxTtlSeconds = Math.max(60, resolved.grants.maxTtlSeconds);
+
+  resolved.audit.maxEntries = Math.max(50, resolved.audit.maxEntries);
+  resolved.audit.maxParamLength = Math.max(256, resolved.audit.maxParamLength);
+
+  return resolved;
+}

package/src/grants.ts

@@ -0,0 +1,183 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { readJsonFileWithFallback, writeJsonFileAtomically } from "openclaw/plugin-sdk";
+import type { ClawClampConfig, GrantRecord } from "./types.js";
+import { withStateFileLock } from "./storage.js";
+import { buildDefaultPolicyStore } from "./policy.js";
+
+const POLICY_FILE = "policy-store.json";
+const POLICY_STORE_ID = "clawclamp";
+const GRANT_POLICY_PREFIX = "grant:";
+
+type PolicyRecord = {
+  cedar_version?: string;
+  name?: string;
+  description?: string;
+  policy_content: string;
+};
+
+type PolicyStoreBody = {
+  name?: string;
+  description?: string;
+  schema?: unknown;
+  trusted_issuers?: Record<string, unknown>;
+  policies?: Record<string, PolicyRecord>;
+};
+
+type PolicyStoreSnapshot = {
+  cedar_version: string;
+  policy_stores: Record<string, PolicyStoreBody>;
+};
+
+function resolvePolicyPath(stateDir: string): string {
+  return path.join(stateDir, "clawclamp", POLICY_FILE);
+}
+
+function encodeBase64(value: string): string {
+  return Buffer.from(value, "utf8").toString("base64");
+}
+
+function decodeBase64(value: string): string {
+  return Buffer.from(value, "base64").toString("utf8");
+}
+
+async function readPolicyStore(stateDir: string): Promise<PolicyStoreSnapshot> {
+  const filePath = resolvePolicyPath(stateDir);
+  const { value } = await readJsonFileWithFallback<PolicyStoreSnapshot>(
+    filePath,
+    buildDefaultPolicyStore() as PolicyStoreSnapshot,
+  );
+  return value;
+}
+
+async function writePolicyStore(stateDir: string, store: PolicyStoreSnapshot): Promise<void> {
+  const filePath = resolvePolicyPath(stateDir);
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await writeJsonFileAtomically(filePath, store);
+}
+
+function getWritableStore(store: PolicyStoreSnapshot): PolicyStoreBody {
+  const current = store.policy_stores?.[POLICY_STORE_ID];
+  if (!current) {
+    throw new Error("clawclamp policy store not found");
+  }
+  current.policies ??= {};
+  return current;
+}
+
+function grantPolicyId(createdAtMs: number): string {
+  return `${GRANT_POLICY_PREFIX}${createdAtMs}:${randomUUID()}`;
+}
+
+function buildGrantPolicy(toolName: string, expiresAtMs: number): string {
+  const toolClause =
+    toolName === "*" ? "true" : `resource.name == ${JSON.stringify(toolName)}`;
+  return `permit(principal, action, resource)
+when {
+  action == Action::"Invoke" &&
+  context.now < ${expiresAtMs} &&
+  ${toolClause}
+};`;
+}
+
+function parseGrantPolicy(id: string, record: PolicyRecord): GrantRecord | null {
+  if (!id.startsWith(GRANT_POLICY_PREFIX)) {
+    return null;
+  }
+  const content = decodeBase64(record.policy_content ?? "");
+  const createdAtMatch = /^grant:(\d+):/.exec(id);
+  const expiresAtMatch = /context\.now\s*<\s*(\d+)/.exec(content);
+  const toolMatch = /resource\.name\s*==\s*"([^"]+)"/.exec(content);
+  const createdAtMs = createdAtMatch ? Number(createdAtMatch[1]) : Date.now();
+  const expiresAtMs = expiresAtMatch ? Number(expiresAtMatch[1]) : 0;
+  if (!Number.isFinite(expiresAtMs) || expiresAtMs <= 0) {
+    return null;
+  }
+  return {
+    id,
+    toolName: toolMatch?.[1] ?? "*",
+    createdAt: new Date(createdAtMs).toISOString(),
+    expiresAt: new Date(expiresAtMs).toISOString(),
+    note: record.description?.trim() || undefined,
+  };
+}
+
+function sortNewestFirst(left: GrantRecord, right: GrantRecord): number {
+  return Date.parse(right.createdAt) - Date.parse(left.createdAt);
+}
+
+function pruneExpiredPolicies(policies: Record<string, PolicyRecord>, nowMs: number): boolean {
+  let changed = false;
+  for (const [id, record] of Object.entries(policies)) {
+    const grant = parseGrantPolicy(id, record);
+    if (grant && Date.parse(grant.expiresAt) <= nowMs) {
+      delete policies[id];
+      changed = true;
+    }
+  }
+  return changed;
+}
+
+export async function listGrants(stateDir: string): Promise<GrantRecord[]> {
+  return withStateFileLock(stateDir, "policy-store", async () => {
+    const store = await readPolicyStore(stateDir);
+    const policyStore = getWritableStore(store);
+    const nowMs = Date.now();
+    const changed = pruneExpiredPolicies(policyStore.policies ?? {}, nowMs);
+    if (changed) {
+      await writePolicyStore(stateDir, store);
+    }
+    return Object.entries(policyStore.policies ?? {})
+      .map(([id, record]) => parseGrantPolicy(id, record))
+      .filter((grant): grant is GrantRecord => Boolean(grant))
+      .sort(sortNewestFirst);
+  });
+}
+
+export async function createGrant(params: {
+  stateDir: string;
+  config: ClawClampConfig;
+  toolName: string;
+  ttlSeconds?: number;
+  note?: string;
+}): Promise<GrantRecord> {
+  return withStateFileLock(params.stateDir, "policy-store", async () => {
+    const store = await readPolicyStore(params.stateDir);
+    const policyStore = getWritableStore(store);
+    const nowMs = Date.now();
+    const ttlSeconds = Math.min(
+      Math.max(60, params.ttlSeconds ?? params.config.grants.defaultTtlSeconds),
+      params.config.grants.maxTtlSeconds,
+    );
+    const expiresAtMs = nowMs + ttlSeconds * 1000;
+    const id = grantPolicyId(nowMs);
+    policyStore.policies![id] = {
+      cedar_version: store.cedar_version,
+      name: `Grant ${params.toolName}`,
+      description: params.note?.trim() || undefined,
+      policy_content: encodeBase64(buildGrantPolicy(params.toolName, expiresAtMs)),
+    };
+    await writePolicyStore(params.stateDir, store);
+    return {
+      id,
+      toolName: params.toolName,
+      createdAt: new Date(nowMs).toISOString(),
+      expiresAt: new Date(expiresAtMs).toISOString(),
+      note: params.note?.trim() || undefined,
+    };
+  });
+}
+
+export async function revokeGrant(stateDir: string, grantId: string): Promise<boolean> {
+  return withStateFileLock(stateDir, "policy-store", async () => {
+    const store = await readPolicyStore(stateDir);
+    const policyStore = getWritableStore(store);
+    if (!policyStore.policies?.[grantId]) {
+      return false;
+    }
+    delete policyStore.policies[grantId];
+    await writePolicyStore(stateDir, store);
+    return true;
+  });
+}

package/src/guard.test.ts

@@ -0,0 +1,69 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { DEFAULT_CLAWCLAMP_CONFIG } from "./config.js";
+import { createClawClampService } from "./guard.js";
+import { readAuditEntries } from "./audit.js";
+
+const getCedarlingMock = vi.fn();
+
+vi.mock("./cedarling.js", () => ({
+  getCedarling: getCedarlingMock,
+}));
+
+describe("ClawclampService", () => {
+  let stateDir: string;
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    stateDir = await fs.mkdtemp(path.join(os.tmpdir(), "clawclamp-"));
+  });
+
+  afterEach(async () => {
+    await fs.rm(stateDir, { recursive: true, force: true });
+  });
+
+  it("blocks tool execution when Cedar initialization fails and policyFailOpen is false", async () => {
+    getCedarlingMock.mockRejectedValue(new Error("fetch failed"));
+
+    const logger = { error: vi.fn(), warn: vi.fn(), info: vi.fn(), debug: vi.fn() };
+    const service = createClawClampService({
+      api: { logger } as any,
+      config: {
+        ...DEFAULT_CLAWCLAMP_CONFIG,
+        mode: "enforce",
+        policyFailOpen: false,
+      },
+      stateDir,
+    });
+
+    const result = await service.handleBeforeToolCall(
+      {
+        toolName: "browser",
+        params: { action: "open", url: "https://example.com" },
+        toolCallId: "call-1",
+        runId: "run-1",
+      },
+      {
+        sessionId: "session-1",
+        sessionKey: "agent:main:main",
+        agentId: "main",
+      } as any,
+    );
+
+    expect(result).toEqual({ block: true, blockReason: "fetch failed" });
+    expect(logger.error).toHaveBeenCalledWith(
+      "Clawclamp authorization failed for browser: fetch failed",
+    );
+
+    const auditEntries = await readAuditEntries(stateDir, 10);
+    expect(auditEntries).toHaveLength(1);
+    expect(auditEntries[0]).toMatchObject({
+      toolName: "browser",
+      cedarDecision: "error",
+      decision: "error",
+      reason: "fetch failed",
+    });
+  });
+});