@bothat-io/molenkopf 0.1.2

package/packages/core/src/providers/provider-catalog.ts

@@ -0,0 +1,186 @@
+import { validateProviderTarget } from "../security/target-policy.ts";
+
+export type ProviderKind = "api" | "local" | "cli";
+
+export type RuntimeProfileConfig = {
+  settingsRef?: string;
+  configRef?: string;
+  permissionMode?: string;
+  allowedTools?: string[];
+  disallowedTools?: string[];
+  addDirs?: string[];
+  sandbox?: string;
+  approval?: string;
+  summary?: string[];
+};
+
+export type RuntimeProfileDiagnostics = {
+  settingsSource?: string;
+  configSource?: string;
+  permissionMode?: string;
+  sandbox?: string;
+  approval?: string;
+  allowedToolCount: number;
+  deniedToolCount: number;
+  addDirCount: number;
+  outerHarness: "unknown";
+  remediation: string;
+};
+
+export type RuntimeProfileView = { summary: string[]; diagnostics?: RuntimeProfileDiagnostics };
+
+export type ProviderConfig = {
+  id: string;
+  name: string;
+  kind: ProviderKind;
+  target: string;
+  credentialEnv?: string;
+  credentialRef?: string;
+  credentialValue?: string;
+  authScheme?: "bearer" | "x-api-key" | "none";
+  runtime?: "claude" | "codex";
+  cliCommand?: string;
+  cliArgs?: string[];
+  cliInputMode?: "stdin" | "argument";
+  cliTimeoutMs?: number;
+  runtimeAuthDir?: string;
+  authRef?: string;
+  runtimeProfile?: RuntimeProfileConfig;
+  protocol?: "openai-responses" | "anthropic-messages" | "openai-chat" | "ollama-tags";
+  allowDistribution?: boolean;
+  allowClientCredentialForwarding?: boolean;
+  enabled?: boolean;
+};
+
+export type ProviderView = Omit<ProviderConfig, "credentialValue" | "runtimeAuthDir" | "authRef" | "runtimeProfile" | "cliArgs"> & {
+  active: boolean;
+  credentialConfigured: boolean;
+  runtimeAuthConfigured: boolean;
+  runtimeProfile?: RuntimeProfileView;
+  selectable: boolean;
+};
+
+export type ProviderCatalogOptions = { includeBuiltIns?: boolean; includeEnvProviders?: boolean };
+
+export function buildProviderCatalog(target: string, extra: ProviderConfig[] = [], env: Record<string, string | undefined> = process.env, options: ProviderCatalogOptions = {}): ProviderConfig[] {
+  const includeBuiltIns = options.includeBuiltIns !== false;
+  const includeEnvProviders = options.includeEnvProviders !== false;
+  const providers: ProviderConfig[] = [
+    ...(includeBuiltIns ? builtInProviders(target, env) : []),
+    ...(includeEnvProviders ? configuredEnvProviders(env) : []),
+    ...extra.map((item) => ({ ...item, enabled: item.enabled !== false }))
+  ];
+  return uniqueById(providers);
+}
+
+export function viewProviders(providers: ProviderConfig[], activeProviderId: string, env: Record<string, string | undefined> = process.env): ProviderView[] {
+  return providers.map((provider) => {
+    const { credentialValue, runtimeAuthDir, authRef, runtimeProfile, cliArgs, ...safeProvider } = provider;
+    return {
+      ...safeProvider,
+      active: provider.id === activeProviderId,
+      credentialConfigured: Boolean(credentialValue || (provider.credentialEnv && env[provider.credentialEnv])),
+      runtimeAuthConfigured: Boolean(runtimeAuthDir),
+      runtimeProfile: viewRuntimeProfile(runtimeProfile),
+      selectable: provider.enabled !== false
+    };
+  });
+}
+
+export function viewRuntimeProfile(profile: RuntimeProfileConfig | undefined): RuntimeProfileView | undefined {
+  const summary = profile?.summary?.map((item) => item.slice(0, 80)).filter(Boolean) ?? [];
+  if (!summary.length) return undefined;
+  return { summary, diagnostics: runtimeDiagnostics(profile) };
+}
+
+function runtimeDiagnostics(profile: RuntimeProfileConfig | undefined): RuntimeProfileDiagnostics | undefined {
+  if (!profile) return undefined;
+  return {
+    settingsSource: profile.settingsRef,
+    configSource: profile.configRef,
+    permissionMode: profile.permissionMode,
+    sandbox: profile.sandbox,
+    approval: profile.approval,
+    allowedToolCount: profile.allowedTools?.length ?? 0,
+    deniedToolCount: profile.disallowedTools?.length ?? 0,
+    addDirCount: profile.addDirs?.length ?? 0,
+    outerHarness: "unknown",
+    remediation: "If the host client still asks, approve that prompt or configure this project in .claude/settings.json; Molenkopf cannot bypass a separate Claude/Codex harness."
+  };
+}
+
+function builtInProviders(target: string, env: Record<string, string | undefined>): ProviderConfig[] {
+  const openaiTarget = safeTarget(env.OPENAI_BASE_URL, "https://api.openai.com/v1");
+  const anthropicTarget = safeTarget(env.ANTHROPIC_BASE_URL, "https://api.anthropic.com/v1");
+  const ollamaTarget = safeTarget(env.OLLAMA_BASE_URL, "http://127.0.0.1:11434/v1", true);
+  const lmstudioTarget = safeTarget(env.LMSTUDIO_BASE_URL, "http://127.0.0.1:1234/v1", true);
+  return [
+    { id: "default", name: "Default upstream", kind: "api", target, authScheme: "none", enabled: true },
+    { id: "openai-env", name: "OpenAI env profile", kind: "api", target: openaiTarget.value, credentialEnv: "OPENAI_API_KEY", credentialRef: "env:OPENAI_API_KEY", authScheme: "bearer", protocol: "openai-responses", enabled: openaiTarget.safe && Boolean(env.OPENAI_BASE_URL || env.OPENAI_API_KEY) },
+    { id: "anthropic-env", name: "Anthropic env profile", kind: "api", target: anthropicTarget.value, credentialEnv: "ANTHROPIC_API_KEY", credentialRef: "env:ANTHROPIC_API_KEY", authScheme: "x-api-key", protocol: "anthropic-messages", enabled: anthropicTarget.safe && Boolean(env.ANTHROPIC_BASE_URL || env.ANTHROPIC_API_KEY) },
+    { id: "ollama-local", name: "Local Ollama compatible", kind: "local", target: ollamaTarget.value, authScheme: "none", protocol: "ollama-tags", enabled: ollamaTarget.safe && Boolean(env.OLLAMA_BASE_URL) },
+    { id: "lmstudio-local", name: "Local LM Studio compatible", kind: "local", target: lmstudioTarget.value, authScheme: "none", protocol: "openai-chat", enabled: lmstudioTarget.safe && Boolean(env.LMSTUDIO_BASE_URL) }
+  ];
+}
+
+function configuredEnvProviders(env: Record<string, string | undefined>): ProviderConfig[] {
+  return splitCsv(env.MOLENKOPF_PROVIDER_IDS).map((id) => providerFromEnv(id, env)).filter((item): item is ProviderConfig => Boolean(item));
+}
+
+function providerFromEnv(id: string, env: Record<string, string | undefined>): ProviderConfig | undefined {
+  if (!/^[a-z0-9][a-z0-9._:-]{0,63}$/i.test(id)) return undefined;
+  const prefix = `MOLENKOPF_PROVIDER_${id.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_`;
+  const kind = env[`${prefix}KIND`] === "local" ? "local" : "api";
+  const checkedTarget = safeTarget(env[`${prefix}TARGET`], "", kind === "local");
+  const target = checkedTarget.value;
+  if (!target || !checkedTarget.safe) return undefined;
+  const credentialEnv = env[`${prefix}CREDENTIAL_ENV`]?.trim();
+  return {
+    id,
+    name: env[`${prefix}NAME`]?.trim() || id,
+    kind,
+    target,
+    credentialEnv: credentialEnv || undefined,
+    credentialRef: credentialEnv ? `env:${credentialEnv}` : "none",
+    authScheme: authScheme(env[`${prefix}AUTH`], target, credentialEnv),
+    protocol: protocol(env[`${prefix}PROTOCOL`], kind, target),
+    enabled: env[`${prefix}ENABLED`]?.toLowerCase() !== "false"
+  };
+}
+
+function safeTarget(value: string | undefined, fallback = "", allowPrivate = false): { value: string; safe: boolean } {
+  const candidate = value?.trim() || fallback;
+  if (!candidate) return { value: "", safe: false };
+  try {
+    validateProviderTarget(candidate, { allowPrivate });
+    return { value: candidate, safe: true };
+  } catch {
+    return { value: fallback, safe: false };
+  }
+}
+
+function authScheme(value: string | undefined, target: string, credentialEnv?: string): ProviderConfig["authScheme"] {
+  if (value === "bearer" || value === "x-api-key" || value === "none") return value;
+  if (!credentialEnv) return "none";
+  return target.includes("anthropic") ? "x-api-key" : "bearer";
+}
+
+function protocol(value: string | undefined, kind: ProviderKind, target: string): ProviderConfig["protocol"] {
+  if (value === "openai-responses" || value === "anthropic-messages" || value === "openai-chat" || value === "ollama-tags") return value;
+  if (kind === "local" && target.includes("11434")) return "ollama-tags";
+  if (kind === "local") return "openai-chat";
+  return target.includes("anthropic") ? "anthropic-messages" : "openai-responses";
+}
+
+function splitCsv(value: string | undefined): string[] {
+  return (value ?? "").split(",").map((item) => item.trim()).filter(Boolean);
+}
+
+function uniqueById(providers: ProviderConfig[]): ProviderConfig[] {
+  const seen = new Set<string>();
+  return providers.filter((provider) => {
+    if (seen.has(provider.id)) return false;
+    seen.add(provider.id);
+    return true;
+  });
+}

package/packages/core/src/routing/distribution.ts

@@ -0,0 +1,31 @@
+// Weighted token distribution across providers. The provider currently furthest
+// below its target share of total tokens is chosen next, so equal weights give a
+// fair split and unequal weights (e.g. 80/20) hold the configured ratio over time.
+
+export type ProviderShare = { id: string; weight: number; usedTokens: number };
+
+export function chooseByDistribution(shares: ProviderShare[]): string | undefined {
+  const enabled = shares.filter((share) => share.weight > 0);
+  if (!enabled.length) return undefined;
+  const totalWeight = enabled.reduce((sum, share) => sum + share.weight, 0);
+  const totalUsed = enabled.reduce((sum, share) => sum + Math.max(0, share.usedTokens), 0);
+  let bestId: string | undefined;
+  let bestDeficit = -Infinity;
+  for (const share of enabled) {
+    const target = (share.weight / totalWeight) * (totalUsed + 1);
+    const deficit = target - Math.max(0, share.usedTokens);
+    if (deficit > bestDeficit) {
+      bestDeficit = deficit;
+      bestId = share.id;
+    }
+  }
+  return bestId;
+}
+
+// Normalizes provider weights into display shares (percent of total weight).
+export function weightShares(shares: { id: string; weight: number }[]): Record<string, number> {
+  const total = shares.reduce((sum, share) => sum + Math.max(0, share.weight), 0);
+  const out: Record<string, number> = {};
+  for (const share of shares) out[share.id] = total > 0 ? Math.round((Math.max(0, share.weight) / total) * 1000) / 10 : 0;
+  return out;
+}

package/packages/core/src/security/secret-redactor.ts

@@ -0,0 +1,139 @@
+import { shortHash } from "../utils/hash.ts";
+import { replaceJsonStrings, scanJsonStringValues, type JsonStringReplacement } from "../pipeline/json-string-spans.ts";
+
+export type Redaction = { kind: string; hash: string };
+export type RedactionResult = { text: string; redactions: Redaction[] };
+
+type Rule = { kind: string; pattern: RegExp; value?: (match: RegExpExecArray) => string };
+
+const rules: Rule[] = [
+  { kind: "private_key", pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g },
+  { kind: "authorization_bearer", pattern: /(Authorization:\s*Bearer\s+)([^\s\r\n]+)/gi, value: (m) => m[2] },
+  { kind: "authorization_basic", pattern: /(Authorization:\s*Basic\s+)([A-Za-z0-9+/=]+)/gi, value: (m) => m[2] },
+  { kind: "cookie", pattern: /(Cookie:\s*)([^\r\n]+)/gi, value: (m) => m[2] },
+  { kind: "anthropic_api_key", pattern: /\bsk-ant-[A-Za-z0-9_-]{32,}\b/g },
+  { kind: "openai_api_key", pattern: /\bsk-(?:proj-|)[A-Za-z0-9_-]{32,}\b/g },
+  { kind: "github_token", pattern: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9_]{30,}\b/g },
+  { kind: "molenkopf_api_key", pattern: /(?<![A-Za-z0-9_-])mk_[A-Za-z0-9_-]{24,}(?![A-Za-z0-9_-])/g },
+  { kind: "gitlab_token", pattern: /\bglpat-[A-Za-z0-9_-]{20,}\b/g },
+  { kind: "npm_token", pattern: /\bnpm_[A-Za-z0-9]{32,}\b/g },
+  { kind: "slack_token", pattern: /\bxox[baprs]-[A-Za-z0-9-]{20,}\b/g },
+  { kind: "stripe_secret", pattern: /\b(?:sk|rk)_(?:live|test)_[A-Za-z0-9]{16,}\b/g },
+  { kind: "google_api_key", pattern: /\bAIza[0-9A-Za-z_-]{35}\b/g },
+  { kind: "aws_access_key_id", pattern: /\bAKIA[0-9A-Z]{16}\b/g },
+  { kind: "jwt", pattern: /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g },
+  { kind: "db_url", pattern: /\b(?:postgres(?:ql)?|mysql|mariadb|mongodb(?:\+srv)?|redis):\/\/[^:\s/@]+:[^@\s]+@[^\s"'<>]+/gi },
+  { kind: "basic_auth_url", pattern: /\b[a-z][a-z0-9+.-]*:\/\/[^:\s/@]+:[^@\s]+@[^\s"'<>]+/gi },
+  { kind: "sentry_dsn", pattern: /\bhttps:\/\/[A-Za-z0-9]+@[^/\s"'<>]*sentry\.io\/[0-9A-Za-z_-]+/gi },
+  { kind: "account_key", pattern: /\b(AccountKey=)(?!\[REDACTED_SECRET:)([^;\s]+)/gi, value: (m) => m[2] },
+  { kind: "sensitive_assignment", pattern: /(?<!REDACTED_SECRET:)\b((?:access[_-]?token|refresh[_-]?token|client[_-]?secret|session[_-]?token|auth[_-]?token|db[_-]?url)\s*[:=]\s*)(?!\[REDACTED_SECRET:)([^\s&"'`,;}\\\]]+)/gi, value: (m) => m[2] },
+  { kind: "password", pattern: /\b(password=)(?!\[REDACTED_SECRET:)([^\s&"'`,;}\\\]]+)/gi, value: (m) => m[2] },
+  { kind: "token", pattern: /\b(token=)(?!\[REDACTED_SECRET:)([^\s&"'`,;}\\\]]+)/gi, value: (m) => m[2] },
+  { kind: "secret", pattern: /\b(secret=)(?!\[REDACTED_SECRET:)([^\s&"'`,;}\\\]]+)/gi, value: (m) => m[2] },
+  { kind: "api_key", pattern: /\b(api_key=)(?!\[REDACTED_SECRET:)([^\s&"'`,;}\\\]]+)/gi, value: (m) => m[2] },
+  { kind: "env_secret", pattern: /(^|[\s{[,;])((?!REDACTED_SECRET\b)[A-Z][A-Z0-9_]*(?:PASSWORD|PASSWD|PWD|TOKEN|SECRET|API_KEY|PRIVATE_KEY|CREDENTIAL)[A-Z0-9_]*\s*[:=]\s*)(?!\[REDACTED_SECRET:)([^\s&"'`,;}\\\]]+)/g, value: (m) => m[3] }
+];
+const sensitiveJsonKeys = /(?:^|[_-])(?:password|passwd|pwd|token|authorization|auth|cookie|secret|api[_-]?key|credential|private[_-]?key)(?:$|[_-])/i;
+
+export function redactSecrets(input: string): RedactionResult {
+  const redactions: Redaction[] = [];
+  let text = redactJsonKeys(input, redactions) ?? input;
+  for (const rule of rules) {
+    text = text.replace(rule.pattern, (...args) => {
+      const match = args[args.length - 3] as string;
+      const exec = args.slice(0, -2) as unknown as RegExpExecArray;
+      const secret = rule.value ? rule.value(exec) : match;
+      const marker = redactionMarker(rule.kind, secret, redactions);
+      if (rule.kind === "env_secret") return `${exec[1]}${exec[2]}${marker}`;
+      if (rule.value && exec[1]) return `${exec[1]}${marker}`;
+      return marker;
+    });
+  }
+  return { text, redactions };
+}
+
+function redactJsonKeys(input: string, redactions: Redaction[]): string | undefined {
+  if (!/^\s*[\[{]/.test(input)) return undefined;
+  if (exceedsSafeJsonDepth(input)) return containsSensitiveJsonKey(input) ? redactionMarker("json_too_deep", input, redactions) : undefined;
+  const structural = redactSensitiveJsonValues(input, redactions);
+  const base = structural ?? input;
+  const spans = scanJsonStringValues(base);
+  if (!spans) return structural;
+  const replacements: JsonStringReplacement[] = [];
+  for (const span of spans) {
+    if (span.key && isSensitiveJsonKey(span.key)) {
+      if (isRedactionMarker(span.value)) continue;
+      replacements.push({ start: span.start, end: span.end, value: redactionMarker(`json_${safeKind(span.key)}`, span.value, redactions) });
+      continue;
+    }
+    const nested = redactJsonKeys(span.value, redactions);
+    if (nested && nested !== span.value) replacements.push({ start: span.start, end: span.end, value: nested });
+  }
+  return replacements.length ? replaceJsonStrings(base, replacements) : structural;
+}
+
+function redactSensitiveJsonValues(input: string, redactions: Redaction[]): string | undefined {
+  let root: unknown;
+  try { root = JSON.parse(input) as unknown; } catch { return undefined; }
+  const stack: Array<{ value: unknown; key?: string; parent?: Record<string, unknown> | unknown[]; index?: string | number }> = [{ value: root }];
+  let changed = false;
+  while (stack.length) {
+    const item = stack.pop()!;
+    if (item.key && isSensitiveJsonKey(item.key) && typeof item.value !== "string") {
+      const marker = redactionMarker(`json_${safeKind(item.key)}`, JSON.stringify(item.value), redactions);
+      if (Array.isArray(item.parent) && typeof item.index === "number") item.parent[item.index] = marker;
+      else if (item.parent && typeof item.index === "string") item.parent[item.index] = marker;
+      changed = true;
+      continue;
+    }
+    if (!item.value || typeof item.value !== "object") continue;
+    if (Array.isArray(item.value)) {
+      for (let i = 0; i < item.value.length; i++) stack.push({ value: item.value[i], parent: item.value, index: i });
+    } else {
+      const object = item.value as Record<string, unknown>;
+      for (const [key, value] of Object.entries(object)) stack.push({ value, key, parent: object, index: key });
+    }
+  }
+  return changed ? JSON.stringify(root) : undefined;
+}
+
+function redactionMarker(kind: string, secret: string, redactions: Redaction[]): string {
+  const hash = shortHash(secret);
+  redactions.push({ kind, hash });
+  return `[REDACTED_SECRET:${kind}:sha256:${hash}]`;
+}
+
+function safeKind(key: string): string {
+  return key.toLowerCase().replace(/[^a-z0-9]+/g, "_");
+}
+
+function isSensitiveJsonKey(key: string): boolean {
+  const normalized = key.replace(/([a-z0-9])([A-Z])/g, "$1_$2");
+  return sensitiveJsonKeys.test(normalized);
+}
+
+function containsSensitiveJsonKey(input: string): boolean {
+  return /"(?:[^"\\]|\\.)*(?:password|passwd|pwd|token|authorization|auth|cookie|secret|api[_-]?key|credential|private[_-]?key)(?:[^"\\]|\\.)*"\s*:/i.test(input);
+}
+
+function isRedactionMarker(value: string): boolean {
+  return /^\[REDACTED_SECRET:[a-z0-9_-]+:sha256:[a-f0-9]{12}\]$/.test(value);
+}
+
+function exceedsSafeJsonDepth(text: string): boolean {
+  let depth = 0, inString = false;
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] === '"' && !escaped(text, i)) inString = !inString;
+    if (inString) continue;
+    if (text[i] === "{" || text[i] === "[") depth++;
+    else if (text[i] === "}" || text[i] === "]") depth--;
+    if (depth > 1000) return true;
+  }
+  return false;
+}
+
+function escaped(text: string, quoteIndex: number): boolean {
+  let slashes = 0;
+  for (let i = quoteIndex - 1; i >= 0 && text[i] === "\\"; i--) slashes++;
+  return slashes % 2 === 1;
+}

package/packages/core/src/security/target-policy.ts

@@ -0,0 +1,61 @@
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+
+export type TargetPolicy = { allowPrivate?: boolean; allowSearch?: boolean; path?: string };
+export type ConnectTarget = { url: URL; address: string; family: 4 | 6 };
+
+export function validateProviderTarget(value: string, policy: TargetPolicy = {}): string {
+  const url = parseHttpTarget(value, policy.path ?? "target");
+  if (url.username || url.password || (!policy.allowSearch && url.search)) throw new Error(`unsafe URL: ${policy.path ?? "target"}`);
+  if (!policy.allowPrivate && isPrivateHost(url.hostname)) throw new Error(`unsafe private URL: ${policy.path ?? "target"}`);
+  return value;
+}
+
+export async function resolveConnectTarget(value: string, policy: TargetPolicy = {}): Promise<ConnectTarget> {
+  const url = parseHttpTarget(value, policy.path ?? "target");
+  if (url.username || url.password || (!policy.allowSearch && url.search)) throw new Error(`unsafe URL: ${policy.path ?? "target"}`);
+  const resolved = await lookup(url.hostname, { all: true, verbatim: true });
+  if (!policy.allowPrivate && resolved.some((item) => isPrivateHost(item.address))) throw new Error(`unsafe private URL: ${policy.path ?? "target"}`);
+  const first = resolved[0];
+  if (!first) throw new Error(`invalid URL: ${policy.path ?? "target"}`);
+  return { url, address: first.address, family: first.family === 6 ? 6 : 4 };
+}
+
+export function isPrivateHost(hostname: string): boolean {
+  const host = hostname.toLowerCase().replace(/^\[|\]$/g, "");
+  if (host === "localhost" || host === "metadata.google.internal") return true;
+  const ip = isIP(host);
+  if (ip === 6) return isPrivateIpv6(host);
+  if (ip === 4) return isPrivateIpv4(host);
+  return false;
+}
+
+function parseHttpTarget(value: string, path: string): URL {
+  let url: URL;
+  try { url = new URL(value); } catch { throw new Error(`invalid URL: ${path}`); }
+  if (url.protocol !== "http:" && url.protocol !== "https:") throw new Error(`invalid URL protocol: ${path}`);
+  return url;
+}
+
+function isPrivateIpv4(host: string): boolean {
+  const parts = host.split(".").map(Number);
+  if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) return false;
+  const [a, b] = parts;
+  return a === 10 || a === 127 || a === 0 || a >= 224 || (a === 100 && b >= 64 && b <= 127)
+    || (a === 169 && b === 254) || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168);
+}
+
+function isPrivateIpv6(host: string): boolean {
+  if (host === "::" || host === "::1" || host === "0:0:0:0:0:0:0:1") return true;
+  if (host.startsWith("fe80:") || host.startsWith("fc") || host.startsWith("fd")) return true;
+  if (host.startsWith("::ffff:")) return isPrivateIpv4(ipv4Mapped(host));
+  return false;
+}
+
+function ipv4Mapped(host: string): string {
+  const tail = host.slice("::ffff:".length);
+  if (tail.includes(".")) return tail;
+  const groups = tail.split(":").map((part) => Number.parseInt(part || "0", 16));
+  const number = ((groups[0] ?? 0) << 16) + (groups[1] ?? 0);
+  return [(number >>> 24) & 255, (number >>> 16) & 255, (number >>> 8) & 255, number & 255].join(".");
+}

package/packages/core/src/storage/local-paths.ts

@@ -0,0 +1,6 @@
+export const DEFAULT_DATA_DIR = ".molenkopf";
+
+export function defaultDataDir(): string {
+  if (process.env.MOLENKOPF_DATA_DIR) return process.env.MOLENKOPF_DATA_DIR;
+  return DEFAULT_DATA_DIR;
+}

package/packages/core/src/storage/private-state.ts

@@ -0,0 +1,30 @@
+import { chmod, mkdir, writeFile } from "node:fs/promises";
+import { chmodSync, mkdirSync } from "node:fs";
+
+export const PRIVATE_DIR_MODE = 0o700;
+export const PRIVATE_FILE_MODE = 0o600;
+
+export async function ensurePrivateDir(path: string): Promise<void> {
+  await mkdir(path, process.platform === "win32" ? { recursive: true } : { recursive: true, mode: PRIVATE_DIR_MODE });
+  await chmodPrivate(path, PRIVATE_DIR_MODE);
+}
+
+export function ensurePrivateDirSync(path: string): void {
+  mkdirSync(path, process.platform === "win32" ? { recursive: true } : { recursive: true, mode: PRIVATE_DIR_MODE });
+  chmodPrivateSync(path, PRIVATE_DIR_MODE);
+}
+
+export async function writePrivateFile(path: string, data: string | Buffer): Promise<void> {
+  await writeFile(path, data, process.platform === "win32" ? undefined : { mode: PRIVATE_FILE_MODE });
+  await chmodPrivate(path, PRIVATE_FILE_MODE);
+}
+
+export async function chmodPrivate(path: string, mode: number): Promise<void> {
+  if (process.platform === "win32") return;
+  try { await chmod(path, mode); } catch { /* best effort for non-POSIX filesystems */ }
+}
+
+export function chmodPrivateSync(path: string, mode: number): void {
+  if (process.platform === "win32") return;
+  try { chmodSync(path, mode); } catch { /* best effort for non-POSIX filesystems */ }
+}

package/packages/core/src/storage/purge-dir.ts

@@ -0,0 +1,10 @@
+import { rm } from "node:fs/promises";
+import { isAbsolute, relative, resolve } from "node:path";
+
+export async function purgeChildDir(root: string, child: string): Promise<void> {
+  const base = resolve(root);
+  const target = resolve(base, child);
+  const rel = relative(base, target);
+  if (!rel || rel.startsWith("..") || isAbsolute(rel)) throw new Error("unsafe_purge_path");
+  await rm(target, { recursive: true, force: true });
+}

package/packages/core/src/store/retrieval-store.ts

@@ -0,0 +1,114 @@
+import { readFile, rename, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { defaultDataDir } from "../storage/local-paths.ts";
+import { chmodPrivate, ensurePrivateDir, PRIVATE_FILE_MODE, writePrivateFile } from "../storage/private-state.ts";
+import { purgeChildDir } from "../storage/purge-dir.ts";
+import { sha256 } from "../utils/hash.ts";
+import { byteLength } from "../utils/text.ts";
+
+export type RetrievalMeta = {
+  hash: string;
+  createdAt: string;
+  contentKind: string;
+  originalBytes: number;
+  compressedBytes: number;
+  compressorName: string;
+  redacted: boolean;
+  requestId?: string;
+};
+
+const EXCERPT_CHARS = 320;
+const RETRIEVAL_PREFIX = "molenkopf://sha256/";
+
+export class RetrievalStore {
+  private root: string;
+
+  constructor(root = defaultDataDir()) {
+    this.root = root;
+  }
+
+  async save(text: string, meta: Omit<RetrievalMeta, "hash" | "createdAt" | "originalBytes">): Promise<{ id: string; meta: RetrievalMeta }> {
+    const hash = sha256(text);
+    const full: RetrievalMeta = { hash, createdAt: new Date().toISOString(), originalBytes: byteLength(text), ...meta };
+    const dir = this.dirFor(hash);
+    await ensurePrivateDir(dir);
+    await atomicPairWrite(dir, hash, boundedExcerpt(text), JSON.stringify(full, null, 2));
+    return { id: `${RETRIEVAL_PREFIX}${hash}`, meta: full };
+  }
+
+  idFor(text: string): string {
+    return `${RETRIEVAL_PREFIX}${sha256(text)}`;
+  }
+
+  async retrieve(id: string): Promise<string> {
+    const hash = this.hashFromId(id);
+    await this.checkedMetadata(hash);
+    return readFile(join(this.dirFor(hash), `${hash}.txt`), "utf8");
+  }
+
+  async metadata(id: string): Promise<RetrievalMeta> {
+    const hash = this.hashFromId(id);
+    return this.checkedMetadata(hash);
+  }
+
+  async purgeAll(): Promise<void> {
+    await purgeChildDir(this.root, "store");
+  }
+
+  private hashFromId(id: string): string {
+    if (!id.startsWith(RETRIEVAL_PREFIX)) throw new Error("invalid retrieval id");
+    const hash = id.slice(RETRIEVAL_PREFIX.length).toLowerCase();
+    if (!/^[a-f0-9]{64}$/.test(hash)) throw new Error("invalid retrieval id");
+    return hash;
+  }
+
+  private dirFor(hash: string): string {
+    return join(this.root, "store", "sha256", hash.slice(0, 2), hash.slice(2, 4));
+  }
+
+  private async checkedMetadata(hash: string): Promise<RetrievalMeta> {
+    const meta = JSON.parse(await readFile(join(this.dirFor(hash), `${hash}.json`), "utf8")) as RetrievalMeta;
+    if (!isRetrievalMeta(meta) || meta.hash !== hash) throw new Error("invalid retrieval metadata");
+    return meta;
+  }
+}
+
+async function atomicPairWrite(dir: string, hash: string, text: string, json: string): Promise<void> {
+  const suffix = `${process.pid}-${Date.now()}`;
+  const textTmp = join(dir, `${hash}.${suffix}.txt.tmp`);
+  const jsonTmp = join(dir, `${hash}.${suffix}.json.tmp`);
+  const textPath = join(dir, `${hash}.txt`);
+  const jsonPath = join(dir, `${hash}.json`);
+  let textFinalized = false;
+  let jsonFinalized = false;
+  try {
+    await writePrivateFile(textTmp, text);
+    await writePrivateFile(jsonTmp, json);
+    await rename(textTmp, textPath);
+    textFinalized = true;
+    await chmodPrivate(textPath, PRIVATE_FILE_MODE);
+    await rename(jsonTmp, jsonPath);
+    jsonFinalized = true;
+    await chmodPrivate(jsonPath, PRIVATE_FILE_MODE);
+  } catch (err) {
+    await rm(textTmp, { force: true }).catch(() => {});
+    await rm(jsonTmp, { force: true }).catch(() => {});
+    if (textFinalized && !jsonFinalized) await rm(textPath, { force: true }).catch(() => {});
+    if (jsonFinalized && !textFinalized) await rm(jsonPath, { force: true }).catch(() => {});
+    throw err;
+  }
+}
+
+function isRetrievalMeta(value: unknown): value is RetrievalMeta {
+  if (!value || typeof value !== "object") return false;
+  const item = value as RetrievalMeta;
+  return /^[a-f0-9]{64}$/.test(item.hash) && typeof item.createdAt === "string" && typeof item.contentKind === "string"
+    && typeof item.originalBytes === "number" && typeof item.compressedBytes === "number"
+    && typeof item.compressorName === "string" && typeof item.redacted === "boolean"
+    && (item.requestId === undefined || typeof item.requestId === "string");
+}
+
+function boundedExcerpt(text: string): string {
+  const excerpt = text.length > EXCERPT_CHARS ? `${text.slice(0, EXCERPT_CHARS)}\n[TRUNCATED_CONTEXT:${text.length - EXCERPT_CHARS}_CHARS]` : text;
+  return `Context excerpt only. Full original content is not persisted.\n${excerpt}`;
+}

package/packages/core/src/utils/hash.ts

@@ -0,0 +1,9 @@
+import { createHash } from "node:crypto";
+
+export function sha256(text: string): string {
+  return createHash("sha256").update(text).digest("hex");
+}
+
+export function shortHash(text: string): string {
+  return sha256(text).slice(0, 12);
+}

package/packages/core/src/utils/text.ts

@@ -0,0 +1,18 @@
+export function byteLength(text: string): number {
+  return Buffer.byteLength(text, "utf8");
+}
+
+export function stripAnsi(text: string): string {
+  return text.replace(/\u001b\[[0-9;?]*[ -/]*[@-~]/g, "");
+}
+
+export function truncateValue(value: unknown, max = 240): unknown {
+  if (typeof value === "string" && value.length > max) {
+    return `${value.slice(0, max)}...[truncated ${value.length - max} chars]`;
+  }
+  if (Array.isArray(value)) return value.map((item) => truncateValue(item, max));
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, truncateValue(v, max)]));
+  }
+  return value;
+}

package/packages/core/src/utils/tokens.ts

@@ -0,0 +1,3 @@
+export function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 4);
+}