haechi 0.3.2

package/packages/crypto/index.mjs

@@ -0,0 +1,142 @@
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
+import { dirname } from "node:path";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+
+const ALG = "AES-256-GCM";
+
+export function createLocalCryptoProvider({ keyFile }) {
+  if (!keyFile) {
+    throw new Error("Local crypto provider requires keyFile");
+  }
+
+  let cachedKeys = null;
+
+  async function loadKeys() {
+    if (cachedKeys) {
+      return cachedKeys;
+    }
+    const raw = JSON.parse(await readFile(keyFile, "utf8"));
+    if (!raw.keys?.length) {
+      throw new Error(`No keys found in ${keyFile}`);
+    }
+    const byKid = new Map();
+    for (const entry of raw.keys) {
+      const key = Buffer.from(entry.k, "base64url");
+      if (key.length !== 32) {
+        throw new Error("AES-256-GCM local key must be 32 bytes");
+      }
+      byKid.set(entry.kid, { kid: entry.kid, key });
+    }
+    const activeEntry = raw.keys.find((key) => key.status === "active") ?? raw.keys[0];
+    cachedKeys = {
+      active: byKid.get(activeEntry.kid),
+      byKid
+    };
+    return cachedKeys;
+  }
+
+  return {
+    id: "haechi.crypto.local-aes-gcm",
+    version: "0.1.0",
+    capabilities: {
+      readsPlaintext: true,
+      networkEgress: false
+    },
+    async encrypt({ plaintext, aad }) {
+      const { active: { kid, key } } = await loadKeys();
+      const iv = randomBytes(12);
+      const cipher = createCipheriv("aes-256-gcm", key, iv);
+      const aadBytes = Buffer.from(canonicalize(aad), "utf8");
+      cipher.setAAD(aadBytes);
+      const ciphertext = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+      const tag = cipher.getAuthTag();
+      return {
+        v: 1,
+        alg: ALG,
+        kid,
+        iv: iv.toString("base64url"),
+        ct: ciphertext.toString("base64url"),
+        tag: tag.toString("base64url"),
+        aadHash: sha256(aadBytes)
+      };
+    },
+    async decrypt({ envelope, aad }) {
+      const { active, byKid } = await loadKeys();
+      if (envelope.alg && envelope.alg !== ALG) {
+        throw new Error(`Unsupported local crypto algorithm: ${envelope.alg}`);
+      }
+      const selected = envelope.kid ? byKid.get(envelope.kid) : active;
+      if (!selected) {
+        throw new Error(`Unknown key id in envelope: ${envelope.kid}`);
+      }
+      const { key } = selected;
+      const aadBytes = Buffer.from(canonicalize(aad), "utf8");
+      if (envelope.aadHash && envelope.aadHash !== sha256(aadBytes)) {
+        throw new Error("AAD hash mismatch");
+      }
+      const decipher = createDecipheriv("aes-256-gcm", key, Buffer.from(envelope.iv, "base64url"));
+      decipher.setAAD(aadBytes);
+      decipher.setAuthTag(Buffer.from(envelope.tag, "base64url"));
+      const plaintext = Buffer.concat([
+        decipher.update(Buffer.from(envelope.ct, "base64url")),
+        decipher.final()
+      ]);
+      return plaintext.toString("utf8");
+    }
+  };
+}
+
+export async function initLocalKeyFile(keyFile, { force = false } = {}) {
+  await mkdir(dirname(keyFile), { recursive: true });
+
+  let existing = null;
+  try {
+    existing = JSON.parse(await readFile(keyFile, "utf8"));
+    if (!force) {
+      return { created: false, keyFile };
+    }
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+
+  // Rotating with --force must not orphan existing envelopes/token vault
+  // records, so prior keys are retained as retired and stay kid-addressable.
+  const retiredKeys = (existing?.keys ?? []).map((key) => ({
+    ...key,
+    status: key.status === "active" ? "retired" : key.status
+  }));
+
+  const key = {
+    version: 1,
+    createdAt: new Date().toISOString(),
+    keys: [
+      {
+        kid: `local-${Date.now()}-${randomBytes(3).toString("hex")}`,
+        kty: "oct",
+        alg: ALG,
+        status: "active",
+        k: randomBytes(32).toString("base64url")
+      },
+      ...retiredKeys
+    ]
+  };
+
+  await writeFile(keyFile, `${JSON.stringify(key, null, 2)}\n`, { mode: 0o600 });
+  return { created: true, keyFile, rotated: retiredKeys.length > 0 };
+}
+
+export function canonicalize(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => canonicalize(item)).join(",")}]`;
+  }
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalize(value[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function sha256(value) {
+  return createHash("sha256").update(value).digest("base64url");
+}

package/packages/filter/index.mjs

@@ -0,0 +1,189 @@
+const DEFAULT_RULES = [
+  {
+    id: "email",
+    type: "email",
+    pattern: "\\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\\.[A-Z]{2,}\\b",
+    flags: "gi",
+    confidence: 0.95
+  },
+  {
+    id: "kr-phone",
+    type: "phone",
+    pattern: "(?:\\+82[-\\s]?)?0?1[016789][-.\\s]?\\d{3,4}[-.\\s]?\\d{4}",
+    flags: "g",
+    confidence: 0.9
+  },
+  {
+    id: "kr-rrn-like",
+    type: "kr_rrn",
+    pattern: "\\b\\d{6}[-\\s]?[1-8]\\d{6}\\b",
+    flags: "g",
+    confidence: 0.85,
+    validate: krRrnValid
+  },
+  {
+    id: "card-like",
+    type: "card",
+    pattern: "\\b(?:\\d[ -]*?){13,19}\\b",
+    flags: "g",
+    confidence: 0.75,
+    validate: luhnValid
+  },
+  {
+    id: "openai-like-key",
+    type: "api_key",
+    pattern: "\\b(?:sk|rk|pk)_[A-Za-z0-9_-]{24,}\\b",
+    flags: "g",
+    confidence: 0.95
+  },
+  {
+    id: "bearer-token",
+    type: "secret",
+    pattern: "\\bBearer\\s+[A-Za-z0-9._~+/-]{16,}\\b",
+    flags: "g",
+    confidence: 0.9
+  },
+  {
+    id: "assignment-secret",
+    type: "secret",
+    // Lookbehind keeps the key name out of the match so transforms replace
+    // only the secret value, not the assignment prefix.
+    pattern: "(?<=\\b(?:api[_-]?key|secret|token|password)\\s*[:=]\\s*['\\\"]?)[A-Za-z0-9._~+/-]{12,}",
+    flags: "gi",
+    confidence: 0.85
+  }
+];
+
+export function createDefaultFilterEngine({ customRules = [] } = {}) {
+  const rules = DEFAULT_RULES.concat(customRules.map(normalizeCustomRule));
+
+  return {
+    id: "haechi.filter.default",
+    version: "0.1.0",
+    capabilities: {
+      readsPlaintext: true,
+      networkEgress: false
+    },
+    async detect({ entries }) {
+      return entries.flatMap((entry) => detectEntry(entry, rules));
+    }
+  };
+}
+
+export function detectEntry(entry, rules) {
+  const detections = [];
+
+  for (const rule of rules) {
+    const regex = new RegExp(rule.pattern, rule.flags.includes("g") ? rule.flags : `${rule.flags}g`);
+    for (const match of entry.value.matchAll(regex)) {
+      const value = match[0];
+      if (rule.validate && !rule.validate(value)) {
+        continue;
+      }
+      detections.push({
+        type: rule.type,
+        ruleId: rule.id,
+        path: entry.path,
+        pathText: entry.pathText,
+        kind: entry.kind ?? "value",
+        start: match.index,
+        end: match.index + value.length,
+        confidence: rule.confidence,
+        value
+      });
+    }
+  }
+
+  return removeOverlaps(detections);
+}
+
+function normalizeCustomRule(rule) {
+  if (!rule.id || !rule.type || !rule.pattern) {
+    throw new Error("Custom filter rule requires id, type, and pattern");
+  }
+  validateCustomPattern(rule.pattern);
+  validateFlags(rule.flags ?? "g");
+  return {
+    id: rule.id,
+    type: rule.type,
+    pattern: rule.pattern,
+    flags: rule.flags ?? "g",
+    confidence: rule.confidence ?? 0.7
+  };
+}
+
+function validateCustomPattern(pattern) {
+  if (pattern.length > 500) {
+    throw new Error("Custom filter rule pattern is too long");
+  }
+  if (/(?:\([^)]*[+*][^)]*\)){1}[+*{]/.test(pattern)) {
+    throw new Error("Custom filter rule pattern contains nested quantifiers");
+  }
+  if (/\\[1-9]/.test(pattern)) {
+    throw new Error("Custom filter rule pattern must not use backreferences");
+  }
+}
+
+function validateFlags(flags) {
+  if (!/^[dgimsuvy]*$/.test(flags)) {
+    throw new Error(`Invalid custom filter flags: ${flags}`);
+  }
+}
+
+function removeOverlaps(detections) {
+  const sorted = detections.sort((left, right) => {
+    if (left.start !== right.start) {
+      return left.start - right.start;
+    }
+    return (right.end - right.start) - (left.end - left.start);
+  });
+
+  const accepted = [];
+  let lastEnd = -1;
+
+  for (const detection of sorted) {
+    if (detection.start < lastEnd) {
+      continue;
+    }
+    accepted.push(detection);
+    lastEnd = detection.end;
+  }
+
+  return accepted;
+}
+
+function luhnValid(value) {
+  const digits = value.replace(/\D/g, "");
+  if (digits.length < 13 || digits.length > 19) {
+    return false;
+  }
+
+  let sum = 0;
+  let alternate = false;
+
+  for (let index = digits.length - 1; index >= 0; index -= 1) {
+    let digit = Number(digits[index]);
+    if (alternate) {
+      digit *= 2;
+      if (digit > 9) {
+        digit -= 9;
+      }
+    }
+    sum += digit;
+    alternate = !alternate;
+  }
+
+  return sum % 10 === 0;
+}
+
+function krRrnValid(value) {
+  const digits = value.replace(/\D/g, "");
+  if (digits.length !== 13) {
+    return false;
+  }
+
+  const weights = [2, 3, 4, 5, 6, 7, 8, 9, 2, 3, 4, 5];
+  const sum = weights.reduce((total, weight, index) => total + weight * Number(digits[index]), 0);
+  const check = (11 - (sum % 11)) % 10;
+  return check === Number(digits[12]);
+}

package/packages/mcp-stdio/index.mjs

@@ -0,0 +1,105 @@
+import { createInterface } from "node:readline";
+
+export async function protectMcpJsonRpcMessage(message, runtime) {
+  if (!message || typeof message !== "object" || Array.isArray(message)) {
+    throw new Error(Array.isArray(message)
+      ? "JSON-RPC batch messages are not supported by the MCP stdio filter"
+      : "MCP message must be a JSON object");
+  }
+  const policy = runtime.config.mcp;
+  // JSON-RPC notifications (method, no id) must not receive responses; a
+  // rejected or blocked notification is dropped (returns null) instead.
+  const isNotification = message.method !== undefined
+    && !Object.prototype.hasOwnProperty.call(message, "id");
+  if (policy.requireJsonRpc && message.jsonrpc !== "2.0") {
+    return isNotification ? null : errorJsonRpc(message.id, -32002, "haechi_mcp_invalid_jsonrpc", {
+      reason: "MCP messages must use JSON-RPC 2.0"
+    });
+  }
+  if (message.method && !methodAllowed(message.method, policy.allowedMethods)) {
+    return isNotification ? null : errorJsonRpc(message.id, -32003, "haechi_mcp_method_not_allowed", {
+      method: message.method
+    });
+  }
+
+  const next = structuredClone(message);
+
+  if (policy.protectParams && Object.prototype.hasOwnProperty.call(next, "params")) {
+    const result = await runtime.haechi.protectJson(next.params, {
+      protocol: "mcp-stdio",
+      operation: next.method ?? "params",
+      mode: runtime.config.policy.mode ?? runtime.config.mode
+    });
+    if (result.blocked) {
+      return isNotification ? null : blockedJsonRpc(next.id, result);
+    }
+    next.params = result.payload;
+  }
+
+  if (policy.protectResults && Object.prototype.hasOwnProperty.call(next, "result")) {
+    const result = await runtime.haechi.protectJson(next.result, {
+      protocol: "mcp-stdio",
+      operation: "result",
+      mode: runtime.config.policy.mode ?? runtime.config.mode
+    });
+    if (result.blocked) {
+      return blockedJsonRpc(next.id, result);
+    }
+    next.result = result.payload;
+  }
+
+  return next;
+}
+
+export async function runMcpStdioFilter({ input = process.stdin, output = process.stdout, runtime }) {
+  const lines = createInterface({ input, crlfDelay: Infinity });
+
+  for await (const line of lines) {
+    if (!line.trim()) {
+      continue;
+    }
+    try {
+      const message = JSON.parse(line);
+      const protectedMessage = await protectMcpJsonRpcMessage(message, runtime);
+      if (protectedMessage === null) {
+        continue;
+      }
+      output.write(`${JSON.stringify(protectedMessage)}\n`);
+    } catch (error) {
+      output.write(`${JSON.stringify({
+        jsonrpc: "2.0",
+        error: {
+          code: -32000,
+          message: "haechi_mcp_stdio_error",
+          data: {
+            reason: error.message
+          }
+        },
+        id: null
+      })}\n`);
+    }
+  }
+}
+
+function blockedJsonRpc(id, result) {
+  return errorJsonRpc(id, -32001, "haechi_policy_block", {
+    auditId: result.auditEvent.id,
+    summary: result.summary
+  });
+}
+
+function errorJsonRpc(id, code, message, data) {
+  return {
+    jsonrpc: "2.0",
+    error: {
+      code,
+      message,
+      data
+    },
+    id: id ?? null
+  };
+}
+
+function methodAllowed(method, allowedMethods) {
+  return allowedMethods.includes("*") || allowedMethods.includes(method);
+}

package/packages/plugin/index.mjs

@@ -0,0 +1,83 @@
+import { readFile } from "node:fs/promises";
+
+const VALID_KINDS = new Set([
+  "crypto-provider",
+  "key-provider",
+  "policy-engine",
+  "filter-engine",
+  "token-vault",
+  "audit-sink",
+  "protocol-adapter",
+  "classifier-plugin"
+]);
+
+const CAPABILITY_KEYS = [
+  "readsPlaintext",
+  "writesPlaintext",
+  "networkEgress",
+  "fileWrite",
+  "auditWrite",
+  "externalSecrets"
+];
+const VALID_RUNTIMES = new Set(["manifest-only"]);
+
+export async function validatePluginManifestFile(path) {
+  const manifest = JSON.parse(await readFile(path, "utf8"));
+  return validatePluginManifest(manifest);
+}
+
+export function validatePluginManifest(manifest) {
+  const plugin = manifest?.haechiPlugin;
+  const errors = [];
+
+  if (!plugin) {
+    errors.push("missing haechiPlugin root");
+  } else {
+    requireString(plugin, "id", errors);
+    requireString(plugin, "version", errors);
+    requireString(plugin, "kind", errors);
+    requireString(plugin, "runtime", errors);
+    requireString(plugin, "entrypoint", errors);
+
+    if (plugin.kind && !VALID_KINDS.has(plugin.kind)) {
+      errors.push(`invalid kind: ${plugin.kind}`);
+    }
+
+    if (plugin.runtime && !VALID_RUNTIMES.has(plugin.runtime)) {
+      errors.push("dynamic plugin execution is not supported; set runtime to manifest-only");
+    }
+
+    if (!plugin.compatibility?.haechiCore) {
+      errors.push("missing compatibility.haechiCore");
+    }
+
+    if (!plugin.capabilities || typeof plugin.capabilities !== "object") {
+      errors.push("missing capabilities");
+    } else {
+      for (const key of CAPABILITY_KEYS) {
+        if (typeof plugin.capabilities[key] !== "boolean") {
+          errors.push(`capabilities.${key} must be boolean`);
+        }
+      }
+    }
+
+    if (plugin.capabilities?.networkEgress && plugin.capabilities.readsPlaintext && !plugin.dataHandling?.retention) {
+      errors.push("plaintext-reading network plugins must declare dataHandling.retention");
+    }
+
+    if (plugin.dataHandling?.logsRawPayload === true) {
+      errors.push("dataHandling.logsRawPayload must not be true");
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+
+function requireString(object, key, errors) {
+  if (!object[key] || typeof object[key] !== "string") {
+    errors.push(`missing ${key}`);
+  }
+}

package/packages/policy/index.mjs

@@ -0,0 +1,165 @@
+const PRESETS = {
+  "llm-redact": {
+    defaultAction: "redact",
+    actions: {
+      email: "redact",
+      phone: "mask"
+    }
+  },
+  "korean-pii": {
+    actions: {
+      kr_rrn: "block",
+      phone: "mask",
+      email: "redact"
+    }
+  },
+  "secrets-only": {
+    actions: {
+      api_key: "block",
+      secret: "block"
+    }
+  },
+  "strict-block": {
+    defaultAction: "block"
+  },
+  "local-only": {
+    transfer: {
+      allowExternal: false
+    }
+  },
+  "mcp-basic": {
+    defaultAction: "redact",
+    actions: {
+      api_key: "block",
+      secret: "block",
+      kr_rrn: "block"
+    }
+  },
+  "local-inference": {
+    defaultAction: "redact",
+    actions: {
+      email: "tokenize",
+      phone: "mask",
+      api_key: "block",
+      secret: "block",
+      kr_rrn: "block"
+    }
+  }
+};
+
+const VALID_ACTIONS = new Set(["allow", "redact", "mask", "tokenize", "encrypt", "block"]);
+export const ACTION_STRENGTH = {
+  allow: 0,
+  redact: 1,
+  mask: 1,
+  tokenize: 2,
+  encrypt: 2,
+  block: 3
+};
+
+export function buildPolicy({
+  presets = [],
+  mode = "dry-run",
+  defaultAction = "redact",
+  actions = {},
+  customRules = [],
+  allowUnsafeOverrides = false
+} = {}) {
+  const merged = {
+    mode,
+    defaultAction,
+    actions: {},
+    customRules,
+    allowUnsafeOverrides
+  };
+
+  for (const presetName of presets) {
+    const preset = PRESETS[presetName];
+    if (!preset) {
+      throw new Error(`Unknown policy preset: ${presetName}`);
+    }
+    if (preset.defaultAction) {
+      merged.defaultAction = preset.defaultAction;
+    }
+    for (const [type, action] of Object.entries(preset.actions ?? {})) {
+      mergeAction(merged.actions, type, action, {
+        source: `preset:${presetName}`,
+        allowUnsafeOverrides
+      });
+    }
+  }
+
+  for (const [type, action] of Object.entries(actions)) {
+    mergeAction(merged.actions, type, action, {
+      source: "policy.actions",
+      allowUnsafeOverrides
+    });
+  }
+  validatePolicy(merged);
+  return merged;
+}
+
+export function createPolicyEngine(policy) {
+  validatePolicy(policy);
+
+  return {
+    id: "haechi.policy.reference",
+    version: "0.1.0",
+    capabilities: {
+      readsPlaintext: false,
+      networkEgress: false
+    },
+    async decide({ detection, mode }) {
+      const action = policy.actions[detection.type] ?? policy.defaultAction ?? "redact";
+      return {
+        action,
+        reason: `matched:${detection.ruleId}`,
+        mode: mode ?? policy.mode ?? "dry-run"
+      };
+    },
+    async validatePolicy(candidate) {
+      validatePolicy(candidate);
+      return { valid: true };
+    }
+  };
+}
+
+export function validatePolicy(policy) {
+  if (!policy || typeof policy !== "object") {
+    throw new Error("Policy must be an object");
+  }
+  if (policy.defaultAction && !VALID_ACTIONS.has(policy.defaultAction)) {
+    throw new Error(`Invalid default action: ${policy.defaultAction}`);
+  }
+  for (const [type, action] of Object.entries(policy.actions ?? {})) {
+    if (!VALID_ACTIONS.has(action)) {
+      throw new Error(`Invalid action for ${type}: ${action}`);
+    }
+  }
+  if (policy.mode && !["dry-run", "report-only", "enforce"].includes(policy.mode)) {
+    throw new Error(`Invalid policy mode: ${policy.mode}`);
+  }
+  if (policy.allowUnsafeOverrides !== undefined && typeof policy.allowUnsafeOverrides !== "boolean") {
+    throw new Error("allowUnsafeOverrides must be boolean");
+  }
+}
+
+function mergeAction(target, type, action, { source, allowUnsafeOverrides }) {
+  if (!VALID_ACTIONS.has(action)) {
+    throw new Error(`Invalid action for ${type}: ${action}`);
+  }
+
+  const existing = target[type];
+  if (!existing) {
+    target[type] = action;
+    return;
+  }
+
+  if (ACTION_STRENGTH[action] < ACTION_STRENGTH[existing] && !allowUnsafeOverrides) {
+    throw new Error(`Policy action conflict for ${type}: ${source} cannot weaken ${existing} to ${action}`);
+  }
+
+  if (ACTION_STRENGTH[action] >= ACTION_STRENGTH[existing]) {
+    target[type] = action;
+  }
+}