Harden gateway setup and release 0.1.4

Harden model gateway setup, bounded gateway responses, command sandbox policy, and release metadata for 0.1.4.

Author: oscharko

README.md

@@ -1,8 +1,22 @@
 # Keiko
 
-Keiko is a local enterprise coding assistant for regulated engineering teams. It helps inspect a repository, chat with configured language models, generate reviewable unit tests, investigate bugs, run verification, and keep redacted evidence for human review.
+Keiko is a governed agentic workspace for knowledge work that learns from experience.
 
-Keiko is developer-controlled by design. It does not commit, push, open pull requests, merge code, or apply changes without an explicit local action. The manifest-producing surfaces emit redacted evidence for audit.
+The current npm release starts with local developer-assist workflows for regulated engineering teams. Keiko helps inspect a repository, chat with configured language models, generate reviewable unit tests, investigate bugs, run verification, and keep redacted evidence for human review.
+
+Keiko is human-controlled by design. It does not commit, push, open pull requests, merge code, or apply changes without an explicit local action. The manifest-producing surfaces emit redacted evidence for audit.
+
+## Vision
+
+Keiko's long-term direction is a governed workspace where people can delegate knowledge work to learning agents without giving up control, oversight, or accountability.
+
+- **Governed delegation:** agents start with a task, not standing rights.
+- **Harness-first control:** agent actions, tool calls, connector access, approvals, failures, and outcomes flow through one observable control layer.
+- **Keiko Twin:** a governed work representative that can build controlled memory about user preferences, project routines, accepted outcomes, and recurring corrections.
+- **Learning from experience:** Keiko should improve future tool selection, escalation, policy suggestions, and workflow quality from structured evidence and feedback.
+- **Enterprise boundaries:** learning can improve suggestions and routines, but it must never grant itself authority or bypass human and organizational policy.
+
+Software engineering is the first use case because repositories, tests, reviews, and tool calls create hard evidence. The product direction is broader: a controlled agentic workspace for enterprise knowledge work.
 
 ## Requirements
 
@@ -45,8 +59,12 @@ If no model gateway is configured, the UI asks for:
 
 - Base URL, for example `https://llm-gateway.example.com/v1`
 - API token
+- Optional API-key header, only when your gateway admin provides a custom header
+- Deployment names, only when the gateway cannot expose a reliable model list
+
+Keiko calls the gateway model list endpoint, tests discovered chat models with a small chat-completions request, and stores only callable chat models in the local runtime configuration. LiteLLM-compatible gateways can also provide model metadata that lets Keiko filter non-chat models before testing. Credentials stay on the local machine and are not returned to the browser.
 
-Keiko calls the gateway model list endpoint, tests discovered chat models with a small chat-completions request, and stores only callable chat models in the local runtime configuration. Credentials stay on the local machine and are not returned to the browser.
+For OpenAI-compatible gateways such as LiteLLM, usually leave deployment names empty. For Azure AI Foundry, paste the deployment names you want Keiko to offer in the UI.
 
 The UI runs on loopback only. The `--host` option can validate a loopback host value; the server always binds `127.0.0.1`.
 
@@ -89,22 +107,27 @@ The UI can create a local runtime config during first-run setup. For scripted us
     {
       "modelId": "example-chat-model",
       "baseUrl": "https://llm-gateway.example.com/v1",
-      "apiKey": "replace-me"
+      "apiKey": "replace-me",
+      "apiKeyHeaderName": "authorization"
     }
   ]
 }
 ```
 
 Environment variables can override file values:
 
-| Variable                    | Purpose                        |
-| --------------------------- | ------------------------------ |
-| `KEIKO_CONFIG_FILE`         | Path to a gateway config file. |
-| `KEIKO_DEFAULT_BASE_URL`    | Fallback gateway base URL.     |
-| `KEIKO_DEFAULT_API_KEY`     | Fallback gateway API token.    |
-| `KEIKO_MODEL_<ID>_BASE_URL` | Per-model base URL override.   |
-| `KEIKO_MODEL_<ID>_API_KEY`  | Per-model API token override.  |
-| `KEIKO_UI_PORT`             | Local UI port override.        |
+| Variable                               | Purpose                           |
+| -------------------------------------- | --------------------------------- |
+| `KEIKO_CONFIG_FILE`                    | Path to a gateway config file.    |
+| `KEIKO_DEFAULT_BASE_URL`               | Fallback gateway base URL.        |
+| `KEIKO_DEFAULT_API_KEY`                | Fallback gateway API token.       |
+| `KEIKO_DEFAULT_API_KEY_HEADER_NAME`    | Fallback credential header name.  |
+| `KEIKO_MODEL_<ID>_BASE_URL`            | Per-model base URL override.      |
+| `KEIKO_MODEL_<ID>_API_KEY`             | Per-model API token override.     |
+| `KEIKO_MODEL_<ID>_API_KEY_HEADER_NAME` | Per-model credential header name. |
+| `KEIKO_UI_PORT`                        | Local UI port override.           |
+
+Supported credential headers are `authorization`, `x-litellm-key`, `x-api-key`, and `api-key`.
 
 Do not commit gateway config files, API tokens, `.keiko/`, or evidence that contains project-specific review material unless your process explicitly requires it.
 
@@ -129,13 +152,14 @@ Known limits:
 
 ## Troubleshooting
 
-| Symptom               | Check                                                                                                   |
-| --------------------- | ------------------------------------------------------------------------------------------------------- |
-| UI does not open      | Run `npm run keiko:status`, then inspect `.keiko/ui.log`.                                               |
-| Port is busy          | Start with `KEIKO_UI_PORT=1984 npm run keiko:start` or stop the process using the port.                 |
-| No model appears      | Reopen Settings, verify the base URL and token, then run the credential test again.                     |
-| Credential test fails | Confirm the gateway accepts OpenAI-compatible chat-completions requests at the configured base URL.     |
-| Stale process state   | Run `npm run keiko:stop`, delete `.keiko/ui.pid` if the process is no longer running, then start again. |
+| Symptom                | Check                                                                                                    |
+| ---------------------- | -------------------------------------------------------------------------------------------------------- |
+| UI does not open       | Run `npm run keiko:status`, then inspect `.keiko/ui.log`.                                                |
+| Port is busy           | Start with `KEIKO_UI_PORT=1984 npm run keiko:start` or stop the process using the port.                  |
+| No model appears       | Reopen Settings, verify the base URL and token, then run the credential test again.                      |
+| Credential test fails  | Confirm the gateway accepts OpenAI-compatible chat-completions requests at the configured base URL.      |
+| Custom proxy key fails | Confirm whether your gateway expects `Authorization` or a custom API-key header such as `X-Litellm-Key`. |
+| Stale process state    | Run `npm run keiko:stop`, delete `.keiko/ui.pid` if the process is no longer running, then start again.  |
 
 ## Further Reading
 

docs/ui-runbook.md

@@ -33,8 +33,14 @@ When Keiko has no model gateway configuration, Settings asks for:
 
 - Base URL, for example `https://llm-gateway.example.com/v1`
 - API token
+- Optional API-key header, only when your gateway admin provides a custom header
+- Deployment names, only when the gateway cannot expose a reliable model list
 
-Keiko tests the credentials immediately. It lists available models from the gateway, performs a small chat-completions smoke test, and saves only callable chat models in the local runtime configuration.
+Supported credential headers are `authorization`, `x-litellm-key`, `x-api-key`, and `api-key`.
+
+Keiko tests the credentials immediately. It lists available models from the gateway, uses LiteLLM-style model metadata when available, performs a small chat-completions smoke test, and saves only callable chat models in the local runtime configuration.
+
+For OpenAI-compatible gateways such as LiteLLM, usually leave deployment names empty. For Azure AI Foundry, paste the deployment names you want Keiko to offer in the UI.
 
 Environment variables are still supported for scripted starts. They are not a standalone UI configuration source when the UI needs to discover models for a first-time user.
 
@@ -77,4 +83,5 @@ Keep `.keiko/`, runtime config files, and API tokens out of version control.
 | Port conflict          | Stop the conflicting process or start Keiko with another port.                       |
 | No model appears       | Re-run Settings credential test and confirm the gateway exposes chat models.         |
 | Credential test fails  | Confirm the base URL points to an OpenAI-compatible API and that the token is valid. |
+| Custom proxy key fails | Confirm whether your gateway expects `Authorization` or a custom API-key header.     |
 | Stop does not clean up | Ensure the process is gone, then remove `.keiko/ui.pid` and start again.             |

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@oscharko-dev/keiko",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Enterprise model-agnostic developer-assist coding agent for regulated engineering workflows.",
   "type": "module",
   "license": "Apache-2.0",

package.json

@@ -309,7 +309,7 @@ async function cmdStart(
     return 1;
   }
   child.unref();
-  writeFileSync(pidFile(options), `${String(child.pid)}\n`, "utf8");
+  writeFileSync(pidFile(options), `${String(child.pid)}\n`, { encoding: "utf8", mode: 0o600 });
   io.out(`Starting Keiko UI on ${healthUrl(options).replace("/api/health", "")} ...\n`);
 
   const healthy = await waitForHealth(options, child.pid, deps);

src/cli/lifecycle.ts

@@ -4,6 +4,7 @@
 // and are excluded from every serialisation path.
 
 import { readFileSync } from "node:fs";
+import { isIP } from "node:net";
 import { ConfigInvalidError } from "./errors.js";
 import type {
   CircuitBreakerConfig,
@@ -21,11 +22,26 @@ const DEFAULT_RETRY_BASE_DELAY_MS = 500;
 const DEFAULT_FAILURE_THRESHOLD = 5;
 const DEFAULT_COOLDOWN_MS = 30_000;
 const DEFAULT_HALF_OPEN_PROBES = 2;
+export const DEFAULT_API_KEY_HEADER_NAME = "authorization";
+const MAX_API_KEY_HEADER_NAME_LENGTH = 64;
+const API_KEY_HEADER_NAME_RE = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/u;
+export const SUPPORTED_API_KEY_HEADER_NAMES = [
+  DEFAULT_API_KEY_HEADER_NAME,
+  "x-litellm-key",
+  "x-api-key",
+  "api-key",
+] as const;
+const SUPPORTED_API_KEY_HEADER_NAME_SET = new Set<string>(SUPPORTED_API_KEY_HEADER_NAMES);
+const BEARER_API_KEY_HEADER_NAME_SET = new Set<string>([
+  DEFAULT_API_KEY_HEADER_NAME,
+  "x-litellm-key",
+]);
 
 export type EnvSource = Readonly<Record<string, string | undefined>>;
 
 export interface SafeProviderConfig {
   readonly modelId: string;
+  readonly credentialHeaderName: string;
   readonly timeoutMs: number;
   readonly maxRetries: number;
   readonly retryBaseDelayMs: number;
@@ -96,6 +112,45 @@ function optionalNonEmptyString(value: unknown, path: string, fallback: string):
   return requireNonEmptyString(value, path);
 }
 
+export function normalizeApiKeyHeaderName(
+  value: unknown,
+  path: string,
+  fallback = DEFAULT_API_KEY_HEADER_NAME,
+): string {
+  if (value === undefined) {
+    return fallback;
+  }
+  if (typeof value !== "string") {
+    throw new ConfigInvalidError(`${path} must be a string`);
+  }
+  const headerName = value.trim().toLowerCase();
+  if (headerName.length === 0) {
+    return fallback;
+  }
+  if (
+    headerName.length > MAX_API_KEY_HEADER_NAME_LENGTH ||
+    !API_KEY_HEADER_NAME_RE.test(headerName)
+  ) {
+    throw new ConfigInvalidError(`${path} must be a valid HTTP header name`);
+  }
+  if (!SUPPORTED_API_KEY_HEADER_NAME_SET.has(headerName)) {
+    throw new ConfigInvalidError(
+      `${path} must be one of ${SUPPORTED_API_KEY_HEADER_NAMES.join(", ")}`,
+    );
+  }
+  return headerName;
+}
+
+export function apiKeyHeaderValue(headerName: string, apiKey: string): string {
+  if (
+    BEARER_API_KEY_HEADER_NAME_SET.has(headerName) &&
+    !apiKey.toLowerCase().startsWith("bearer ")
+  ) {
+    return `Bearer ${apiKey}`;
+  }
+  return apiKey;
+}
+
 function requireEnum<T extends string>(value: unknown, path: string, allowed: readonly T[]): T {
   if (typeof value !== "string" || !allowed.includes(value as T)) {
     throw new ConfigInvalidError(`${path} must be one of ${allowed.join(", ")}`);
@@ -120,20 +175,42 @@ function resolveSecret(modelId: string, fileValue: string, env: EnvSource, suffi
   return fallback ?? "";
 }
 
+function resolveApiKeyHeaderName(
+  rawValue: unknown,
+  path: string,
+  modelId: string,
+  env: EnvSource,
+): string {
+  const token = envModelToken(modelId);
+  const perModelName = `KEIKO_MODEL_${token}_API_KEY_HEADER_NAME`;
+  const perModel = env[perModelName];
+  if (perModel !== undefined && perModel.length > 0) {
+    return normalizeApiKeyHeaderName(perModel, perModelName);
+  }
+  if (rawValue !== undefined) {
+    return normalizeApiKeyHeaderName(rawValue, path);
+  }
+  return normalizeApiKeyHeaderName(
+    env.KEIKO_DEFAULT_API_KEY_HEADER_NAME,
+    "KEIKO_DEFAULT_API_KEY_HEADER_NAME",
+  );
+}
+
 // Validates a resolved baseUrl for scheme and credential hygiene. Host/IP is
 // intentionally NOT restricted: Keiko addresses private network endpoints
 // (private IPs are a valid, first-class target); this guard is scheme/credential
 // hygiene + defence-in-depth, not host filtering.
 function isLoopbackHost(hostname: string): boolean {
-  return (
-    hostname === "localhost" ||
-    hostname === "::1" ||
-    hostname === "[::1]" ||
-    hostname.startsWith("127.")
-  );
+  if (hostname === "localhost" || hostname === "::1" || hostname === "[::1]") {
+    return true;
+  }
+  // Real IPv4 loopback only. isIP === 4 guarantees a well-formed dotted-quad, so a "127." prefix
+  // here is the 127.0.0.0/8 block — never a domain such as "127.evil.com" or "127.0.0.1.evil.com".
+  // The WHATWG URL parser has already canonicalised IPv4 shorthand/hex into url.hostname.
+  return isIP(hostname) === 4 && hostname.startsWith("127.");
 }
 
-function validateBaseUrl(baseUrl: string, path: string): void {
+export function validateBaseUrl(baseUrl: string, path: string): void {
   let url: URL;
   try {
     url = new URL(baseUrl);
@@ -143,6 +220,9 @@ function validateBaseUrl(baseUrl: string, path: string): void {
   if (url.protocol !== "http:" && url.protocol !== "https:") {
     throw new ConfigInvalidError(`${path}.baseUrl must use the http or https scheme`);
   }
+  if (url.search !== "" || url.hash !== "") {
+    throw new ConfigInvalidError(`${path}.baseUrl must not contain a query string or fragment`);
+  }
   if (url.protocol === "http:" && !isLoopbackHost(url.hostname)) {
     throw new ConfigInvalidError(
       `${path}.baseUrl must use https unless it targets localhost or loopback`,
@@ -243,6 +323,12 @@ function parseProviderConfig(
     modelId,
     baseUrl,
     apiKey,
+    apiKeyHeaderName: resolveApiKeyHeaderName(
+      raw.apiKeyHeaderName,
+      `${path}.apiKeyHeaderName`,
+      modelId,
+      env,
+    ),
     timeoutMs: requirePositiveInt(raw.timeoutMs ?? DEFAULT_TIMEOUT_MS, `${path}.timeoutMs`),
     maxRetries: requireNonNegativeInt(raw.maxRetries ?? DEFAULT_MAX_RETRIES, `${path}.maxRetries`),
     retryBaseDelayMs: requirePositiveInt(
@@ -331,6 +417,7 @@ export function toSafeObject(config: GatewayConfig): SafeGatewayConfig {
   return {
     providers: config.providers.map((provider) => ({
       modelId: provider.modelId,
+      credentialHeaderName: provider.apiKeyHeaderName ?? DEFAULT_API_KEY_HEADER_NAME,
       timeoutMs: provider.timeoutMs,
       maxRetries: provider.maxRetries,
       retryBaseDelayMs: provider.retryBaseDelayMs,

src/gateway/config.ts

@@ -2,6 +2,9 @@ import { readFileSync } from "node:fs";
 import { request as httpsRequest } from "node:https";
 import { rootCertificates } from "node:tls";
 
+// Caps a single gateway response at 10 MB; real chat completions are far smaller.
+export const MAX_RESPONSE_BYTES = 10_000_000;
+
 export interface GatewayFetchOptions extends RequestInit {
   readonly fetchImpl?: typeof fetch | undefined;
   readonly useCaFallback?: boolean | undefined;
@@ -92,7 +95,14 @@ function fetchWithCaBundle(url: string, init: RequestInit): Promise<Response> {
       },
       (res) => {
         const chunks: Buffer[] = [];
+        let total = 0;
         res.on("data", (chunk: Buffer) => {
+          total += chunk.length;
+          if (total > MAX_RESPONSE_BYTES) {
+            req.destroy();
+            reject(new Error("gateway response exceeded the size limit"));
+            return;
+          }
           chunks.push(chunk);
         });
         res.on("end", () => {
@@ -127,3 +137,28 @@ export async function gatewayFetch(
     throw error;
   }
 }
+
+export async function readJsonCapped(
+  response: Response,
+  maxBytes: number = MAX_RESPONSE_BYTES,
+): Promise<unknown> {
+  if (response.body === null) {
+    return response.json();
+  }
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  const parts: string[] = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > maxBytes) {
+      await reader.cancel();
+      throw new Error("response body exceeded the size limit");
+    }
+    parts.push(decoder.decode(value, { stream: true }));
+  }
+  parts.push(decoder.decode());
+  return JSON.parse(parts.join("")) as unknown;
+}

src/gateway/http.ts

@@ -35,9 +35,13 @@ export {
 } from "./capabilities.js";
 
 export {
+  apiKeyHeaderValue,
+  DEFAULT_API_KEY_HEADER_NAME,
   loadConfigFromFile,
+  normalizeApiKeyHeaderName,
   parseGatewayConfig,
   toSafeObject,
+  validateBaseUrl,
   type EnvSource,
   type SafeGatewayConfig,
   type SafeProviderConfig,