@bothat-io/molenkopf 0.1.2

package/packages/proxy/src/http/runtime-state.ts

@@ -0,0 +1,198 @@
+import { pluginCatalog } from "../../../core/src/plugins/plugin-catalog.ts";
+import { staticPluginPipeline } from "../../../core/src/plugins/static-pipeline.ts";
+import { buildProviderCatalog, type ProviderConfig } from "../../../core/src/providers/provider-catalog.ts";
+import type { AuditManifest } from "../../../core/src/manifest/audit-store.ts";
+import { createCommunicationGraph, type CommunicationGraph } from "./communication-graph.ts";
+import { createMemoryGraph, type MemoryGraph } from "../../../core/src/memory/memory-graph.ts";
+import type { AuthUser } from "./auth-state.ts";
+import type { IdentityStore } from "../../../core/src/identity/identity-store.ts";
+import type { UsageSnapshotStore } from "../../../core/src/identity/usage-snapshot.ts";
+import type { ResolvedAgent } from "../../../core/src/config/config-policies.ts";
+import { restoreRuntimeAuthProviders } from "./runtime-auth-registry.ts";
+import { loadRuntimeSettings } from "./runtime-settings.ts";
+import type { RuntimeAuthProofStore } from "./runtime-auth-proof.ts";
+import { requireSessionSecret } from "./session-secret.ts";
+
+export type { ResolvedAgent };
+export type RuntimeOptions = {
+  target: string;
+  dataDir?: string;
+  providers?: ProviderConfig[];
+  activeProviderId?: string;
+  configAgents?: ResolvedAgent[];
+  providerCatalogMode?: "auto" | "explicit";
+  configSource?: { kind: "env" | "file"; path?: string };
+};
+export const CONTROL_PLANE_LIMITS = {
+  agentDrafts: 25,
+  providerItems: 50,
+  graphNodes: 80,
+  graphEdges: 120,
+  requestBodyBytes: 8192,
+  idLength: 64,
+  labelLength: 80,
+  pluginIds: 20
+};
+
+export type AgentDraftMetadata = {
+  id: string;
+  label: string;
+  kind: "CI agent" | "Local agent" | "External agent";
+  providerId: string;
+  enabledPluginIds: string[];
+  tokenHash?: string;
+  tokenHashAlgorithm?: "sha256";
+  disabled?: boolean;
+  tokenLimit?: number;
+  status: "draft";
+  createdAt: string;
+  updatedAt: string;
+};
+export type AgentDraftView = Omit<AgentDraftMetadata, "tokenHash"> & { tokenHashPresent: boolean; tokenFingerprint?: string; usage: UsageTotals };
+
+export type UsagePeriodTotals = { requests: number; inputTokens: number; outputTokens: number; costEur?: number };
+export type UsageTotals = UsagePeriodTotals & { periods?: Record<string, UsagePeriodTotals> };
+export type RoutingMode = "manual" | "distribute";
+export type PluginLifecycle = { status: "disabled" | "booted" | "enabled" | "stopped" | "error"; hook?: string; error?: string };
+
+export type RuntimeStateResult<T> = { ok: true; value: T } | { ok: false; status: number; error: string; reason?: string };
+
+export type RuntimeState = {
+  requests: number;
+  compressedItems: number;
+  startedAt: string;
+  host: string;
+  port?: number;
+  dataDir?: string;
+  latest?: AuditManifest;
+  pluginEnabled: Record<string, boolean>;
+  pluginUpdatedAt: Record<string, string>;
+  pluginLifecycle: Record<string, PluginLifecycle>;
+  providers: ProviderConfig[];
+  activeProviderId: string;
+  providerSelectedAt: string;
+  routingMode: RoutingMode;
+  providerWeights: Record<string, number>;
+  pluginOrder: string[];
+  usageByProvider: Record<string, UsageTotals>;
+  usageByUser: Record<string, UsageTotals>;
+  usageByAgent: Record<string, UsageTotals>;
+  usageByKey: Record<string, UsageTotals>;
+  usageByTeam: Record<string, UsageTotals>;
+  consumerBudgets: Record<string, number>;
+  configAgents: ResolvedAgent[];
+  agentDrafts: AgentDraftMetadata[];
+  communicationGraph: CommunicationGraph;
+  memoryGraph: MemoryGraph;
+  sessionSecret: string;
+  authAttempts: Record<string, { count: number; resetAt: number }>;
+  runtimeAuthProofs: RuntimeAuthProofStore;
+  bootstrapSetup?: Promise<void>;
+  settingsLoadWarning?: string;
+  configSource: { kind: "env" | "file"; path?: string };
+  identity?: IdentityStore;
+  usageSnapshot?: UsageSnapshotStore;
+};
+
+export function createRuntimeState(options: RuntimeOptions, host: string): RuntimeState {
+  const now = new Date().toISOString();
+  const explicit = options.providerCatalogMode === "explicit";
+  if (explicit && !(options.providers ?? []).length) throw new Error("explicit provider config requires providers");
+  const restored: ReturnType<typeof restoreRuntimeAuthProviders> = explicit ? { providers: [] } : restoreRuntimeAuthProviders(options.dataDir);
+  const loadedSettings = loadRuntimeSettings(options.dataDir);
+  const settings = loadedSettings.settings;
+  const persistedProviders = explicit ? [] : settings.providers ?? [];
+  const providers = buildProviderCatalog(options.target, [...(options.providers ?? []), ...persistedProviders, ...restored.providers], process.env, { includeBuiltIns: !explicit, includeEnvProviders: !explicit });
+  const weights = Object.fromEntries(providers.map((provider) => [provider.id, 1]));
+  const requestedActive = options.activeProviderId ?? settings.activeProviderId ?? restored.activeProviderId ?? (explicit ? providers[0]?.id : "default") ?? "default";
+  return {
+    requests: 0,
+    compressedItems: 0,
+    startedAt: now,
+    host,
+    dataDir: options.dataDir,
+    pluginEnabled: normalizedPluginEnabled(settings.pluginEnabled),
+    pluginUpdatedAt: {},
+    pluginLifecycle: {},
+    providers,
+    activeProviderId: selectedProviderId(providers, requestedActive),
+    providerSelectedAt: now,
+    routingMode: cleanRoutingMode(settings.routingMode) ?? restored.routingMode ?? "manual",
+    providerWeights: { ...weights, ...(settings.providerWeights ?? {}) },
+    pluginOrder: settings.pluginOrder ?? [...staticPluginPipeline],
+    usageByProvider: {},
+    usageByUser: {},
+    usageByAgent: {},
+    usageByKey: {},
+    usageByTeam: {},
+    consumerBudgets: settings.consumerBudgets ?? {},
+    configAgents: options.configAgents ?? [],
+    agentDrafts: (settings.agentDrafts ?? []).filter((draft) => providers.some((provider) => provider.id === draft.providerId && provider.enabled !== false)),
+    communicationGraph: createCommunicationGraph(),
+    memoryGraph: createMemoryGraph(),
+    sessionSecret: requireSessionSecret(),
+    authAttempts: {},
+    runtimeAuthProofs: {},
+    settingsLoadWarning: loadedSettings.warning,
+    configSource: options.configSource ?? { kind: "env" }
+  };
+}
+
+export function activeProvider(state: RuntimeState): ProviderConfig {
+  return state.providers.find((provider) => provider.id === state.activeProviderId && provider.enabled !== false) ?? firstEnabledProvider(state.providers) ?? state.providers[0];
+}
+
+export function repairActiveProvider(state: RuntimeState): boolean {
+  const id = activeProvider(state)?.id ?? "default";
+  if (state.activeProviderId === id) return false;
+  state.activeProviderId = id;
+  state.providerSelectedAt = new Date().toISOString();
+  return true;
+}
+
+export function distributionEligible(provider: ProviderConfig): boolean {
+  if (provider.id === "default" || provider.enabled === false || provider.allowDistribution === false) return false;
+  return provider.kind !== "cli" || provider.allowDistribution === true || Boolean(provider.runtimeAuthDir);
+}
+
+export function isPluginEnabled(state: RuntimeState, id: string): boolean {
+  const plugin = pluginCatalog.find((item) => item.id === id);
+  return plugin ? state.pluginEnabled[id] ?? plugin.enabledByDefault : false;
+}
+
+export function enabledPluginIds(state: RuntimeState): string[] {
+  return pluginCatalog.filter((plugin) => isPluginEnabled(state, plugin.id)).map((plugin) => plugin.id);
+}
+
+export function emptyUsage(): UsageTotals {
+  return { requests: 0, inputTokens: 0, outputTokens: 0, costEur: 0 };
+}
+
+function normalizedPluginEnabled(settings: Record<string, boolean> | undefined): Record<string, boolean> {
+  const enabled: Record<string, boolean> = {};
+  for (const plugin of pluginCatalog) {
+    const configured = settings?.[plugin.id];
+    enabled[plugin.id] = plugin.canToggle && typeof configured === "boolean" ? configured : plugin.enabledByDefault;
+  }
+  return enabled;
+}
+
+function selectedProviderId(providers: ProviderConfig[], requested: string): string {
+  const enabled = providers.find((provider) => provider.id === requested && provider.enabled !== false);
+  return enabled?.id ?? firstEnabledProvider(providers)?.id ?? providers[0]?.id ?? "default";
+}
+
+function firstEnabledProvider(providers: ProviderConfig[]): ProviderConfig | undefined {
+  return providers.find((provider) => provider.enabled !== false);
+}
+
+function cleanRoutingMode(value: unknown): RoutingMode | undefined {
+  return value === "manual" || value === "distribute" ? value : undefined;
+}
+
+export function providerWeight(state: RuntimeState, id: string): number {
+  const weight = state.providerWeights[id];
+  return typeof weight === "number" ? weight : 1;
+}
+
+export { agentTokensUsed, keyCostUsed, keyTokensUsed, orgCostUsed, orgTokensUsed, recordUsage, teamCostUsed, teamTokensUsed, usageForPeriod, userCostUsed, userTokensUsed, userUsageKey } from "./usage-accounting.ts";

package/packages/proxy/src/http/server-io.ts

@@ -0,0 +1,80 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { createServer } from "node:http";
+
+export class HttpInputError extends Error {
+  status: number;
+  code: string;
+  constructor(status: number, code: string) {
+    super(code);
+    this.status = status;
+    this.code = code;
+  }
+}
+
+export function listen(server: ReturnType<typeof createServer>, port: number, host: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const onError = (error: Error) => {
+      server.off("error", onError);
+      reject(error);
+    };
+    server.once("error", onError);
+    server.listen(port, host, () => {
+      server.off("error", onError);
+      resolve();
+    });
+  });
+}
+
+export function readBody(req: IncomingMessage, timeoutMs = bodyTimeoutMs(), maxBytes = bodyLimitBytes()): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    let size = 0;
+    let settled = false;
+    const timer = setTimeout(() => fail(new Error(`request body timed out after ${timeoutMs}ms`)), timeoutMs);
+    req.on("data", (chunk) => {
+      size += Buffer.byteLength(chunk);
+      if (size > maxBytes) return fail(new HttpInputError(413, "request_body_too_large"));
+      chunks.push(Buffer.from(chunk));
+    });
+    req.on("aborted", () => fail(new Error("request body aborted")));
+    req.on("close", () => { if (!req.complete) fail(new Error("request body aborted")); });
+    req.on("error", fail);
+    req.on("end", () => done(Buffer.concat(chunks).toString("utf8")));
+    function done(value: string): void {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(value);
+    }
+    function fail(error: Error): void {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      reject(error);
+    }
+  });
+}
+
+export function inputError(error: unknown): { status: number; code: string } | undefined {
+  return error instanceof HttpInputError ? { status: error.status, code: error.code } : undefined;
+}
+
+function bodyTimeoutMs(): number {
+  const configured = Number(process.env.MOLENKOPF_REQUEST_BODY_TIMEOUT_MS);
+  return Number.isFinite(configured) && configured > 0 ? configured : 30000;
+}
+
+function bodyLimitBytes(): number {
+  const configured = Number(process.env.MOLENKOPF_PROXY_BODY_LIMIT_BYTES);
+  return Number.isFinite(configured) && configured > 0 ? configured : 8 * 1024 * 1024;
+}
+
+export function writeJson(res: ServerResponse, status: number, data: unknown) {
+  res.writeHead(status, { "content-type": "application/json" });
+  res.end(JSON.stringify(data));
+}
+
+export function writeRedirect(res: ServerResponse, location: string) {
+  res.writeHead(302, { location });
+  res.end();
+}

package/packages/proxy/src/http/server-types.ts

@@ -0,0 +1,17 @@
+import type { ProviderConfig } from "../../../core/src/providers/provider-catalog.ts";
+import type { ResolvedAgent } from "./runtime-state.ts";
+
+export type ProxyOptions = {
+  target: string;
+  port: number;
+  host?: string;
+  allowPublicBind?: boolean;
+  dataDir?: string;
+  providers?: ProviderConfig[];
+  activeProviderId?: string;
+  configAgents?: ResolvedAgent[];
+  providerCatalogMode?: "auto" | "explicit";
+  configSource?: { kind: "env" | "file"; path?: string };
+};
+
+export type RunningProxy = { port: number; close: () => Promise<void> };

package/packages/proxy/src/http/server.ts

@@ -0,0 +1,190 @@
+import { randomUUID } from "node:crypto";
+import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
+import { AuditStore } from "../../../core/src/manifest/audit-store.ts";
+import { EventBus } from "../../../core/src/events/event-bus.ts";
+import { type RewriteAudit } from "../../../core/src/pipeline/openai-request-rewriter.ts";
+import { estimateTokens } from "../../../core/src/utils/tokens.ts";
+import { redactSecrets } from "../../../core/src/security/secret-redactor.ts";
+import { builtinMiddlewares, runRequestPipeline, type PluginContext } from "./plugin-pipeline.ts";
+import { orderIndex } from "./local-api-pipeline.ts";
+import { extractConcepts } from "../../../core/src/memory/memory-extractor.ts";
+import { recordConcepts } from "../../../core/src/memory/memory-graph.ts";
+import { RetrievalStore } from "../../../core/src/store/retrieval-store.ts";
+import { buildForwardHeaders, missingProviderCredential } from "./header-utils.ts";
+import { handleLocalRequest } from "./local-api.ts";
+import { createRuntimeState, emptyUsage, isPluginEnabled, type RuntimeState } from "./runtime-state.ts";
+import { resolveRouting } from "./agent-router.ts";
+import { buildManifest, finishRequest } from "./request-finish.ts";
+import { resolveClientIdentity, stripMolenkopfAuthHeaders } from "./proxy-identity.ts";
+import { checkBudgets } from "./budget-gate.ts";
+import { withBudgetWarnings } from "./budget-warnings.ts";
+import { IdentityStore } from "../../../core/src/identity/identity-store.ts";
+import { UsageSnapshotStore } from "../../../core/src/identity/usage-snapshot.ts";
+import { isCliProvider, runCliProvider } from "../runtime/cli-provider.ts";
+import { canStreamOpenAiCli, streamOpenAiCliProvider } from "./cli-stream-response.ts";
+import { forwardStream } from "./streaming-proxy.ts";
+import { createResponseUsageScanner } from "./encoded-usage-meter.ts";
+import { auditPath } from "./request-path.ts";
+import { inputError, listen, readBody, writeJson, writeRedirect } from "./server-io.ts";
+import { requirePublicBindFlag } from "./public-bind.ts";
+import { providerAllowedForClient } from "./provider-access.ts";
+import { restoreUsage } from "./usage-restore.ts";
+import { handleDashboardRequest, isDashboardRequest } from "./dashboard-assets.ts";
+import { createPluginHost, type PluginHost } from "./plugin-host.ts";
+import { effectiveRequestPolicy, enforceModelPolicy, pluginAllowedByPolicy } from "./request-policy.ts";
+import type { ProxyOptions, RunningProxy } from "./server-types.ts";
+export async function startProxy(options: ProxyOptions): Promise<RunningProxy> {
+  const host = options.host ?? "127.0.0.1";
+  requirePublicBindFlag(host, options.allowPublicBind);
+  const state = createRuntimeState(options, host);
+  const identity = new IdentityStore(options.dataDir);
+  await identity.load();
+  state.identity = identity;
+  const usageSnapshot = new UsageSnapshotStore(options.dataDir);
+  const store = new RetrievalStore(options.dataDir);
+  const audit = new AuditStore(options.dataDir);
+  await restoreUsage(state, usageSnapshot, audit);
+  state.usageSnapshot = usageSnapshot;
+  const events = new EventBus(), pluginHost = createPluginHost(state, { store, events });
+  await pluginHost.boot();
+  const server = createServer((req, res) => handle(req, res, store, audit, events, state, pluginHost));
+  await listen(server, options.port, host);
+  const address = server.address();
+  const port = typeof address === "object" && address ? address.port : options.port;
+  state.port = port;
+  await pluginHost.start(port);
+  return {
+    port,
+    close: async () => {
+      await pluginHost.stop().catch(() => {});
+      usageSnapshot.schedule(state);
+      await usageSnapshot.close();
+      identity.close();
+      await new Promise<void>((resolve, reject) => server.close((err) => err ? reject(err) : resolve()));
+    }
+  };
+}
+async function handle(req: IncomingMessage, res: ServerResponse, store: RetrievalStore, audit: AuditStore, events: EventBus, state: RuntimeState, pluginHost: PluginHost) {
+  try {
+    if (req.url === "/") return writeRedirect(res, "/__molenkopf/dashboard");
+    const probePath = auditPath(req.url);
+    if (probePath === "/favicon.ico" || probePath.startsWith("/.well-known/appspecific/")) { res.writeHead(204); return res.end(); }
+    if (isDashboardRequest(req.url)) return await handleDashboardRequest(req, res);
+    if (req.url?.startsWith("/__molenkopf/")) return await handleLocalRequest(req, res, audit, events, state, pluginHost);
+    await handleProxy(req, res, store, audit, events, state, pluginHost);
+  } catch (error) {
+    const input = inputError(error);
+    if (input) return writeJson(res, input.status, { error: input.code });
+    events.emit("request_failed", { data: { error: "proxy_error" } });
+    writeJson(res, 502, { error: "proxy_error" });
+  }
+}
+async function handleProxy(req: IncomingMessage, res: ServerResponse, store: RetrievalStore, auditStore: AuditStore, events: EventBus, state: RuntimeState, pluginHost: PluginHost) {
+  const started = Date.now();
+  const requestId = randomUUID();
+  const rawPath = req.url ?? "/";
+  const path = auditPath(rawPath);
+  const inbound = new Headers(req.headers as Record<string, string>);
+  const resolved = resolveClientIdentity(state.identity, inbound);
+  if (!resolved.keyOk) {
+    events.emit("request_failed", { requestId, data: { error: "invalid_api_key" } });
+    return writeJson(res, 401, { error: "invalid_api_key" });
+  }
+  const client = resolved.client;
+  stripMolenkopfAuthHeaders(inbound);
+  const budget = checkBudgets(state, client);
+  if (budget.ok === false) return rejectBudget(res, events, requestId, budget);
+  for (const warning of budget.warnings) events.emit("request_warning", { requestId, data: { warning } });
+  const routing = resolveRouting(state, inbound, client);
+  if (routing.ok === false) {
+    events.emit("request_failed", { requestId, data: { error: routing.error } });
+    return writeJson(res, routing.status, { error: routing.error });
+  }
+  let provider = routing.provider;
+  events.emit("request_started", { requestId, data: { method: req.method, path } });
+  const originalBody = await readBody(req);
+  const jsonRequest = (inbound.get("content-type") ?? "").includes("application/json");
+  const policy = effectiveRequestPolicy(state, inbound, client);
+  const pluginActive = (id: string) => isPluginEnabled(state, id) && pluginAllowedByPolicy(policy, id);
+  if (jsonRequest && originalBody) {
+    const modelPolicy = enforceModelPolicy(policy, originalBody);
+    if (modelPolicy.ok === false) { events.emit("request_failed", { requestId, data: { error: modelPolicy.error } }); return writeJson(res, modelPolicy.status, { error: modelPolicy.error }); }
+  }
+  if (pluginActive("obsidian-graph-plugin") && originalBody) recordConcepts(state.memoryGraph, extractConcepts(redactSecrets(originalBody).text), new Date().toISOString());
+  let body = originalBody;
+  let audit: RewriteAudit | undefined;
+  if (jsonRequest && originalBody) {
+    const ctx: PluginContext = {
+      requestId, method: req.method ?? "GET", path, consumerId: client.id, providerId: provider.id,
+      body: originalBody, redactedSecrets: 0, compressedItems: 0, savedTokens: 0, retrievalIds: [], compressorsUsed: [], notes: [],
+      usageOf: (id) => state.usageByAgent[id] ?? emptyUsage(),
+      note(message) { ctx.notes.push(message); }
+    };
+    const ordered = [...builtinMiddlewares].sort((a, b) => orderIndex(state, a.id) - orderIndex(state, b.id));
+    await runRequestPipeline(ctx, pluginActive, { store }, ordered);
+    if (ctx.block) { events.emit("request_failed", { requestId, data: { error: ctx.block.error } }); return writeJson(res, ctx.block.status, { error: ctx.block.error }); }
+    if (ctx.providerId !== provider.id) {
+      const next = state.providers.find((item) => item.id === ctx.providerId && item.enabled !== false);
+      if (next) {
+        if (!providerAllowedForClient(client, next.id)) { events.emit("request_failed", { requestId, data: { error: "provider_forbidden" } }); return writeJson(res, 403, { error: "provider_forbidden" }); }
+        provider = next;
+      }
+    }
+    body = ctx.body;
+    audit = {
+      compressedItems: ctx.compressedItems,
+      estimatedOriginalTokens: estimateTokens(originalBody),
+      estimatedCompressedTokens: estimateTokens(body),
+      estimatedSavedTokens: ctx.savedTokens,
+      redactedSecrets: ctx.redactedSecrets,
+      retrievalIds: ctx.retrievalIds,
+      compressorsUsed: ctx.compressorsUsed,
+      warnings: ctx.notes
+    };
+    if (ctx.compressedItems) events.emit("request_compressed", { requestId, data: { items: ctx.compressedItems } });
+  }
+  audit = withBudgetWarnings(audit, budget.warnings);
+  const target = provider.target;
+  if (missingProviderCredential(provider)) return writeJson(res, 502, { error: "missing_provider_credential" });
+  const headers = buildForwardHeaders(inbound, provider);
+  if (body) headers.set("content-length", String(Buffer.byteLength(body)));
+  if (isCliProvider(provider)) {
+    events.emit("request_forwarded", { requestId, data: { path } });
+    if (canStreamOpenAiCli(path, body)) {
+      const cli = await streamOpenAiCliProvider(provider, body, requestId, res);
+      const manifest = buildManifest(requestId, req.method ?? "GET", path, target, provider.id, cli.status, Date.now() - started, client, audit, cli.usage);
+      await finishRequest(manifest, auditStore, events, state, pluginHost);
+      return;
+    }
+    try {
+      const cli = await runCliProvider(provider, body, requestId, path);
+      const manifest = buildManifest(requestId, req.method ?? "GET", path, target, provider.id, cli.status, Date.now() - started, client, audit, cli.usage);
+      await finishRequest(manifest, auditStore, events, state, pluginHost);
+      res.writeHead(cli.status, cli.headers);
+      return res.end(cli.body);
+    } catch (error) {
+      const manifest = buildManifest(requestId, req.method ?? "GET", path, target, provider.id, 502, Date.now() - started, client, audit);
+      await finishRequest(manifest, auditStore, events, state, pluginHost);
+      return writeJson(res, 502, { error: "proxy_error", requestId });
+    }
+  }
+  events.emit("request_forwarded", { requestId, data: { path } });
+  let scanner = createResponseUsageScanner(undefined), statusCode: number;
+  try {
+    const result = await forwardStream(res, target, rawPath, req.method ?? "GET", headers, body || undefined, {
+      allowPrivateTarget: provider.kind === "local" || provider.id === "default",
+      onResponseHead: (_status, responseHeaders) => { scanner = createResponseUsageScanner(headerValue(responseHeaders["content-encoding"])); },
+      onResponseBody: (chunk) => { scanner.feed(chunk); }
+    });
+    statusCode = result.statusCode;
+  } catch (error) {
+    const manifest = buildManifest(requestId, req.method ?? "GET", path, target, provider.id, 502, Date.now() - started, client, audit);
+    await finishRequest(manifest, auditStore, events, state, pluginHost);
+    if (!res.headersSent) return writeJson(res, 502, { error: "proxy_error", requestId });
+    return res.end();
+  }
+const manifest = buildManifest(requestId, req.method ?? "GET", path, target, provider.id, statusCode, Date.now() - started, client, audit, await scanner.finish());
+  await finishRequest(manifest, auditStore, events, state, pluginHost);
+}
+function rejectBudget(res: ServerResponse, events: EventBus, requestId: string, budget: Exclude<ReturnType<typeof checkBudgets>, { ok: true }>) { events.emit("request_failed", { requestId, data: { error: budget.error } }); res.writeHead(budget.status, { "content-type": "application/json", "retry-after": "60" }); return res.end(JSON.stringify({ error: budget.error, tier: budget.tier, scope: budget.scopeId, metric: budget.metric })); }
+const headerValue = (value: number | string | string[] | undefined) => Array.isArray(value) ? value[0] : typeof value === "string" ? value : undefined;

package/packages/proxy/src/http/session-secret.ts

@@ -0,0 +1,19 @@
+const MIN_LENGTH = 32;
+const PLACEHOLDERS = new Set([
+  "your-super-secret-key",
+  "replace-with-at-least-32-random-characters",
+  "changeme",
+  "change-me",
+  "secret",
+  "password"
+]);
+
+const HELP = "MOLENKOPF_SESSION_SECRET is required. Copy .env.example to .env, set a unique value with at least 32 characters, and pass it to Docker with --env-file .env. For source runs, place it in ./.env or export it in your shell.";
+
+export function requireSessionSecret(env: Record<string, string | undefined> = process.env): string {
+  const value = env.MOLENKOPF_SESSION_SECRET?.trim() ?? "";
+  if (!value || value.length < MIN_LENGTH || PLACEHOLDERS.has(value.toLowerCase())) {
+    throw new Error(HELP);
+  }
+  return value;
+}

package/packages/proxy/src/http/streaming-proxy.ts

@@ -0,0 +1,88 @@
+import { request as httpRequest, type ServerResponse, type OutgoingHttpHeaders } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { resolveConnectTarget } from "../../../core/src/security/target-policy.ts";
+
+// Transparent streaming proxy: forward to upstream and stream the response
+// straight back to the client, preserving status, headers, and encoding
+// byte-for-byte. Node built-ins only (no fetch — fetch auto-decodes gzip and
+// would break transparency for streaming/compressed responses).
+
+export type StreamObserver = {
+  onResponseHead?: (statusCode: number, headers: OutgoingHttpHeaders) => void;
+  onResponseBody?: (chunk: Buffer) => void;
+  timeoutMs?: number;
+  allowPrivateTarget?: boolean;
+};
+export type ForwardResult = { statusCode: number };
+
+export async function forwardStream(res: ServerResponse, target: string, rawPath: string, method: string, headers: Headers, body: string | undefined, observer: StreamObserver = {}): Promise<ForwardResult> {
+  const upstream = new URL(originFormTarget(rawPath), target.endsWith("/") ? target : `${target}/`);
+  const checked = await resolveConnectTarget(upstream.toString(), { path: "provider target", allowPrivate: observer.allowPrivateTarget, allowSearch: true });
+  const transport = checked.url.protocol === "https:" ? httpsRequest : httpRequest;
+  return new Promise<ForwardResult>((resolve, reject) => {
+    const timeoutMs = observer.timeoutMs ?? upstreamTimeoutMs();
+    let settled = false;
+    const done = (value: ForwardResult) => { if (!settled) { settled = true; resolve(value); } };
+    const fail = (error: Error) => { if (!settled) { settled = true; reject(error); } };
+    const upstreamReq = transport(checked.url, { method, headers: toOutgoingHeaders(headers, checked.url.host), lookup: pinnedLookup(checked.address, checked.family) }, (upstreamRes) => {
+      const statusCode = upstreamRes.statusCode ?? 502;
+      const safeHeaders = filterResponseHeaders(upstreamRes.headers);
+      observer.onResponseHead?.(statusCode, safeHeaders);
+      res.writeHead(statusCode, safeHeaders);
+      if (observer.onResponseBody) upstreamRes.on("data", (chunk: Buffer | string) => observer.onResponseBody?.(toBuffer(chunk)));
+      upstreamRes.on("end", () => done({ statusCode }));
+      upstreamRes.on("aborted", () => fail(new Error("upstream response aborted")));
+      upstreamRes.on("error", fail);
+      upstreamRes.pipe(res);
+    });
+    upstreamReq.setTimeout(timeoutMs, () => upstreamReq.destroy(new Error(`upstream timed out after ${timeoutMs}ms`)));
+    upstreamReq.on("error", fail);
+    res.on("close", () => { if (!res.writableEnded) upstreamReq.destroy(); });
+    if (body) upstreamReq.end(body);
+    else upstreamReq.end();
+  });
+}
+
+function pinnedLookup(address: string, family: 4 | 6) {
+  return (_hostname: string, _options: unknown, callback: (error: NodeJS.ErrnoException | null, address: string, family: number) => void) => {
+    callback(null, address, family);
+  };
+}
+
+function upstreamTimeoutMs(): number {
+  const configured = Number(process.env.MOLENKOPF_UPSTREAM_TIMEOUT_MS);
+  return Number.isFinite(configured) && configured > 0 ? configured : 120000;
+}
+
+function originFormTarget(rawPath: string): string {
+  if (!rawPath.startsWith("/") || rawPath.startsWith("//") || /^[a-z][a-z0-9+.-]*:/i.test(rawPath)) {
+    throw new Error("invalid_request_target");
+  }
+  return rawPath;
+}
+
+function toOutgoingHeaders(headers: Headers, host: string): OutgoingHttpHeaders {
+  const out: OutgoingHttpHeaders = {};
+  headers.forEach((value, key) => { out[key] = value; });
+  out.host = host;
+  return out;
+}
+
+function filterResponseHeaders(headers: OutgoingHttpHeaders): OutgoingHttpHeaders {
+  const blocked = new Set([
+    "connection", "keep-alive", "proxy-authenticate", "proxy-authorization",
+    "te", "trailer", "transfer-encoding", "upgrade", "set-cookie",
+    "content-security-policy", "content-security-policy-report-only",
+    "cross-origin-opener-policy", "cross-origin-resource-policy",
+    "cross-origin-embedder-policy", "permissions-policy"
+  ]);
+  const out: OutgoingHttpHeaders = {};
+  for (const [key, value] of Object.entries(headers)) {
+    if (!blocked.has(key.toLowerCase())) out[key] = value;
+  }
+  return out;
+}
+
+function toBuffer(chunk: Buffer | string): Buffer {
+  return typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+}