haechi 0.4.0 → 0.6.0

package/packages/auth/index.mjs

@@ -0,0 +1,170 @@
+// Built-in bearer authentication and the authProvider contract.
+//
+// Tokens are never stored in plaintext: the store keeps a keyed-HMAC hash
+// (domain-separated, never a bare hash) plus PII-safe metadata. The plaintext
+// token is shown once at creation. Identity objects are PII-safe by
+// construction — subject/issuer are keyed HMACs, never raw values.
+
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+
+const TOKEN_DOMAIN = "haechi:auth:token:v1";
+const IDENTITY_DOMAIN = "haechi:identity:hash:v1";
+const TOKEN_PREFIX = "hae_";
+const DEFAULT_ALLOWED_LABEL_KEYS = ["team", "env", "tier", "role"];
+const VALID_IDENTITY_TYPES = new Set(["user", "service", "agent"]);
+const MAX_LABEL_VALUE_LENGTH = 64;
+
+export async function readAuthStore(path) {
+  try {
+    const parsed = JSON.parse(await readFile(path, "utf8"));
+    return { version: parsed.version ?? 1, tokens: parsed.tokens ?? [] };
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return { version: 1, tokens: [] };
+    }
+    throw error;
+  }
+}
+
+async function writeAuthStore(path, store) {
+  await mkdir(dirname(path), { recursive: true });
+  const tempPath = `${path}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+  await writeFile(tempPath, `${JSON.stringify(store, null, 2)}\n`, { mode: 0o600 });
+  await rename(tempPath, path);
+}
+
+export function validateLabels(labels, allowedLabelKeys = DEFAULT_ALLOWED_LABEL_KEYS) {
+  for (const [key, value] of Object.entries(labels)) {
+    if (!allowedLabelKeys.includes(key)) {
+      throw new Error(`Label key not allowed: ${key} (allowed: ${allowedLabelKeys.join(", ") || "none"})`);
+    }
+    if (typeof value !== "string" || value.length === 0 || value.length > MAX_LABEL_VALUE_LENGTH) {
+      throw new Error(`Label value for ${key} must be a non-empty string up to ${MAX_LABEL_VALUE_LENGTH} chars`);
+    }
+  }
+  return labels;
+}
+
+export async function addToken({ path, cryptoProvider, type, scopes = [], labels = {}, allowedLabelKeys = DEFAULT_ALLOWED_LABEL_KEYS }) {
+  if (!VALID_IDENTITY_TYPES.has(type)) {
+    throw new Error(`Invalid token type: ${type} (expected user | service | agent)`);
+  }
+  if (!Array.isArray(scopes) || !scopes.every((scope) => typeof scope === "string" && scope.trim())) {
+    throw new Error("scopes must be an array of non-empty strings");
+  }
+  validateLabels(labels, allowedLabelKeys);
+
+  const token = `${TOKEN_PREFIX}${randomBytes(32).toString("base64url")}`;
+  const tokenHash = await cryptoProvider.hmac({ data: token, domain: TOKEN_DOMAIN });
+  const record = {
+    id: `tok_auth_${randomUUID().slice(0, 8)}`,
+    tokenHash,
+    type,
+    scopes,
+    labels,
+    createdAt: new Date().toISOString(),
+    disabled: false
+  };
+
+  const store = await readAuthStore(path);
+  store.tokens.push(record);
+  await writeAuthStore(path, store);
+
+  // The plaintext token is returned to the caller for one-time display only.
+  return { token, record: publicRecord(record) };
+}
+
+export async function listTokens(path) {
+  const store = await readAuthStore(path);
+  return store.tokens.map(publicRecord);
+}
+
+export async function revokeToken({ path, id }) {
+  const store = await readAuthStore(path);
+  const record = store.tokens.find((entry) => entry.id === id);
+  if (!record) {
+    throw new Error(`Unknown token id: ${id}`);
+  }
+  const changed = !record.disabled;
+  record.disabled = true;
+  await writeAuthStore(path, store);
+  return { id, revoked: changed };
+}
+
+function publicRecord(record) {
+  // Never expose the token or its hash.
+  return {
+    id: record.id,
+    type: record.type,
+    scopes: record.scopes,
+    labels: record.labels,
+    createdAt: record.createdAt,
+    disabled: Boolean(record.disabled)
+  };
+}
+
+export async function buildIdentity(record, cryptoProvider) {
+  return {
+    id: record.id,
+    type: record.type,
+    subjectHash: await cryptoProvider.hmac({ data: record.id, domain: IDENTITY_DOMAIN }),
+    issuerHash: await cryptoProvider.hmac({ data: "bearer-local", domain: IDENTITY_DOMAIN }),
+    provider: "bearer",
+    scopes: record.scopes ?? [],
+    labels: record.labels ?? {}
+  };
+}
+
+function bearerTokenFromRequest(request) {
+  const header = request?.headers?.authorization ?? request?.headers?.Authorization;
+  if (typeof header !== "string") {
+    return null;
+  }
+  const match = /^Bearer\s+(.+)$/i.exec(header.trim());
+  return match ? match[1].trim() : null;
+}
+
+function constantTimeHashMatch(candidateHash, storedHash) {
+  const a = Buffer.from(candidateHash, "utf8");
+  const b = Buffer.from(storedHash, "utf8");
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+// authProvider contract: authenticate(request) -> identity | null. Fails closed
+// (null/deny) for a missing/invalid/disabled token; throws are treated as deny
+// by the caller.
+export function createBearerAuthProvider({ path, cryptoProvider }) {
+  if (!path) {
+    throw new Error("Bearer auth provider requires a store path");
+  }
+  if (typeof cryptoProvider?.hmac !== "function") {
+    throw new Error("Bearer auth provider requires a cryptoProvider with hmac()");
+  }
+  return {
+    id: "haechi.auth.bearer",
+    async authenticate(request) {
+      const token = bearerTokenFromRequest(request);
+      if (!token) {
+        return null;
+      }
+      const candidateHash = await cryptoProvider.hmac({ data: token, domain: TOKEN_DOMAIN });
+      const store = await readAuthStore(path);
+      let matched = null;
+      // Scan every record (no early return) so timing does not reveal which
+      // token matched.
+      for (const record of store.tokens) {
+        if (!record.disabled && constantTimeHashMatch(candidateHash, record.tokenHash)) {
+          matched = record;
+        }
+      }
+      if (!matched) {
+        return null;
+      }
+      return buildIdentity(matched, cryptoProvider);
+    }
+  };
+}
+
+export { DEFAULT_ALLOWED_LABEL_KEYS };

package/packages/cli/bin/haechi.mjs

@@ -5,11 +5,14 @@ import { DEFAULT_PROXY_PORT, createHaechiProxy } from "../../proxy/index.mjs";
 import { signPolicyBundleFile, verifyPolicyBundleFile } from "../../policy-bundle/index.mjs";
 import { validatePluginManifestFile } from "../../plugin/index.mjs";
 import { runMcpStdioFilter, wrapMcpChild } from "../../mcp-stdio/index.mjs";
+import { addToken, listTokens, revokeToken } from "../../auth/index.mjs";
+import { createLocalCryptoProvider } from "../../crypto/index.mjs";
 import { spawn } from "node:child_process";
 import { DEFAULT_CONFIG_PATH, createRuntime, isValidPort, loadConfig, writeDefaultConfig } from "../runtime.mjs";
 
 const [command, ...argv] = process.argv.slice(2);
 
+async function main(command, argv) {
 try {
   switch (command) {
     case "init":
@@ -54,19 +57,26 @@ try {
     case "mcp-wrap":
       await mcpWrapCommand(argv);
       break;
+    case "auth":
+      await authCommand(argv);
+      break;
+    case "config":
+      printConfigGuide();
+      break;
     case "help":
     case "--help":
     case "-h":
     case undefined:
-      printHelp();
+      printHelp(argv[0]);
       break;
     default:
-      throw new Error(`Unknown command: ${command}`);
+      throw new Error(`Unknown command: ${command}. Run 'haechi help' for usage.`);
   }
 } catch (error) {
   console.error(`haechi: ${error.message}`);
   process.exitCode = process.exitCode || 1;
 }
+}
 
 async function initCommand(argv) {
   const options = parseOptions(argv);
@@ -222,7 +232,8 @@ async function statusCommand(argv) {
         mode: config.responseProtection.mode,
         failureMode: config.responseProtection.failureMode
       },
-      streamingRequestMode: config.streaming.requestMode
+      streamingRequestMode: config.streaming.requestMode,
+      streamingResponseMode: config.streaming.responseMode
     },
     target: {
       type: config.target.type,
@@ -396,6 +407,76 @@ async function pluginValidateCommand(argv) {
   }
 }
 
+async function authCommand(argv) {
+  const [sub, ...rest] = argv;
+  const options = parseOptions(rest);
+  const config = await loadConfig(options.config ?? DEFAULT_CONFIG_PATH);
+  if (config.keys.provider !== "local") {
+    throw new Error("haechi auth requires keys.provider local (the bearer store is hashed with the local key)");
+  }
+  const cryptoProvider = createLocalCryptoProvider({ keyFile: config.keys.keyFile });
+  const storePath = config.auth.store;
+
+  switch (sub) {
+    case "add": {
+      if (!options.type || options.type === true) {
+        throw new Error("auth add requires --type user|service|agent");
+      }
+      const { token, record } = await addToken({
+        path: storePath,
+        cryptoProvider,
+        type: options.type,
+        scopes: asList(options.scope),
+        labels: asLabels(options.label),
+        allowedLabelKeys: config.auth.allowedLabelKeys
+      });
+      writeJson({
+        ok: true,
+        command: "auth add",
+        id: record.id,
+        type: record.type,
+        scopes: record.scopes,
+        labels: record.labels,
+        token,
+        warning: "This token is shown only once. Store it now; it is not recoverable."
+      });
+      return;
+    }
+    case "list":
+      writeJson({ ok: true, command: "auth list", tokens: await listTokens(storePath) });
+      return;
+    case "revoke": {
+      const [id] = rest;
+      if (!id || id.startsWith("--")) {
+        throw new Error("auth revoke requires a token id");
+      }
+      writeJson({ ok: true, command: "auth revoke", result: await revokeToken({ path: storePath, id }) });
+      return;
+    }
+    default:
+      throw new Error("auth requires a subcommand: add | list | revoke");
+  }
+}
+
+function asList(value) {
+  if (!value || value === true) {
+    return [];
+  }
+  return Array.isArray(value) ? value : [value];
+}
+
+function asLabels(value) {
+  const labels = {};
+  for (const entry of asList(value)) {
+    const index = entry.indexOf("=");
+    if (index === -1) {
+      throw new Error(`Invalid --label (expected key=value): ${entry}`);
+    }
+    labels[entry.slice(0, index)] = entry.slice(index + 1);
+  }
+  return labels;
+}
+
 async function mcpStdioCommand(argv) {
   const options = parseOptions(argv);
   const config = await loadConfig(options.config ?? DEFAULT_CONFIG_PATH);
@@ -436,12 +517,17 @@ function parseOptions(argv) {
     }
     const key = arg.slice(2);
     const next = argv[index + 1];
-    if (!next || next.startsWith("--")) {
-      options[key] = true;
-      continue;
+    const value = (!next || next.startsWith("--")) ? true : next;
+    if (value !== true) {
+      index += 1;
+    }
+    // Repeated flags accumulate into an array (e.g. --scope a --scope b);
+    // a single occurrence stays scalar for backward compatibility.
+    if (Object.prototype.hasOwnProperty.call(options, key)) {
+      options[key] = Array.isArray(options[key]) ? [...options[key], value] : [options[key], value];
+    } else {
+      options[key] = value;
     }
-    options[key] = next;
-    index += 1;
   }
   return options;
 }
@@ -464,26 +550,166 @@ function parsePort(value) {
   return port;
 }
 
-function printHelp() {
-  console.log(`Haechi MVP CLI
+const COMMAND_HELP = {
+  init: {
+    usage: "haechi init [--config haechi.config.json] [--force]",
+    summary: "Create a local key, sample config, and audit path.",
+    detail: "Writes haechi.config.json and .haechi/dev.keys.json (0600). --force rotates the key (prior keys are retired, not deleted) and overwrites the config."
+  },
+  protect: {
+    usage: "haechi protect <input.json> [--config haechi.config.json]",
+    summary: "Inspect and protect a JSON payload, printing the result.",
+    detail: "Reads input.json, applies the policy, and prints the protected payload, audit id, and warnings. Exit 3 if the payload is blocked."
+  },
+  report: {
+    usage: "haechi report [--audit .haechi/audit.jsonl]",
+    summary: "Summarize audit events without raw payloads."
+  },
+  "audit-verify": {
+    usage: "haechi audit-verify [--audit .haechi/audit.jsonl] [--config haechi.config.json]",
+    summary: "Verify the audit hash chain; print validity, record count, and head hash.",
+    detail: "Exit 4 on a broken chain. The head hash is the value to anchor externally against tail truncation."
+  },
+  status: {
+    usage: "haechi status [--config haechi.config.json]",
+    summary: "Show what is and is not protected under the current config.",
+    detail: "Prints effective policy mode, response/streaming protection, target, token vault governance, key file permissions, audit chain status, and a consolidated warnings list."
+  },
+  proxy: {
+    usage: `haechi proxy [--config haechi.config.json] [--host 127.0.0.1] [--port ${DEFAULT_PROXY_PORT}] [--allow-remote-bind]`,
+    summary: "Run the local HTTP JSON proxy in front of an upstream LLM.",
+    detail: "Binds loopback by default; --allow-remote-bind is required (and must be a CLI flag, not config) to bind non-loopback hosts. There is no client auth yet — see 'haechi config'."
+  },
+  "policy-sign": {
+    usage: "haechi policy-sign <policy.json> [--config haechi.config.json] [--out policy.bundle.json]",
+    summary: "Sign a policy file into a verifiable bundle."
+  },
+  "policy-verify": {
+    usage: "haechi policy-verify <policy.bundle.json> [--config haechi.config.json]",
+    summary: "Verify a signed policy bundle against the configured key."
+  },
+  "token-reveal": {
+    usage: "haechi token-reveal <token> [--config haechi.config.json] [--allow-dev-reveal]",
+    summary: "Reveal a tokenized value (governed by tokenVault.revealPolicy; audited).",
+    detail: "Fails unless revealPolicy is local-dev or --allow-dev-reveal is passed."
+  },
+  "token-purge": {
+    usage: "haechi token-purge <token> [--config haechi.config.json]\n  haechi token-purge --expired [--config haechi.config.json]",
+    summary: "Purge a specific token, or all expired tokens with --expired."
+  },
+  "token-export": {
+    usage: "haechi token-export [--config haechi.config.json] [--type email]",
+    summary: "Export token metadata (never plaintext), optionally filtered by type."
+  },
+  "plugin-validate": {
+    usage: "haechi plugin-validate <plugin-manifest.json>",
+    summary: "Validate a plugin manifest (manifest-only; dynamic runtime is rejected)."
+  },
+  "mcp-stdio": {
+    usage: "haechi mcp-stdio [--config haechi.config.json]",
+    summary: "Filter MCP JSON-RPC traffic on stdin/stdout (one direction)."
+  },
+  "mcp-wrap": {
+    usage: "haechi mcp-wrap [--config haechi.config.json] -- <command> [args...]",
+    summary: "Wrap an MCP server with bidirectional stdio protection.",
+    detail: "Spawns <command>, applies the method allowlist + params protection client→server, and result protection + injection heuristics server→client. Drop-in for MCP client configs."
+  },
+  auth: {
+    usage: "haechi auth add --type user|service|agent [--scope k:v ...] [--label k=v ...]\n  haechi auth list [--config haechi.config.json]\n  haechi auth revoke <id> [--config haechi.config.json]",
+    summary: "Manage built-in bearer tokens (separate store, hashed).",
+    detail: "Tokens are stored hashed in auth.store (default .haechi/auth.json, 0600). `add` prints the plaintext token once — it cannot be recovered. `list` never reveals tokens; `revoke` disables one by id."
+  },
+  config: {
+    usage: "haechi config",
+    summary: "Print the configuration guide (keys, defaults, common setups)."
+  }
+};
+
+function printHelp(topic) {
+  if (topic && COMMAND_HELP[topic]) {
+    const entry = COMMAND_HELP[topic];
+    console.log(`haechi ${topic} — ${entry.summary}\n\nUsage:\n  ${entry.usage}${entry.detail ? `\n\n${entry.detail}` : ""}`);
+    return;
+  }
+
+  const order = [
+    "init", "protect", "report", "status", "audit-verify", "proxy",
+    "policy-sign", "policy-verify",
+    "token-reveal", "token-purge", "token-export",
+    "plugin-validate", "mcp-stdio", "mcp-wrap", "auth", "config"
+  ];
+  const lines = order.map((name) => `  ${name.padEnd(16)}${COMMAND_HELP[name].summary}`);
+  console.log(`Haechi — self-hosted AI context enforcement (developer preview)
 
 Usage:
-  haechi init [--config haechi.config.json] [--force]
-  haechi protect <input.json> [--config haechi.config.json]
-  haechi report [--audit .haechi/audit.jsonl]
-  haechi audit-verify [--audit .haechi/audit.jsonl] [--config haechi.config.json]
-  haechi status [--config haechi.config.json]
-  haechi proxy [--config haechi.config.json] [--host 127.0.0.1] [--port ${DEFAULT_PROXY_PORT}] [--allow-remote-bind]
-  haechi policy-sign <policy.json> [--config haechi.config.json] [--out policy.bundle.json]
-  haechi policy-verify <policy.bundle.json> [--config haechi.config.json]
-  haechi token-reveal <token> [--config haechi.config.json] [--allow-dev-reveal]
-  haechi token-purge <token> [--config haechi.config.json]
-  haechi token-purge --expired [--config haechi.config.json]
-  haechi token-export [--config haechi.config.json] [--type email]
-  haechi plugin-validate <plugin-manifest.json>
-  haechi mcp-stdio [--config haechi.config.json]
-  haechi mcp-wrap [--config haechi.config.json] -- <command> [args...]
-
-The default policy mode is dry-run. Change policy.mode to enforce to mutate or block payloads.
+  haechi <command> [options]
+  haechi help <command>     show usage for one command
+
+Commands:
+${lines.join("\n")}
+
+Getting started:
+  haechi init               write config + local key
+  haechi status             see what is protected
+  haechi config             configuration guide
+
+The default policy mode is dry-run (detect + audit only). Set policy.mode to
+"enforce" to transform or block. Run 'haechi config' for all settings.
 `);
 }
+
+function printConfigGuide() {
+  console.log(`Haechi configuration guide
+
+Config file: haechi.config.json (override with --config <path>); template at
+haechi.config.example.json. All values are validated fail-closed — unknown or
+malformed settings refuse to start. 'haechi status' prints the EFFECTIVE state.
+
+Enforcement
+  mode / policy.mode        dry-run | report-only | enforce   (default dry-run)
+                            dry-run/report-only detect + audit only.
+                            policy.mode overrides mode.
+
+Upstream + proxy
+  target.type               llm-http | openai-compatible | vllm-openai |
+                            ollama | llama-cpp                 (unknown = fail)
+  target.upstream           the only upstream the proxy forwards to
+  proxy.host / proxy.port   127.0.0.1 / ${DEFAULT_PROXY_PORT}
+                            non-loopback host needs --allow-remote-bind (CLI flag)
+
+Response + streaming
+  responseProtection.enabled  inspect upstream responses        (default false)
+  responseProtection.failureMode  fail-closed | allow           (default fail-closed)
+  streaming.requestMode     block | pass-through | inspect       (default block)
+                            inspect = stream-filter SSE/NDJSON responses
+  streaming.maxMatchBytes   cross-frame match window             (default 256)
+  limits.upstreamTimeoutMs  upstream timeout in ms              (default 120000)
+
+Detection policy
+  policy.presets            korean-pii, secrets-only, llm-redact,
+                            strict-block, mcp-basic, local-inference, local-only
+  policy.defaultAction      allow | redact | mask | tokenize | encrypt | block
+  policy.actions            per-type overrides; merges may strengthen, not weaken
+  filters.customRules       extra regex rules (ReDoS-screened)
+
+Tokenization (model sees token, caller sees plaintext)
+  tokenVault.revealPolicy   disabled | local-dev               (manual reveal gate)
+  tokenVault.deterministic  same value -> same token           (default false)
+  tokenVault.detokenizeResponses  restore request-issued tokens in the response
+                            (needs responseProtection.enabled)
+
+Privacy + MCP
+  privacy.profile           kr-pipa | eu-gdpr | us-general | null
+  mcp.allowedMethods        client-callable method allowlist
+
+Binding beyond loopback (0.0.0.0):
+  haechi proxy --host 0.0.0.0 --allow-remote-bind
+  There is NO client auth yet (planned 0.6). Use only behind network controls:
+  bind 0.0.0.0 in a container and map -p 127.0.0.1:${DEFAULT_PROXY_PORT}:${DEFAULT_PROXY_PORT}, or front
+  it with a firewall/VPN/authenticating reverse proxy.
+
+Full reference: docs/current/configuration.md
+`);
+}
+
+await main(command, argv);