securityclaw 0.0.1

package/src/config/validator.ts

@@ -0,0 +1,222 @@
+import type {
+  ApprovalRequirements,
+  ChallengeConfig,
+  Decision,
+  HookControls,
+  HookName,
+  PolicyMatch,
+  PolicyRule,
+  SecurityClawConfig,
+  Severity,
+} from "../types.ts";
+import { normalizeFileRules } from "../domain/services/file_rule_registry.ts";
+import { normalizeSensitivePathRules } from "../domain/services/sensitive_path_registry.ts";
+
+const DEFAULT_HOOKS: Record<HookName, HookControls> = {
+  before_prompt_build: { enabled: true, timeout_ms: 50, fail_mode: "open" },
+  before_tool_call: { enabled: true, timeout_ms: 50, fail_mode: "close" },
+  after_tool_call: { enabled: true, timeout_ms: 50, fail_mode: "open" },
+  tool_result_persist: { enabled: true, timeout_ms: 50, fail_mode: "close" },
+  message_sending: { enabled: true, timeout_ms: 50, fail_mode: "open" }
+};
+
+const DECISIONS: Decision[] = ["allow", "warn", "challenge", "block"];
+const DEFAULT_GROUP = "general";
+const DEFAULT_CONTROL_DOMAIN = "execution_control";
+const SEVERITIES: Severity[] = ["low", "medium", "high", "critical"];
+
+function normalizeString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function normalizeStringArray(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+  const normalized = value
+    .map((entry) => normalizeString(entry))
+    .filter((entry): entry is string => Boolean(entry));
+  return normalized.length > 0 ? normalized : undefined;
+}
+
+function normalizeNumber(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function normalizeSeverity(value: unknown): Severity | undefined {
+  return typeof value === "string" && SEVERITIES.includes(value as Severity)
+    ? (value as Severity)
+    : undefined;
+}
+
+function sanitizeDecision(value: unknown): Decision | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  return DECISIONS.includes(value as Decision) ? (value as Decision) : undefined;
+}
+
+function sanitizePolicyMatch(match: PolicyRule["match"]): PolicyMatch {
+  const normalized: PolicyMatch = {};
+  const identity = normalizeStringArray(match?.identity);
+  const scope = normalizeStringArray(match?.scope);
+  const tool = normalizeStringArray(match?.tool);
+  const toolGroup = normalizeStringArray(match?.tool_group);
+  const operation = normalizeStringArray(match?.operation);
+  const tags = normalizeStringArray(match?.tags);
+  const resourceScope = normalizeStringArray(match?.resource_scope) as PolicyMatch["resource_scope"] | undefined;
+  const pathPrefix = normalizeStringArray(match?.path_prefix);
+  const pathGlob = normalizeStringArray(match?.path_glob);
+  const pathRegex = normalizeStringArray(match?.path_regex);
+  const fileType = normalizeStringArray(match?.file_type);
+  const assetLabels = normalizeStringArray(match?.asset_labels);
+  const dataLabels = normalizeStringArray(match?.data_labels);
+  const trustLevel = normalizeStringArray(match?.trust_level) as PolicyMatch["trust_level"] | undefined;
+  const destinationType = normalizeStringArray(match?.destination_type) as PolicyMatch["destination_type"] | undefined;
+  const destDomain = normalizeStringArray(match?.dest_domain);
+  const destIpClass = normalizeStringArray(match?.dest_ip_class) as PolicyMatch["dest_ip_class"] | undefined;
+  const toolArgsSummary = normalizeStringArray(match?.tool_args_summary);
+  const toolArgsRegex = normalizeStringArray(match?.tool_args_regex);
+  const minFileCount = normalizeNumber(match?.min_file_count);
+  const minBytes = normalizeNumber(match?.min_bytes);
+  const minRecordCount = normalizeNumber(match?.min_record_count);
+
+  if (identity) normalized.identity = identity;
+  if (scope) normalized.scope = scope;
+  if (tool) normalized.tool = tool;
+  if (toolGroup) normalized.tool_group = toolGroup;
+  if (operation) normalized.operation = operation;
+  if (tags) normalized.tags = tags;
+  if (resourceScope) normalized.resource_scope = resourceScope;
+  if (pathPrefix) normalized.path_prefix = pathPrefix;
+  if (pathGlob) normalized.path_glob = pathGlob;
+  if (pathRegex) normalized.path_regex = pathRegex;
+  if (fileType) normalized.file_type = fileType;
+  if (assetLabels) normalized.asset_labels = assetLabels;
+  if (dataLabels) normalized.data_labels = dataLabels;
+  if (trustLevel) normalized.trust_level = trustLevel;
+  if (destinationType) normalized.destination_type = destinationType;
+  if (destDomain) normalized.dest_domain = destDomain;
+  if (destIpClass) normalized.dest_ip_class = destIpClass;
+  if (toolArgsSummary) normalized.tool_args_summary = toolArgsSummary;
+  if (toolArgsRegex) normalized.tool_args_regex = toolArgsRegex;
+  if (minFileCount !== undefined) normalized.min_file_count = minFileCount;
+  if (minBytes !== undefined) normalized.min_bytes = minBytes;
+  if (minRecordCount !== undefined) normalized.min_record_count = minRecordCount;
+
+  return normalized;
+}
+
+function sanitizeChallenge(value: PolicyRule["challenge"]): ChallengeConfig | undefined {
+  const ttlSeconds = normalizeNumber(value?.ttl_seconds);
+  return ttlSeconds !== undefined ? { ttl_seconds: ttlSeconds } : undefined;
+}
+
+function sanitizeApprovalRequirements(value: PolicyRule["approval_requirements"]): ApprovalRequirements | undefined {
+  if (!value || typeof value !== "object") {
+    return undefined;
+  }
+  const approverRoles = normalizeStringArray(value.approver_roles);
+  const ttlSeconds = normalizeNumber(value.ttl_seconds);
+  const traceBinding = value.trace_binding === "trace" ? "trace" : value.trace_binding === "none" ? "none" : undefined;
+  const normalized: ApprovalRequirements = {
+    ...(value.ticket_required === true ? { ticket_required: true } : {}),
+    ...(approverRoles ? { approver_roles: approverRoles } : {}),
+    ...(value.single_use === true ? { single_use: true } : {}),
+    ...(traceBinding ? { trace_binding: traceBinding } : {}),
+    ...(ttlSeconds !== undefined ? { ttl_seconds: ttlSeconds } : {}),
+  };
+  return Object.keys(normalized).length > 0 ? normalized : undefined;
+}
+
+function sanitizePolicyRule(rule: PolicyRule): PolicyRule {
+  const decision = sanitizeDecision(rule.decision);
+  if (!decision) {
+    throw new Error(`Policy ${rule.rule_id || "<unknown>"} must define a valid decision.`);
+  }
+  const controlDomain =
+    normalizeString(rule.control_domain) ??
+    normalizeString(rule.group) ??
+    DEFAULT_CONTROL_DOMAIN;
+  const title = normalizeString(rule.title);
+  const description = normalizeString(rule.description);
+  const severity = normalizeSeverity(rule.severity);
+  const owner = normalizeString(rule.owner);
+  const playbookUrl = normalizeString(rule.playbook_url);
+  const challenge = sanitizeChallenge(rule.challenge);
+  const approvalRequirements = sanitizeApprovalRequirements(rule.approval_requirements);
+  return {
+    ...rule,
+    group: normalizeString(rule.group) ?? controlDomain ?? DEFAULT_GROUP,
+    ...(title ? { title } : {}),
+    ...(description ? { description } : {}),
+    ...(severity ? { severity } : {}),
+    control_domain: controlDomain,
+    ...(owner ? { owner } : {}),
+    ...(playbookUrl ? { playbook_url: playbookUrl } : {}),
+    enabled: rule.enabled !== false,
+    decision,
+    reason_codes: Array.isArray(rule.reason_codes) ? rule.reason_codes : [],
+    match: sanitizePolicyMatch(rule.match ?? {}),
+    ...(challenge ? { challenge } : {}),
+    ...(approvalRequirements ? { approval_requirements: approvalRequirements } : {})
+  };
+}
+
+export function validateConfig(raw: Record<string, unknown>): SecurityClawConfig {
+  if (!raw || typeof raw !== "object") {
+    throw new Error("Config must be an object.");
+  }
+
+  const config = raw as Partial<SecurityClawConfig>;
+  if (!config.version || !config.policy_version || !config.environment) {
+    throw new Error("Config must define version, policy_version, and environment.");
+  }
+
+  const hooks = { ...DEFAULT_HOOKS, ...(config.hooks ?? {}) };
+
+  const policies = Array.isArray(config.policies) ? config.policies : [];
+  const normalizedPolicies: PolicyRule[] = [];
+  for (const rule of policies) {
+    if (!rule.rule_id || typeof rule.priority !== "number") {
+      throw new Error("Every policy must define rule_id and priority.");
+    }
+    normalizedPolicies.push(sanitizePolicyRule(rule));
+  }
+
+  const dlp = config.dlp;
+  if (!dlp || !Array.isArray(dlp.patterns) || !dlp.on_dlp_hit) {
+    throw new Error("DLP config must define patterns and on_dlp_hit.");
+  }
+  const webhookUrl = config.event_sink?.webhook_url;
+  const rawSensitivity =
+    raw.sensitivity && typeof raw.sensitivity === "object" && !Array.isArray(raw.sensitivity)
+      ? (raw.sensitivity as Record<string, unknown>)
+      : undefined;
+
+  return {
+    version: config.version,
+    policy_version: config.policy_version,
+    environment: config.environment,
+    defaults: {
+      approval_ttl_seconds: config.defaults?.approval_ttl_seconds ?? 900,
+      persist_mode: config.defaults?.persist_mode ?? "compat"
+    },
+    hooks,
+    policies: normalizedPolicies,
+    sensitivity: {
+      path_rules: normalizeSensitivePathRules(rawSensitivity?.path_rules, "builtin")
+    },
+    file_rules: normalizeFileRules(raw.file_rules),
+    dlp: {
+      on_dlp_hit: dlp.on_dlp_hit,
+      patterns: dlp.patterns
+    },
+    event_sink: {
+      timeout_ms: config.event_sink?.timeout_ms ?? 3000,
+      max_buffer: config.event_sink?.max_buffer ?? 100,
+      retry_limit: config.event_sink?.retry_limit ?? 3,
+      ...(webhookUrl !== undefined ? { webhook_url: webhookUrl } : {})
+    }
+  };
+}

package/src/domain/models/resource_context.ts

@@ -0,0 +1,31 @@
+import type { ResourceScope } from "../../types.ts";
+
+export interface ResourceContext {
+  resourceScope: ResourceScope;
+  resourcePaths: string[];
+}
+
+export interface ToolContext {
+  toolGroup?: string;
+  operation?: string;
+  resourceScope: ResourceScope;
+  resourcePaths: string[];
+  tags: string[];
+}
+
+export interface DestinationContext {
+  destinationType?: "internal" | "public" | "unknown" | "personal_storage" | "paste_service";
+  destDomain?: string;
+  destIpClass?: "loopback" | "private" | "public" | "unknown";
+}
+
+export interface LabelContext {
+  assetLabels: string[];
+  dataLabels: string[];
+}
+
+export interface VolumeContext {
+  fileCount?: number;
+  bytes?: number;
+  recordCount?: number;
+}

package/src/domain/ports/approval_repository.ts

@@ -0,0 +1,40 @@
+export interface StoredApprovalNotification {
+  channel: string;
+  to: string;
+  account_id?: string;
+  thread_id?: number;
+  message_id?: string;
+  sent_at?: string;
+}
+
+export interface StoredApprovalRecord {
+  approval_id: string;
+  request_key: string;
+  session_scope: string;
+  status: "pending" | "approved" | "rejected" | "expired";
+  requested_at: string;
+  expires_at: string;
+  policy_version: string;
+  actor_id: string;
+  scope: string;
+  tool_name: string;
+  resource_scope: string;
+  resource_paths: string[];
+  reason_codes: string[];
+  rule_ids: string[];
+  args_summary?: string;
+  approver?: string;
+  decided_at?: string;
+  notifications: StoredApprovalNotification[];
+}
+
+export interface ApprovalRepository {
+  create(record: Omit<StoredApprovalRecord, "notifications">): StoredApprovalRecord;
+  getById(approvalId: string): StoredApprovalRecord | undefined;
+  findApproved(sessionScope: string, requestKey: string): StoredApprovalRecord | undefined;
+  findPending(sessionScope: string, requestKey: string): StoredApprovalRecord | undefined;
+  resolve(approvalId: string, approver: string, decision: "approved" | "rejected", metadata?: { expires_at?: string }): StoredApprovalRecord | undefined;
+  updateNotifications(approvalId: string, notifications: StoredApprovalNotification[]): StoredApprovalRecord | undefined;
+  listPending(limit: number): StoredApprovalRecord[];
+  close(): void;
+}

package/src/domain/ports/notification_port.ts

@@ -0,0 +1,29 @@
+export type ApprovalChannel = "telegram" | "discord" | "slack" | "signal" | "imessage" | "whatsapp" | "line";
+
+export interface NotificationTarget {
+  channel: ApprovalChannel;
+  to: string;
+  accountId?: string;
+  threadId?: string | number;
+}
+
+export interface NotificationOptions {
+  buttons?: Array<Array<{
+    text: string;
+    callback_data: string;
+    style?: string;
+  }>>;
+}
+
+export interface NotificationResult {
+  channel: ApprovalChannel;
+  to: string;
+  accountId?: string;
+  threadId?: number;
+  messageId?: string;
+  sentAt: string;
+}
+
+export interface NotificationPort {
+  send(target: NotificationTarget, message: string, options?: NotificationOptions): Promise<NotificationResult>;
+}

package/src/domain/ports/openclaw_adapter.ts

@@ -0,0 +1,22 @@
+export interface OpenClawLogger {
+  info?: (message: string) => void;
+  warn?: (message: string) => void;
+  error?: (message: string) => void;
+}
+
+export interface OpenClawConfig {
+  [key: string]: unknown;
+}
+
+export interface OpenClawAdapter {
+  readonly logger: OpenClawLogger;
+  readonly config: OpenClawConfig;
+  
+  sendTelegram(to: string, text: string, opts?: Record<string, unknown>): Promise<{ messageId?: string }>;
+  sendDiscord(to: string, text: string, opts?: Record<string, unknown>): Promise<{ messageId?: string }>;
+  sendSlack(to: string, text: string, opts?: Record<string, unknown>): Promise<{ messageId?: string }>;
+  sendSignal(to: string, text: string, opts?: Record<string, unknown>): Promise<{ messageId?: string }>;
+  sendIMessage(to: string, text: string, opts?: Record<string, unknown>): Promise<{ messageId?: string }>;
+  sendWhatsApp(to: string, text: string, opts?: Record<string, unknown>): Promise<{ messageId?: string }>;
+  sendLine(to: string, text: string, opts?: Record<string, unknown>): Promise<{ messageId?: string }>;
+}

package/src/domain/services/account_policy_engine.ts

@@ -0,0 +1,163 @@
+import type { AccountPolicyMode, AccountPolicyRecord } from "../../types.ts";
+
+export type AccountDecisionOverride = {
+  decision: "allow";
+  decision_source: "account";
+  reason_codes: string[];
+  policy: AccountPolicyRecord;
+};
+
+function normalizeString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function normalizeMode(value: unknown): AccountPolicyMode {
+  return value === "default_allow" ? "default_allow" : "apply_rules";
+}
+
+function enforceSingleAdmin(policies: AccountPolicyRecord[]): AccountPolicyRecord[] {
+  let selectedAdminSubject: string | undefined;
+  for (const policy of policies) {
+    if (policy.is_admin) {
+      selectedAdminSubject = policy.subject;
+    }
+  }
+  if (!selectedAdminSubject) {
+    return policies;
+  }
+  return policies.map((policy) =>
+    policy.is_admin && policy.subject !== selectedAdminSubject
+      ? {
+          ...policy,
+          is_admin: false,
+        }
+      : policy,
+  );
+}
+
+function normalizePolicyEntry(value: unknown): AccountPolicyRecord | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return undefined;
+  }
+
+  const subject = normalizeString((value as { subject?: unknown }).subject);
+  if (!subject) {
+    return undefined;
+  }
+
+  const record: AccountPolicyRecord = {
+    subject,
+    mode: normalizeMode((value as { mode?: unknown }).mode),
+    is_admin: (value as { is_admin?: unknown }).is_admin === true,
+  };
+
+  const optionalFields = [
+    "label",
+    "session_key",
+    "session_id",
+    "agent_id",
+    "channel",
+    "chat_type",
+    "updated_at",
+  ] as const;
+
+  for (const field of optionalFields) {
+    const normalized = normalizeString((value as Record<string, unknown>)[field]);
+    if (normalized) {
+      record[field] = normalized;
+    }
+  }
+
+  return record;
+}
+
+export function sanitizeAccountPolicies(input: unknown): AccountPolicyRecord[] {
+  if (!Array.isArray(input)) {
+    return [];
+  }
+
+  const deduped = new Map<string, AccountPolicyRecord>();
+  for (const entry of input) {
+    const normalized = normalizePolicyEntry(entry);
+    if (!normalized) {
+      continue;
+    }
+    deduped.set(normalized.subject, normalized);
+  }
+  return enforceSingleAdmin(Array.from(deduped.values()));
+}
+
+export function canonicalizeAccountPolicies(input: unknown): AccountPolicyRecord[] {
+  return sanitizeAccountPolicies(input)
+    .map((policy) => {
+      const canonical: AccountPolicyRecord = {
+        subject: policy.subject,
+        mode: policy.mode,
+        is_admin: policy.is_admin,
+      };
+
+      const optionalFields = [
+        "label",
+        "session_key",
+        "session_id",
+        "agent_id",
+        "channel",
+        "chat_type",
+        "updated_at",
+      ] as const;
+
+      for (const field of optionalFields) {
+        if (policy[field]) {
+          canonical[field] = policy[field];
+        }
+      }
+
+      return canonical;
+    })
+    .sort((left, right) => left.subject.localeCompare(right.subject));
+}
+
+export class AccountPolicyEngine {
+  #policiesBySubject: Map<string, AccountPolicyRecord>;
+
+  constructor(policies: unknown) {
+    this.#policiesBySubject = new Map(
+      sanitizeAccountPolicies(policies).map((policy) => [policy.subject, policy]),
+    );
+  }
+
+  getPolicy(subject: string | undefined): AccountPolicyRecord | undefined {
+    if (!subject) {
+      return undefined;
+    }
+    return this.#policiesBySubject.get(subject);
+  }
+
+  listPolicies(): AccountPolicyRecord[] {
+    return Array.from(this.#policiesBySubject.values());
+  }
+
+  evaluate(subject: string | undefined): AccountDecisionOverride | undefined {
+    const policy = this.getPolicy(subject);
+    if (!policy) {
+      return undefined;
+    }
+    if (policy.mode === "default_allow") {
+      return {
+        decision: "allow",
+        decision_source: "account",
+        reason_codes: ["ACCOUNT_DEFAULT_ALLOW"],
+        policy
+      };
+    }
+    return undefined;
+  }
+
+  static sanitize(input: unknown): AccountPolicyRecord[] {
+    return sanitizeAccountPolicies(input);
+  }
+
+  static canonicalize(input: unknown): AccountPolicyRecord[] {
+    return canonicalizeAccountPolicies(input);
+  }
+}