securityclaw 0.0.1

package/src/hooks/policy_guard.ts

@@ -0,0 +1,222 @@
+import type {
+  ApprovalRecord,
+  BeforeToolCallInput,
+  DecisionContext,
+  FileRule,
+  GuardComputation,
+  SecurityContext,
+  SensitivePathRule,
+} from "../types.ts";
+import type { ApprovalFsm } from "../engine/approval_fsm.ts";
+import type { DecisionEngine } from "../engine/decision_engine.ts";
+import type { RuleEngine } from "../engine/rule_engine.ts";
+import { defaultFileRuleReasonCode, matchFileRule } from "../domain/services/file_rule_registry.ts";
+import { inferSensitivityLabels } from "../domain/services/sensitivity_label_inference.ts";
+
+function buildSecurityContext(
+  input: BeforeToolCallInput,
+  policyVersion: string,
+  traceId: string,
+  nowIso: string,
+): SecurityContext {
+  return {
+    trace_id: input.security_context?.trace_id ?? traceId,
+    actor_id: input.actor_id,
+    workspace: input.workspace,
+    policy_version: input.security_context?.policy_version ?? policyVersion,
+    untrusted: input.security_context?.untrusted ?? false,
+    tags: [...(input.security_context?.tags ?? input.tags ?? [])],
+    created_at: input.security_context?.created_at ?? nowIso
+  };
+}
+
+function invalidApprovalResult(
+  mutatedPayload: BeforeToolCallInput,
+  securityContext: SecurityContext,
+  approval: ApprovalRecord,
+  reasonCodes: string[],
+): GuardComputation<BeforeToolCallInput> {
+  return {
+    mutated_payload: mutatedPayload,
+    decision: "block",
+    decision_source: "approval",
+    reason_codes: reasonCodes,
+    sanitization_actions: [],
+    security_context: securityContext,
+    approval,
+  };
+}
+
+function validateApprovedReplay(approval: ApprovalRecord, context: DecisionContext): string[] {
+  const reasons: string[] = [];
+  if (approval.request_context.actor_id !== context.actor_id) {
+    reasons.push("APPROVAL_ACTOR_MISMATCH");
+  }
+  if (approval.request_context.scope !== context.scope) {
+    reasons.push("APPROVAL_SCOPE_MISMATCH");
+  }
+  if (
+    approval.request_context.tool_name !== undefined &&
+    context.tool_name !== undefined &&
+    approval.request_context.tool_name !== context.tool_name
+  ) {
+    reasons.push("APPROVAL_TOOL_MISMATCH");
+  }
+  if (approval.request_context.resource_scope !== context.resource_scope) {
+    reasons.push("APPROVAL_RESOURCE_SCOPE_MISMATCH");
+  }
+
+  const requirements = approval.approval_requirements;
+  if (requirements?.trace_binding === "trace" && approval.request_context.trace_id !== context.security_context.trace_id) {
+    reasons.push("APPROVAL_TRACE_SCOPE_MISMATCH");
+  }
+  if (requirements?.ticket_required === true && !approval.ticket_id) {
+    reasons.push("APPROVAL_TICKET_REQUIRED");
+  }
+  if (
+    requirements?.approver_roles?.length &&
+    (!approval.approver_role || !requirements.approver_roles.includes(approval.approver_role))
+  ) {
+    reasons.push("APPROVAL_ROLE_MISMATCH");
+  }
+  if (requirements?.single_use === true && approval.used_at) {
+    reasons.push("APPROVAL_ALREADY_USED");
+  }
+
+  return reasons;
+}
+
+export function runPolicyGuard(
+  input: BeforeToolCallInput,
+  policyVersion: string,
+  traceId: string,
+  nowIso: string,
+  ruleEngine: RuleEngine,
+  decisionEngine: DecisionEngine,
+  approvals: ApprovalFsm,
+  sensitivePathRules: SensitivePathRule[] = [],
+  fileRules: FileRule[] = [],
+): GuardComputation<BeforeToolCallInput> {
+  const securityContext = buildSecurityContext(input, policyVersion, traceId, nowIso);
+  const inferredLabels = inferSensitivityLabels(
+    input.tool_group,
+    input.resource_paths ?? [],
+    input.tool_args_summary,
+    sensitivePathRules,
+  );
+  const assetLabels = [...new Set([...(input.asset_labels ?? []), ...inferredLabels.assetLabels])];
+  const dataLabels = [...new Set([...(input.data_labels ?? []), ...inferredLabels.dataLabels])];
+  const mutatedPayload = {
+    ...input,
+    asset_labels: assetLabels,
+    data_labels: dataLabels,
+    security_context: securityContext,
+  } as BeforeToolCallInput;
+  const context: DecisionContext = {
+    actor_id: input.actor_id,
+    scope: input.scope,
+    tool_name: input.tool_name,
+    ...(input.tool_group !== undefined ? { tool_group: input.tool_group } : {}),
+    ...(input.operation !== undefined ? { operation: input.operation } : {}),
+    tags: [...new Set([...(input.tags ?? []), ...securityContext.tags])],
+    resource_scope: input.resource_scope ?? "none",
+    resource_paths: [...(input.resource_paths ?? [])],
+    ...(input.file_type !== undefined ? { file_type: input.file_type } : {}),
+    asset_labels: assetLabels,
+    data_labels: dataLabels,
+    trust_level: input.trust_level ?? (securityContext.untrusted ? "untrusted" : "trusted"),
+    ...(input.destination_type !== undefined ? { destination_type: input.destination_type } : {}),
+    ...(input.dest_domain !== undefined ? { dest_domain: input.dest_domain } : {}),
+    ...(input.dest_ip_class !== undefined ? { dest_ip_class: input.dest_ip_class } : {}),
+    ...(input.tool_args_summary !== undefined ? { tool_args_summary: input.tool_args_summary } : {}),
+    volume: { ...(input.volume ?? {}) },
+    security_context: securityContext
+  };
+  const matchedFileRule = matchFileRule(context.resource_paths, fileRules);
+  const fileRuleReasonCodes = matchedFileRule
+    ? matchedFileRule.reason_codes?.length
+      ? [...matchedFileRule.reason_codes]
+      : [defaultFileRuleReasonCode(matchedFileRule.decision)]
+    : [];
+
+  if (matchedFileRule && matchedFileRule.decision !== "challenge") {
+    return {
+      mutated_payload: mutatedPayload,
+      decision: matchedFileRule.decision,
+      decision_source: "file_rule",
+      reason_codes: fileRuleReasonCodes,
+      sanitization_actions: [],
+      security_context: securityContext,
+    };
+  }
+
+  if (input.approval_id) {
+    const approval = approvals.getApprovalStatus(input.approval_id);
+    if (approval?.status === "approved") {
+      const replayViolations = validateApprovedReplay(approval, context);
+      if (replayViolations.length > 0) {
+        return invalidApprovalResult(mutatedPayload, securityContext, approval, replayViolations);
+      }
+      if (approval.approval_requirements?.single_use === true) {
+        approvals.markApprovalUsed(approval.approval_id);
+      }
+      const result: GuardComputation<BeforeToolCallInput> = {
+        mutated_payload: mutatedPayload,
+        decision: "allow",
+        decision_source: "approval",
+        reason_codes: ["APPROVAL_GRANTED"],
+        sanitization_actions: [],
+        security_context: securityContext
+      };
+      result.approval = approval;
+      return result;
+    }
+    if (approval && approval.status !== "pending") {
+      const result: GuardComputation<BeforeToolCallInput> = {
+        mutated_payload: mutatedPayload,
+        decision: "block",
+        decision_source: "approval",
+        reason_codes: [`APPROVAL_${approval.status.toUpperCase()}`],
+        sanitization_actions: [],
+        security_context: securityContext
+      };
+      result.approval = approval;
+      return result;
+    }
+  }
+
+  const matches = matchedFileRule ? [] : ruleEngine.match(context);
+  const outcome = matchedFileRule
+    ? {
+        decision: matchedFileRule.decision,
+        decision_source: "file_rule" as const,
+        reason_codes: fileRuleReasonCodes,
+        matched_rules: [],
+        challenge_ttl_seconds: decisionEngine.config.defaults.approval_ttl_seconds,
+      }
+    : decisionEngine.evaluate(context, matches);
+
+  let approval: ApprovalRecord | undefined;
+  if (outcome.decision === "challenge") {
+    const requestOptions = {
+      reason_codes: outcome.reason_codes,
+      rule_ids: matchedFileRule ? [`file_rule:${matchedFileRule.id}`] : outcome.matched_rules.map((rule) => rule.rule_id),
+      ...(outcome.challenge_ttl_seconds !== undefined ? { ttl_seconds: outcome.challenge_ttl_seconds } : {}),
+      ...(outcome.approval_requirements ? { approval_requirements: outcome.approval_requirements } : {}),
+    };
+    approval = approvals.requestApproval(context, requestOptions);
+  }
+
+  const result: GuardComputation<BeforeToolCallInput> = {
+    mutated_payload: mutatedPayload,
+    decision: outcome.decision,
+    decision_source: outcome.decision_source,
+    reason_codes: outcome.reason_codes,
+    sanitization_actions: [],
+    security_context: securityContext
+  };
+  if (approval !== undefined) {
+    result.approval = approval;
+  }
+  return result;
+}

package/src/hooks/result_guard.ts

@@ -0,0 +1,88 @@
+import type { AfterToolCallInput, DlpFinding, GuardComputation, SanitizationAction, SchemaExpectation, SecurityContext } from "../types.ts";
+import type { DlpEngine } from "../engine/dlp_engine.ts";
+
+function buildSecurityContext(input: AfterToolCallInput, traceId: string, policyVersion: string, nowIso: string): SecurityContext {
+  return {
+    trace_id: input.security_context?.trace_id ?? traceId,
+    actor_id: input.actor_id,
+    workspace: input.workspace,
+    policy_version: input.security_context?.policy_version ?? policyVersion,
+    untrusted: input.security_context?.untrusted ?? false,
+    tags: [...(input.security_context?.tags ?? [])],
+    created_at: input.security_context?.created_at ?? nowIso
+  };
+}
+
+function matchesType(value: unknown, expected: SchemaExpectation["type"]): boolean {
+  if (expected === "array") {
+    return Array.isArray(value);
+  }
+  if (expected === "object") {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+  }
+  return typeof value === expected;
+}
+
+function validateSchema(value: unknown, schema: SchemaExpectation, path = "result"): string[] {
+  const errors: string[] = [];
+  if (!matchesType(value, schema.type)) {
+    errors.push(`SCHEMA_TYPE_MISMATCH:${path}`);
+    return errors;
+  }
+  if (schema.type === "object" && schema.required && value && typeof value === "object") {
+    const record = value as Record<string, unknown>;
+    for (const [key, child] of Object.entries(schema.required)) {
+      if (!(key in record)) {
+        errors.push(`SCHEMA_MISSING_FIELD:${path}.${key}`);
+        continue;
+      }
+      errors.push(...validateSchema(record[key], child, `${path}.${key}`));
+    }
+  }
+  return errors;
+}
+
+function findingsToActions(findings: DlpFinding[]): SanitizationAction[] {
+  return findings.map((finding) => ({
+    path: finding.path,
+    action: finding.action,
+    detail: `${finding.pattern_name}:${finding.type}`
+  }));
+}
+
+export function runResultGuard(
+  input: AfterToolCallInput,
+  traceId: string,
+  policyVersion: string,
+  nowIso: string,
+  dlpEngine: DlpEngine,
+): GuardComputation<AfterToolCallInput> {
+  const securityContext = buildSecurityContext(input, traceId, policyVersion, nowIso);
+  const schemaErrors = input.expected_schema ? validateSchema(input.result, input.expected_schema) : [];
+  const findings = dlpEngine.scan(input.result);
+  const hasSchemaErrors = schemaErrors.length > 0;
+  const hasFindings = findings.length > 0;
+  const decision =
+    hasSchemaErrors || dlpEngine.config.on_dlp_hit === "block"
+      ? hasFindings || hasSchemaErrors
+        ? "block"
+        : "allow"
+      : hasFindings
+        ? dlpEngine.config.on_dlp_hit === "warn"
+          ? "warn"
+          : "allow"
+        : "allow";
+
+  const sanitizedResult =
+    hasFindings && dlpEngine.config.on_dlp_hit === "sanitize"
+      ? dlpEngine.sanitize(input.result, findings, "sanitize")
+      : input.result;
+
+  return {
+    mutated_payload: { ...input, result: sanitizedResult, security_context: securityContext } as AfterToolCallInput,
+    decision,
+    reason_codes: [...schemaErrors, ...(hasFindings ? ["DLP_HIT"] : ["RESULT_OK"])],
+    sanitization_actions: findingsToActions(findings),
+    security_context: securityContext
+  };
+}

package/src/i18n/locale.ts

@@ -0,0 +1,36 @@
+export type SecurityClawLocale = "zh-CN" | "en";
+
+export const DEFAULT_SECURITYCLAW_LOCALE: SecurityClawLocale = "en";
+
+function normalizeLocaleTag(value: string): string {
+  return value.trim().replace(/_/g, "-").toLowerCase();
+}
+
+export function resolveSecurityClawLocale(
+  value: string | undefined,
+  fallback: SecurityClawLocale = DEFAULT_SECURITYCLAW_LOCALE,
+): SecurityClawLocale {
+  const normalized = value ? normalizeLocaleTag(value) : "";
+  if (!normalized) {
+    return fallback;
+  }
+  if (normalized === "zh" || normalized.startsWith("zh-")) {
+    return "zh-CN";
+  }
+  if (normalized === "en" || normalized.startsWith("en-")) {
+    return "en";
+  }
+  return fallback;
+}
+
+export function isChineseLocale(locale: SecurityClawLocale): boolean {
+  return locale === "zh-CN";
+}
+
+export function localeForIntl(locale: SecurityClawLocale): string {
+  return isChineseLocale(locale) ? "zh-CN" : "en-US";
+}
+
+export function pickLocalized(locale: SecurityClawLocale, zhText: string, enText: string): string {
+  return isChineseLocale(locale) ? zhText : enText;
+}

package/src/index.ts

@@ -0,0 +1,255 @@
+import { ConfigManager } from "./config/loader.ts";
+import { ApprovalFsm } from "./engine/approval_fsm.ts";
+import { DecisionEngine } from "./engine/decision_engine.ts";
+import { DlpEngine } from "./engine/dlp_engine.ts";
+import { RuleEngine } from "./engine/rule_engine.ts";
+import { EventEmitter, HttpEventSink } from "./events/emitter.ts";
+import { runContextGuard } from "./hooks/context_guard.ts";
+import { runOutputGuard } from "./hooks/output_guard.ts";
+import { runPersistGuard } from "./hooks/persist_guard.ts";
+import { runPolicyGuard } from "./hooks/policy_guard.ts";
+import { runResultGuard } from "./hooks/result_guard.ts";
+import type {
+  AfterToolCallInput,
+  BeforePromptBuildInput,
+  BeforeToolCallInput,
+  EventSink,
+  GuardComputation,
+  HookName,
+  HookResult,
+  MessageSendingInput,
+  PluginHooks,
+  SecurityClawPluginOptions,
+  SecurityDecisionEvent,
+  ToolResultPersistInput
+} from "./types.ts";
+import { generateTraceId, nowIso, withTimeout } from "./utils.ts";
+
+export * from "./types.ts";
+export { ConfigManager } from "./config/loader.ts";
+export { securityDecisionEventSchema } from "./events/schema.ts";
+
+type PluginResult = {
+  hooks: PluginHooks;
+  approvals: ApprovalFsm;
+  config: ConfigManager;
+  events: EventEmitter;
+};
+
+type RuntimeDependencies = {
+  config: ReturnType<ConfigManager["getConfig"]>;
+  ruleEngine: RuleEngine;
+  decisionEngine: DecisionEngine;
+  dlpEngine: DlpEngine;
+};
+
+function buildEvent(
+  hook: HookName,
+  traceId: string,
+  result: GuardComputation,
+  latencyMs: number,
+  now: () => number,
+): SecurityDecisionEvent {
+  return {
+    schema_version: "1.0",
+    event_type: "SecurityDecisionEvent",
+    trace_id: traceId,
+    hook,
+    decision: result.decision,
+    reason_codes: result.reason_codes,
+    latency_ms: latencyMs,
+    ts: nowIso(now),
+    ...(result.decision_source !== undefined ? { decision_source: result.decision_source } : {})
+  };
+}
+
+async function executeGuard<TInput>(
+  hook: HookName,
+  input: TInput,
+  handler: () => Promise<GuardComputation<TInput>> | GuardComputation<TInput>,
+  dependencies: {
+    eventEmitter: EventEmitter;
+    configManager: ConfigManager;
+    now: () => number;
+  },
+): Promise<HookResult<TInput>> {
+  const config = dependencies.configManager.getConfig();
+  const controls = config.hooks[hook];
+  const traceId =
+    (input as { security_context?: { trace_id?: string }; trace_id?: string }).security_context?.trace_id ??
+    (input as { trace_id?: string }).trace_id ??
+    generateTraceId();
+  const startedAt = dependencies.now();
+
+  if (!controls.enabled) {
+    const latencyMs = dependencies.now() - startedAt;
+    return {
+      mutated_payload: input,
+      decision: "allow",
+      reason_codes: ["HOOK_DISABLED"],
+      sanitization_actions: [],
+      latency_ms: latencyMs
+    };
+  }
+
+  try {
+    const computation = await withTimeout(
+      Promise.resolve(handler()),
+      controls.timeout_ms,
+      `${hook} timed out`,
+    );
+    const latencyMs = dependencies.now() - startedAt;
+    const event = buildEvent(hook, traceId, computation, latencyMs, dependencies.now);
+    await dependencies.eventEmitter.emitSecurityEvent(event);
+    return {
+      ...computation,
+      latency_ms: latencyMs
+    };
+  } catch (error) {
+    const latencyMs = dependencies.now() - startedAt;
+    const decision = controls.fail_mode === "close" ? "block" : "allow";
+    const reason = error instanceof Error && error.message.includes("timed out") ? "HOOK_TIMEOUT" : "HOOK_ERROR";
+    const fallback: GuardComputation<TInput> = {
+      mutated_payload: input,
+      decision,
+      reason_codes: [reason],
+      sanitization_actions: []
+    };
+    const event = buildEvent(hook, traceId, fallback, latencyMs, dependencies.now);
+    await dependencies.eventEmitter.emitSecurityEvent(event);
+    return {
+      ...fallback,
+      latency_ms: latencyMs
+    };
+  }
+}
+
+export function createSecurityClawPlugin(options: SecurityClawPluginOptions = {}): PluginResult {
+  const now = options.now ?? Date.now;
+  const configManager = options.config
+    ? new ConfigManager(options.config)
+    : ConfigManager.fromFile(options.config_path ?? "./config/policy.default.yaml");
+  const initialConfig = configManager.getConfig();
+  const sink: EventSink | undefined =
+    options.event_sink ??
+    (initialConfig.event_sink.webhook_url
+      ? new HttpEventSink(initialConfig.event_sink.webhook_url, initialConfig.event_sink.timeout_ms)
+      : undefined);
+  const eventEmitter = new EventEmitter(
+    sink,
+    initialConfig.event_sink.max_buffer,
+    initialConfig.event_sink.retry_limit,
+  );
+  const approvals = new ApprovalFsm(now);
+  const traceGenerator = options.generate_trace_id ?? generateTraceId;
+
+  function buildRuntime(config: ReturnType<ConfigManager["getConfig"]>): RuntimeDependencies {
+    return {
+      config,
+      ruleEngine: new RuleEngine(config.policies),
+      decisionEngine: new DecisionEngine(config),
+      dlpEngine: new DlpEngine(config.dlp)
+    };
+  }
+
+  let runtime = buildRuntime(configManager.getConfig());
+  function getRuntime(): RuntimeDependencies {
+    const latest = configManager.getConfig();
+    if (latest !== runtime.config) {
+      runtime = buildRuntime(latest);
+    }
+    return runtime;
+  }
+
+  return {
+    hooks: {
+      before_prompt_build: (input: BeforePromptBuildInput) =>
+        executeGuard(
+          "before_prompt_build",
+          input,
+          () => {
+            const current = getRuntime();
+            return runContextGuard(
+              input,
+              current.config.policy_version,
+              input.trace_id ?? traceGenerator(),
+              nowIso(now),
+            );
+          },
+          { eventEmitter, configManager, now },
+        ),
+      before_tool_call: (input: BeforeToolCallInput) =>
+        executeGuard(
+          "before_tool_call",
+          input,
+          () => {
+            const current = getRuntime();
+            return runPolicyGuard(
+              input,
+              current.config.policy_version,
+              input.security_context?.trace_id ?? traceGenerator(),
+              nowIso(now),
+              current.ruleEngine,
+              current.decisionEngine,
+              approvals,
+              current.config.sensitivity.path_rules,
+              current.config.file_rules,
+            );
+          },
+          { eventEmitter, configManager, now },
+        ),
+      after_tool_call: (input: AfterToolCallInput) =>
+        executeGuard(
+          "after_tool_call",
+          input,
+          () => {
+            const current = getRuntime();
+            return runResultGuard(
+              input,
+              input.security_context?.trace_id ?? traceGenerator(),
+              current.config.policy_version,
+              nowIso(now),
+              current.dlpEngine,
+            );
+          },
+          { eventEmitter, configManager, now },
+        ),
+      tool_result_persist: (input: ToolResultPersistInput) =>
+        executeGuard(
+          "tool_result_persist",
+          input,
+          () => {
+            const current = getRuntime();
+            return runPersistGuard(
+              input,
+              input.security_context?.trace_id ?? traceGenerator(),
+              current.config.policy_version,
+              nowIso(now),
+              current.dlpEngine,
+              current.config.defaults.persist_mode,
+            );
+          },
+          { eventEmitter, configManager, now },
+        ),
+      message_sending: (input: MessageSendingInput) =>
+        executeGuard(
+          "message_sending",
+          input,
+          () => {
+            const current = getRuntime();
+            return runOutputGuard(
+              input,
+              input.security_context?.trace_id ?? traceGenerator(),
+              current.config.policy_version,
+              nowIso(now),
+              current.dlpEngine,
+            );
+          },
+          { eventEmitter, configManager, now },
+        )
+    },
+    approvals,
+    config: configManager,
+    events: eventEmitter
+  };
+}