securityclaw 0.0.1

package/install.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PACKAGE="${SECURITYCLAW_NPM_PACKAGE:-securityclaw}"
+VERSION="${SECURITYCLAW_VERSION:-latest}"
+
+if command -v npx >/dev/null 2>&1; then
+  if [[ "${VERSION}" == "latest" ]]; then
+    exec npx --yes "${PACKAGE}" install "$@"
+  fi
+  exec npx --yes "${PACKAGE}@${VERSION}" install "$@"
+fi
+
+if command -v npm >/dev/null 2>&1; then
+  if [[ "${VERSION}" == "latest" ]]; then
+    exec npm exec --yes --package "${PACKAGE}" securityclaw -- install "$@"
+  fi
+  exec npm exec --yes --package "${PACKAGE}@${VERSION}" securityclaw -- install "$@"
+fi
+
+echo "SecurityClaw installer requires npx or npm." >&2
+exit 1

package/openclaw.plugin.json

@@ -0,0 +1,60 @@
+{
+  "id": "securityclaw",
+  "name": "SecurityClaw Security",
+  "description": "Runtime policy enforcement, transcript sanitization, and audit events for OpenClaw.",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "configPath": {
+        "type": "string",
+        "description": "Path to the SecurityClaw YAML policy file, relative to the plugin root or absolute."
+      },
+      "overridePath": {
+        "type": "string",
+        "description": "Legacy JSON override file path for one-time migration into SQLite; no longer used for ongoing strategy persistence."
+      },
+      "dbPath": {
+        "type": "string",
+        "description": "Optional absolute SQLite override for internal use. Relative values are ignored; normal installs use extensions/securityclaw/data/securityclaw.db."
+      },
+      "webhookUrl": {
+        "type": "string",
+        "description": "Optional override for SecurityDecisionEvent webhook delivery."
+      },
+      "policyVersion": {
+        "type": "string"
+      },
+      "environment": {
+        "type": "string"
+      },
+      "approvalTtlSeconds": {
+        "type": "number",
+        "minimum": 1
+      },
+      "persistMode": {
+        "type": "string",
+        "enum": ["strict", "compat"]
+      },
+      "decisionLogMaxLength": {
+        "type": "number",
+        "minimum": 64,
+        "description": "Max serialized argument length included in SecurityClaw decision logs."
+      },
+      "statusPath": {
+        "type": "string",
+        "description": "Optional absolute status snapshot override for internal use. Relative values are ignored; normal installs use extensions/securityclaw/runtime/securityclaw-status.json."
+      },
+      "adminAutoStart": {
+        "type": "boolean",
+        "description": "Whether to auto-start SecurityClaw admin dashboard when plugin is loaded (default true)."
+      },
+      "adminPort": {
+        "type": "number",
+        "minimum": 1,
+        "maximum": 65535,
+        "description": "Optional admin dashboard listen port. Defaults to SECURITYCLAW_ADMIN_PORT or 4780."
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "securityclaw",
+  "version": "0.0.1",
+  "description": "SecurityClaw security plugin for OpenClaw-compatible hooks.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "securityclaw": "bin/securityclaw.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/znary/securityclaw.git"
+  },
+  "homepage": "https://github.com/znary/securityclaw#readme",
+  "bugs": {
+    "url": "https://github.com/znary/securityclaw/issues"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "files": [
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md",
+    "README.zh-CN.md",
+    "admin/public",
+    "admin/server.ts",
+    "bin",
+    "config/policy.default.yaml",
+    "index.ts",
+    "install.sh",
+    "openclaw.plugin.json",
+    "src"
+  ],
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test:unit": "node --test --experimental-strip-types",
+    "test": "npm run typecheck && npm run test:unit",
+    "check": "npm test",
+    "admin": "node --experimental-strip-types ./admin/server.ts",
+    "admin:build": "node ./scripts/build-admin.mjs",
+    "prepack": "npm test && npm run admin:build",
+    "pack:plugin": "node ./scripts/pack-plugin.mjs",
+    "openclaw:install": "node ./scripts/install-openclaw-plugin.mjs",
+    "release:check": "node ./scripts/release-preflight.mjs",
+    "release:dry-run": "npm run release:check && npm publish --dry-run --access public"
+  },
+  "dependencies": {
+    "esbuild": "^0.27.4",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "recharts": "^3.8.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "openclaw": "^2026.3.13",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "openclaw": "^2026.3.13"
+  }
+}

package/src/admin/build.ts

@@ -0,0 +1,113 @@
+import { build } from "esbuild";
+import { existsSync, mkdirSync, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+type AdminBuildLogger = {
+  info?: (message: string) => void;
+  warn?: (message: string) => void;
+};
+
+type AdminBuildPaths = {
+  sourceDir: string;
+  entryPoint: string;
+  outfile: string;
+};
+
+type AdminBuildResult = {
+  state: "built" | "skipped";
+  paths: AdminBuildPaths;
+};
+
+type AdminBuildOptions = {
+  force?: boolean;
+  logger?: AdminBuildLogger;
+  paths?: Partial<AdminBuildPaths>;
+};
+
+type GlobalWithSecurityClawAdminBuild = typeof globalThis & {
+  __securityclawAdminBuildPromise?: Promise<AdminBuildResult>;
+};
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+
+function resolvePaths(overrides: Partial<AdminBuildPaths> = {}): AdminBuildPaths {
+  return {
+    sourceDir: overrides.sourceDir ?? path.resolve(ROOT, "admin/src"),
+    entryPoint: overrides.entryPoint ?? path.resolve(ROOT, "admin/src/app.jsx"),
+    outfile: overrides.outfile ?? path.resolve(ROOT, "admin/public/app.js")
+  };
+}
+
+function newestMtimeMs(target: string): number | undefined {
+  if (!existsSync(target)) {
+    return undefined;
+  }
+  const stat = statSync(target);
+  if (!stat.isDirectory()) {
+    return stat.mtimeMs;
+  }
+
+  let newest = 0;
+  for (const entry of readdirSync(target, { withFileTypes: true })) {
+    const candidate = newestMtimeMs(path.join(target, entry.name));
+    if (candidate !== undefined && candidate > newest) {
+      newest = candidate;
+    }
+  }
+  return newest || stat.mtimeMs;
+}
+
+export function shouldBuildAdminAssets(options: Pick<AdminBuildOptions, "paths"> = {}): boolean {
+  const paths = resolvePaths(options.paths);
+  if (!existsSync(paths.outfile)) {
+    return true;
+  }
+  const sourceMtimeMs = newestMtimeMs(paths.sourceDir);
+  if (sourceMtimeMs === undefined) {
+    return false;
+  }
+  return sourceMtimeMs > statSync(paths.outfile).mtimeMs;
+}
+
+export async function ensureAdminAssetsBuilt(options: AdminBuildOptions = {}): Promise<AdminBuildResult> {
+  const paths = resolvePaths(options.paths);
+  if (!options.force && !shouldBuildAdminAssets({ paths })) {
+    return { state: "skipped", paths };
+  }
+  if (!existsSync(paths.entryPoint)) {
+    throw new Error(`SecurityClaw admin entry point not found: ${paths.entryPoint}`);
+  }
+
+  const state = globalThis as GlobalWithSecurityClawAdminBuild;
+  if (state.__securityclawAdminBuildPromise) {
+    return state.__securityclawAdminBuildPromise;
+  }
+
+  const logger = options.logger ?? {};
+  mkdirSync(path.dirname(paths.outfile), { recursive: true });
+
+  const promise = build({
+    entryPoints: [paths.entryPoint],
+    outfile: paths.outfile,
+    bundle: true,
+    format: "esm",
+    target: ["es2022"],
+    sourcemap: false,
+    minify: true,
+    define: {
+      "process.env.NODE_ENV": "\"production\""
+    }
+  }).then(() => {
+    logger.info?.(`SecurityClaw admin bundle rebuilt: ${paths.outfile}`);
+    return { state: "built" as const, paths };
+  }).catch((error) => {
+    logger.warn?.(`SecurityClaw admin bundle build failed (${String(error)})`);
+    throw error;
+  }).finally(() => {
+    delete state.__securityclawAdminBuildPromise;
+  });
+
+  state.__securityclawAdminBuildPromise = promise;
+  return promise;
+}

package/src/admin/console_notice.ts

@@ -0,0 +1,195 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+import { resolveSecurityClawStateDir } from "../infrastructure/config/plugin_config_parser.ts";
+import type { SecurityClawLocale } from "../i18n/locale.ts";
+import { pickLocalized } from "../i18n/locale.ts";
+
+export type AdminConsoleState = "started" | "already-running" | "service-command";
+
+export type AdminConsoleLogger = {
+  info?: (message: string) => void;
+  warn?: (message: string) => void;
+};
+
+export type BrowserOpenResult = {
+  ok: boolean;
+  command?: string;
+  error?: string;
+};
+
+export type BrowserOpener = (url: string) => BrowserOpenResult;
+
+export type AnnounceAdminConsoleOptions = {
+  locale: SecurityClawLocale;
+  logger: AdminConsoleLogger;
+  url: string;
+  state: AdminConsoleState;
+  stateDir?: string;
+  opener?: BrowserOpener;
+};
+
+export type AnnounceAdminConsoleResult = {
+  firstRun: boolean;
+  openedAutomatically: boolean;
+  markerPath?: string;
+};
+
+const MARKER_FILE_NAME = "admin-dashboard-opened-v1.json";
+const BANNER_BORDER = "=".repeat(72);
+const GATEWAY_COMMANDS_WITH_ADMIN_BANNER = new Set(["run", "start", "restart", "status"]);
+
+function emitLog(logger: AdminConsoleLogger, message: string): void {
+  logger.info?.(message);
+}
+
+function emitWarn(logger: AdminConsoleLogger, message: string): void {
+  logger.warn?.(message);
+}
+
+function localize(locale: SecurityClawLocale, zhText: string, enText: string): string {
+  return pickLocalized(locale, zhText, enText);
+}
+
+export function resolveAdminConsoleMarkerPath(stateDir: string): string {
+  return path.join(resolveSecurityClawStateDir(stateDir), MARKER_FILE_NAME);
+}
+
+export function buildAdminConsoleBanner(params: {
+  locale: SecurityClawLocale;
+  url: string;
+  state: AdminConsoleState;
+  openedAutomatically: boolean;
+}): string[] {
+  const { locale, url, state, openedAutomatically } = params;
+  const title =
+    state === "already-running"
+      ? localize(locale, "SecurityClaw 管理后台已在运行", "SecurityClaw admin dashboard is already running")
+      : state === "service-command"
+        ? localize(locale, "SecurityClaw 管理后台入口", "SecurityClaw admin dashboard entry")
+        : localize(locale, "SecurityClaw 管理后台已启动", "SecurityClaw admin dashboard is ready");
+  const openHint = openedAutomatically
+    ? localize(
+        locale,
+        "首次启动已自动在默认浏览器中打开。",
+        "Opened automatically in your default browser on first startup.",
+      )
+    : state === "service-command"
+      ? localize(
+          locale,
+          "后台由 OpenClaw gateway 服务托管；如未自动打开，请手动访问下面的链接。",
+          "The background OpenClaw gateway service hosts this dashboard; if your browser did not open automatically, open the URL below manually.",
+        )
+      : localize(
+          locale,
+          "如未自动打开，请手动访问下面的链接。",
+          "If your browser did not open automatically, open the URL below manually.",
+        );
+
+  return [BANNER_BORDER, title, `URL: ${url}`, openHint, BANNER_BORDER];
+}
+
+export function shouldAnnounceAdminConsoleForArgv(argv: readonly string[] = process.argv): boolean {
+  const gatewayIndex = argv.findIndex((value) => value === "gateway");
+  if (gatewayIndex < 0) {
+    return false;
+  }
+
+  for (const token of argv.slice(gatewayIndex + 1)) {
+    if (GATEWAY_COMMANDS_WITH_ADMIN_BANNER.has(token)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function writeAdminConsoleMarker(markerPath: string, url: string): void {
+  mkdirSync(path.dirname(markerPath), { recursive: true });
+  writeFileSync(
+    markerPath,
+    JSON.stringify(
+      {
+        opened_at: new Date().toISOString(),
+        url,
+      },
+      null,
+      2,
+    ),
+    "utf8",
+  );
+}
+
+export function openAdminConsoleInBrowser(url: string): BrowserOpenResult {
+  if (process.platform === "darwin") {
+    const result = spawnSync("open", [url], { stdio: "ignore", timeout: 5_000 });
+    if (result.error) {
+      return { ok: false, command: "open", error: String(result.error) };
+    }
+    if (result.status !== 0) {
+      return { ok: false, command: "open", error: `exit code ${result.status}` };
+    }
+    return { ok: true, command: "open" };
+  }
+
+  if (process.platform === "win32") {
+    const result = spawnSync("cmd", ["/c", "start", "", url], {
+      stdio: "ignore",
+      timeout: 5_000,
+      windowsHide: true,
+    });
+    if (result.error) {
+      return { ok: false, command: "cmd /c start", error: String(result.error) };
+    }
+    if (result.status !== 0) {
+      return { ok: false, command: "cmd /c start", error: `exit code ${result.status}` };
+    }
+    return { ok: true, command: "cmd /c start" };
+  }
+
+  if (process.platform === "linux") {
+    const result = spawnSync("xdg-open", [url], { stdio: "ignore", timeout: 5_000 });
+    if (result.error) {
+      return { ok: false, command: "xdg-open", error: String(result.error) };
+    }
+    if (result.status !== 0) {
+      return { ok: false, command: "xdg-open", error: `exit code ${result.status}` };
+    }
+    return { ok: true, command: "xdg-open" };
+  }
+
+  return {
+    ok: false,
+    error: `unsupported platform ${process.platform}`,
+  };
+}
+
+export function announceAdminConsole(options: AnnounceAdminConsoleOptions): AnnounceAdminConsoleResult {
+  const { locale, logger, url, state, stateDir, opener = openAdminConsoleInBrowser } = options;
+  const markerPath = stateDir ? resolveAdminConsoleMarkerPath(stateDir) : undefined;
+  const firstRun = markerPath !== undefined && !existsSync(markerPath);
+
+  let openedAutomatically = false;
+  if (firstRun) {
+    const result = opener(url);
+    if (result.ok) {
+      openedAutomatically = true;
+      if (markerPath) {
+        writeAdminConsoleMarker(markerPath, url);
+      }
+    } else {
+      const via = result.command ? ` via ${result.command}` : "";
+      emitWarn(logger, `securityclaw: failed to auto-open admin dashboard${via} (${result.error ?? "unknown error"})`);
+    }
+  }
+
+  for (const line of buildAdminConsoleBanner({ locale, url, state, openedAutomatically })) {
+    emitLog(logger, line);
+  }
+
+  return {
+    firstRun,
+    openedAutomatically,
+    ...(markerPath !== undefined ? { markerPath } : {}),
+  };
+}

package/src/admin/dashboard_url_state.ts

@@ -0,0 +1,80 @@
+export const ADMIN_TAB_IDS = ["overview", "events", "rules", "skills", "accounts"] as const;
+export const ADMIN_DECISION_FILTER_IDS = ["all", "allow", "warn", "challenge", "block"] as const;
+
+export type AdminTabId = (typeof ADMIN_TAB_IDS)[number];
+export type AdminDecisionFilterId = (typeof ADMIN_DECISION_FILTER_IDS)[number];
+
+export type AdminDashboardUrlState = {
+  tab: AdminTabId;
+  decisionFilter: AdminDecisionFilterId;
+  decisionPage: number;
+};
+
+const ADMIN_TAB_ID_SET = new Set<string>(ADMIN_TAB_IDS);
+const ADMIN_DECISION_FILTER_ID_SET = new Set<string>(ADMIN_DECISION_FILTER_IDS);
+
+function readPositivePage(value: string | null | undefined): number {
+  const page = Number.parseInt(String(value || ""), 10);
+  return Number.isFinite(page) && page > 0 ? page : 1;
+}
+
+export function normalizeAdminTabId(value: string | null | undefined): AdminTabId {
+  return ADMIN_TAB_ID_SET.has(String(value || "")) ? (value as AdminTabId) : "overview";
+}
+
+export function normalizeAdminDecisionFilterId(value: string | null | undefined): AdminDecisionFilterId {
+  return ADMIN_DECISION_FILTER_ID_SET.has(String(value || "")) ? (value as AdminDecisionFilterId) : "all";
+}
+
+export function matchesAdminDecisionFilter(
+  decision: string | null | undefined,
+  filter: AdminDecisionFilterId
+): boolean {
+  if (filter === "all") {
+    return true;
+  }
+  return decision === filter;
+}
+
+export function readAdminDashboardUrlState(input: {
+  search?: string;
+  hash?: string;
+} = {}): AdminDashboardUrlState {
+  const searchParams = new URLSearchParams(input.search || "");
+  const hashTab = (input.hash || "").replace(/^#/, "");
+  return {
+    tab: normalizeAdminTabId(searchParams.get("tab") || hashTab),
+    decisionFilter: normalizeAdminDecisionFilterId(searchParams.get("decision")),
+    decisionPage: readPositivePage(searchParams.get("page"))
+  };
+}
+
+export function buildAdminDashboardSearch(input: {
+  currentSearch?: string;
+  tab: AdminTabId;
+  decisionFilter: AdminDecisionFilterId;
+  decisionPage: number;
+}): string {
+  const searchParams = new URLSearchParams(input.currentSearch || "");
+
+  if (input.tab === "overview") {
+    searchParams.delete("tab");
+  } else {
+    searchParams.set("tab", input.tab);
+  }
+
+  if (input.decisionFilter === "all") {
+    searchParams.delete("decision");
+  } else {
+    searchParams.set("decision", input.decisionFilter);
+  }
+
+  if (input.tab !== "events" || input.decisionPage <= 1) {
+    searchParams.delete("page");
+  } else {
+    searchParams.set("page", String(input.decisionPage));
+  }
+
+  const serialized = searchParams.toString();
+  return serialized ? `?${serialized}` : "";
+}

package/src/admin/openclaw_session_catalog.ts

@@ -0,0 +1,137 @@
+import os from "node:os";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+import { ApprovalSubjectResolver } from "../domain/services/approval_subject_resolver.ts";
+
+type JsonRecord = Record<string, unknown>;
+
+type RawSessionMetadata = {
+  sessionId?: unknown;
+  updatedAt?: unknown;
+  chatType?: unknown;
+  lastChannel?: unknown;
+  deliveryContext?: {
+    channel?: unknown;
+  };
+  origin?: {
+    provider?: unknown;
+    surface?: unknown;
+    chatType?: unknown;
+  };
+  sessionFile?: unknown;
+};
+
+export type OpenClawChatSession = {
+  subject: string;
+  label: string;
+  session_key: string;
+  session_id?: string;
+  agent_id?: string;
+  channel?: string;
+  provider?: string;
+  chat_type?: string;
+  updated_at?: string;
+  session_file?: string;
+};
+
+function normalizeString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function normalizeTimestamp(value: unknown): string | undefined {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return new Date(value).toISOString();
+  }
+  if (typeof value === "string" && value.trim()) {
+    const parsed = Date.parse(value);
+    if (Number.isFinite(parsed)) {
+      return new Date(parsed).toISOString();
+    }
+  }
+  return undefined;
+}
+
+function readSessionFile(filePath: string): JsonRecord {
+  const raw = JSON.parse(readFileSync(filePath, "utf8")) as unknown;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    return {};
+  }
+  return raw as JsonRecord;
+}
+
+export function listOpenClawChatSessions(openClawHome = path.join(os.homedir(), ".openclaw")): OpenClawChatSession[] {
+  const agentsDir = path.join(openClawHome, "agents");
+  if (!existsSync(agentsDir)) {
+    return [];
+  }
+
+  const deduped = new Map<string, OpenClawChatSession>();
+  for (const agentEntry of readdirSync(agentsDir, { withFileTypes: true })) {
+    if (!agentEntry.isDirectory()) {
+      continue;
+    }
+
+    const agentId = agentEntry.name;
+    const sessionsPath = path.join(agentsDir, agentId, "sessions", "sessions.json");
+    if (!existsSync(sessionsPath)) {
+      continue;
+    }
+
+    const rawSessions = readSessionFile(sessionsPath);
+    for (const [sessionKey, rawMetadata] of Object.entries(rawSessions)) {
+      if (!rawMetadata || typeof rawMetadata !== "object" || Array.isArray(rawMetadata)) {
+        continue;
+      }
+
+      const metadata = rawMetadata as RawSessionMetadata;
+      const sessionId = normalizeString(metadata.sessionId);
+      const channel =
+        normalizeString(metadata.deliveryContext?.channel) ??
+        normalizeString(metadata.lastChannel);
+      const provider =
+        normalizeString(metadata.origin?.provider) ??
+        normalizeString(metadata.origin?.surface);
+      const chatType =
+        normalizeString(metadata.chatType) ??
+        normalizeString(metadata.origin?.chatType);
+      const updatedAt = normalizeTimestamp(metadata.updatedAt);
+      const sessionFile = normalizeString(metadata.sessionFile);
+      const subject = ApprovalSubjectResolver.resolve({
+        agentId,
+        sessionKey,
+        ...(sessionId ? { sessionId } : {}),
+        ...(channel ? { channelId: channel } : {})
+      });
+
+      const entry: OpenClawChatSession = {
+        subject,
+        label: subject,
+        session_key: sessionKey,
+        ...(sessionId ? { session_id: sessionId } : {}),
+        ...(channel ? { channel } : {}),
+        ...(provider ? { provider } : {}),
+        ...(chatType ? { chat_type: chatType } : {}),
+        ...(updatedAt ? { updated_at: updatedAt } : {}),
+        ...(sessionFile ? { session_file: sessionFile } : {}),
+        agent_id: agentId
+      };
+
+      const previous = deduped.get(subject);
+      const previousTs = previous?.updated_at ? Date.parse(previous.updated_at) : Number.NEGATIVE_INFINITY;
+      const nextTs = entry.updated_at ? Date.parse(entry.updated_at) : Number.NEGATIVE_INFINITY;
+      if (!previous || nextTs >= previousTs) {
+        deduped.set(subject, entry);
+      }
+    }
+  }
+
+  return Array.from(deduped.values()).sort((left, right) => {
+    const rightTs = right.updated_at ? Date.parse(right.updated_at) : Number.NEGATIVE_INFINITY;
+    const leftTs = left.updated_at ? Date.parse(left.updated_at) : Number.NEGATIVE_INFINITY;
+    if (rightTs !== leftTs) {
+      return rightTs - leftTs;
+    }
+    return left.subject.localeCompare(right.subject);
+  });
+}