keryx 0.29.9 → 0.29.11

package/actions/swagger.ts

@@ -62,10 +62,10 @@ export class Swagger implements Action {
   web = { route: "/swagger", method: HTTP_METHOD.GET };
 
   async run() {
-    const paths: Record<string, any> = {};
+    const paths: Record<string, Record<string, unknown>> = {};
     const components: {
-      schemas: Record<string, any>;
-      securitySchemes?: Record<string, any>;
+      schemas: Record<string, unknown>;
+      securitySchemes?: Record<string, unknown>;
     } = {
       schemas: {},
       securitySchemes: {
@@ -94,21 +94,23 @@ export class Swagger implements Action {
       const description = action.description;
 
       // Extract path parameters from the original route
-      const parameters: any[] = [];
+      const parameters: Array<Record<string, unknown>> = [];
       const pathParamMatches = action.web.route.match(/:\w+/g) || [];
       const pathParamNames = new Set<string>();
 
       // Pre-compute Zod JSON Schema for enriching path param types
-      let zodProperties: Record<string, any> = {};
+      let zodProperties: Record<string, Record<string, unknown>> = {};
       let zodDescriptions: Record<string, string> = {};
       if (action.inputs && typeof action.inputs.parse === "function") {
         const jsonSchema = z.toJSONSchema(action.inputs, {
           io: "input",
           unrepresentable: "any",
-        }) as any;
-        zodProperties = jsonSchema.properties ?? {};
-        for (const [name, propSchema] of Object.entries<any>(zodProperties)) {
-          if (propSchema.description) {
+        }) as Record<string, unknown>;
+        zodProperties =
+          (jsonSchema.properties as Record<string, Record<string, unknown>>) ??
+          {};
+        for (const [name, propSchema] of Object.entries(zodProperties)) {
+          if (typeof propSchema.description === "string") {
             zodDescriptions[name] = propSchema.description;
           }
         }
@@ -135,16 +137,18 @@ export class Swagger implements Action {
         const fullSchema = z.toJSONSchema(action.inputs!, {
           io: "input",
           unrepresentable: "any",
-        }) as any;
-        const requiredFields = new Set<string>(fullSchema.required ?? []);
-        for (const [name, propSchema] of Object.entries<any>(zodProperties)) {
+        }) as Record<string, unknown>;
+        const requiredFields = new Set<string>(
+          (fullSchema.required as string[] | undefined) ?? [],
+        );
+        for (const [name, propSchema] of Object.entries(zodProperties)) {
           if (pathParamNames.has(name)) continue; // already a path param
           parameters.push({
             name,
             in: "query",
             required: requiredFields.has(name),
             schema: propSchema,
-            ...(propSchema.description
+            ...(typeof propSchema.description === "string"
               ? { description: propSchema.description }
               : {}),
           });
@@ -152,7 +156,7 @@ export class Swagger implements Action {
       }
 
       // Build requestBody if Zod inputs exist and method supports body
-      let requestBody: any = undefined;
+      let requestBody: Record<string, unknown> | undefined = undefined;
       if (
         action.inputs &&
         typeof action.inputs.parse === "function" &&
@@ -166,9 +170,9 @@ export class Swagger implements Action {
         const jsonSchema = z.toJSONSchema(zodSchema, {
           io: "input",
           unrepresentable: "any",
-        });
+        }) as Record<string, unknown>;
         // Remove $schema from component schemas (not needed in OpenAPI)
-        const { $schema, ...schemaWithout$schema } = jsonSchema as any;
+        const { $schema, ...schemaWithout$schema } = jsonSchema;
         components.schemas[schemaName] = schemaWithout$schema;
         requestBody = {
           required: true,
@@ -181,7 +185,9 @@ export class Swagger implements Action {
       }
 
       // Build responses - use generated schema if available
-      const responses = JSON.parse(JSON.stringify(swaggerResponses));
+      const responses: Record<string, unknown> = JSON.parse(
+        JSON.stringify(swaggerResponses),
+      );
 
       if (action.web?.streaming) {
         // Streaming endpoints return SSE

package/config/observability.ts

@@ -4,4 +4,6 @@ export const configObservability = {
   enabled: await loadFromEnvIfSet("OTEL_METRICS_ENABLED", false),
   metricsRoute: await loadFromEnvIfSet("OTEL_METRICS_ROUTE", "/metrics"),
   serviceName: await loadFromEnvIfSet("OTEL_SERVICE_NAME", ""),
+  metricsAuthUsername: await loadFromEnvIfSet("OTEL_METRICS_AUTH_USERNAME", ""),
+  metricsAuthPassword: await loadFromEnvIfSet("OTEL_METRICS_AUTH_PASSWORD", ""),
 };

package/config/server/mcp.ts

@@ -17,5 +17,6 @@ export const configServerMcp = {
     "MCP_OAUTH_REFRESH_TTL",
     60 * 60 * 24 * 30,
   ), // 30 days, in seconds
+  oauthTrustProxy: await loadFromEnvIfSet("MCP_OAUTH_TRUST_PROXY", false),
   markdownDepthLimit: await loadFromEnvIfSet("MCP_MARKDOWN_DEPTH_LIMIT", 5),
 };

package/config/server/web.ts

@@ -70,7 +70,7 @@ export const configServerWeb = {
   compression: {
     enabled: await loadFromEnvIfSet("WEB_COMPRESSION_ENABLED", true),
     threshold: await loadFromEnvIfSet("WEB_COMPRESSION_THRESHOLD", 1024),
-    encodings: ["br", "gzip"] as ("br" | "gzip")[],
+    encodings: ["gzip"] as "gzip"[],
   },
   correlationId: {
     header: await loadFromEnvIfSet("WEB_CORRELATION_ID_HEADER", "X-Request-Id"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keryx",
-  "version": "0.29.9",
+  "version": "0.29.11",
   "module": "index.ts",
   "type": "module",
   "license": "MIT",

package/servers/web.ts

@@ -1,6 +1,6 @@
+import { randomUUID } from "node:crypto";
 import { parse } from "node:url";
 import type { ServerWebSocket } from "bun";
-import { randomUUID } from "crypto";
 import { api, logger } from "../api";
 import { type HTTP_METHOD } from "../classes/Action";
 import { Connection } from "../classes/Connection";
@@ -11,6 +11,7 @@ import { config } from "../config";
 import type { PubSubMessage } from "../initializers/pubsub";
 import { ansi } from "../util/ansi";
 import { isOriginAllowed } from "../util/http";
+import { verifyBasicAuth } from "../util/webBasicAuth";
 import { compressResponse } from "../util/webCompression";
 import {
   buildError,
@@ -325,6 +326,23 @@ export class WebServer extends Server<ReturnType<typeof Bun.serve>> {
       config.observability.enabled &&
       parsedUrl.pathname === config.observability.metricsRoute
     ) {
+      if (
+        !verifyBasicAuth(
+          req,
+          config.observability.metricsAuthUsername,
+          config.observability.metricsAuthPassword,
+        )
+      ) {
+        return {
+          response: new Response("Unauthorized", {
+            status: 401,
+            headers: {
+              "WWW-Authenticate": 'Basic realm="Metrics"',
+              "Content-Type": "text/plain",
+            },
+          }),
+        };
+      }
       const body = await api.observability.collectMetrics();
       return {
         response: new Response(body || "", {

package/util/config.ts

@@ -1,62 +1,56 @@
-/**
-Deep-merges source into target, mutating target in place.
-Only plain objects are recursively merged; arrays and primitives are overwritten.
-*/
-export function deepMerge<T extends Record<string, any>>(
+type MergeMode = "overwrite" | "defaults";
+
+function mergeWith<T extends Record<string, unknown>>(
   target: T,
-  source: Record<string, any>,
+  source: Record<string, unknown>,
+  mode: MergeMode,
 ): T {
+  const writable = target as Record<string, unknown>;
   for (const key of Object.keys(source)) {
     const targetVal = target[key];
     const sourceVal = source[key];
-
-    if (
+    const bothPlainObjects =
       targetVal &&
       sourceVal &&
       typeof targetVal === "object" &&
       typeof sourceVal === "object" &&
       !Array.isArray(targetVal) &&
-      !Array.isArray(sourceVal)
-    ) {
-      deepMerge(targetVal, sourceVal);
-    } else {
-      (target as any)[key] = sourceVal;
+      !Array.isArray(sourceVal);
+
+    if (bothPlainObjects) {
+      mergeWith(
+        targetVal as Record<string, unknown>,
+        sourceVal as Record<string, unknown>,
+        mode,
+      );
+    } else if (mode === "overwrite" || !(key in target)) {
+      writable[key] = sourceVal;
     }
   }
 
   return target;
 }
 
+/**
+Deep-merges source into target, mutating target in place.
+Only plain objects are recursively merged; arrays and primitives are overwritten.
+*/
+export function deepMerge<T extends Record<string, unknown>>(
+  target: T,
+  source: Record<string, unknown>,
+): T {
+  return mergeWith(target, source, "overwrite");
+}
+
 /**
  * Like `deepMerge`, but only sets values that don't already exist in target.
  * Useful for applying plugin config defaults without overwriting user-set values.
  */
-export function deepMergeDefaults<T extends Record<string, any>>(
+export function deepMergeDefaults<T extends Record<string, unknown>>(
   target: T,
-  source: Record<string, any>,
+  source: Record<string, unknown>,
 ): T {
-  for (const key of Object.keys(source)) {
-    if (!(key in target)) {
-      (target as any)[key] = source[key];
-    } else {
-      const targetVal = target[key];
-      const sourceVal = source[key];
-
-      if (
-        targetVal &&
-        sourceVal &&
-        typeof targetVal === "object" &&
-        typeof sourceVal === "object" &&
-        !Array.isArray(targetVal) &&
-        !Array.isArray(sourceVal)
-      ) {
-        deepMergeDefaults(targetVal, sourceVal);
-      }
-      // If key exists in target and isn't a nested object, keep the target value
-    }
-  }
-
-  return target;
+  return mergeWith(target, source, "defaults");
 }
 
 /**

package/util/http.ts

@@ -35,10 +35,20 @@ export function buildCorsHeaders(
 }
 
 /**
- * Derive the external-facing origin for a request.
- * Respects reverse-proxy headers (`X-Forwarded-Proto` / `X-Forwarded-Host`)
- * so that URLs are correct when behind ngrok, a load balancer, etc.
- * Falls back to the parsed request-URL origin.
+ * Derive the external-facing origin for a request. Used to construct OAuth
+ * metadata URLs (issuer, endpoints) and the MCP `WWW-Authenticate` resource
+ * metadata URL.
+ *
+ * Resolution order:
+ * 1. `applicationUrl` config (when set to a non-localhost value).
+ * 2. `X-Forwarded-Proto` / `X-Forwarded-Host` (or `Host`) headers — only when
+ *    `config.server.mcp.oauthTrustProxy` is enabled. These headers are
+ *    spoofable by any client when the server is reachable directly, so
+ *    trusting them unconditionally would let an attacker poison OAuth
+ *    metadata and MCP `WWW-Authenticate` URLs. Operators must opt in via
+ *    `MCP_OAUTH_TRUST_PROXY=true` after confirming a reverse proxy strips
+ *    client-supplied forwarded headers.
+ * 3. The parsed request-URL origin.
  */
 export function getExternalOrigin(req: Request, url: URL): string {
   // Prefer explicitly configured APPLICATION_URL (for proxy/tunnel scenarios
@@ -48,17 +58,18 @@ export function getExternalOrigin(req: Request, url: URL): string {
     return new URL(appUrl).origin;
   }
 
-  // Fall back to reverse-proxy headers
-  const forwardedProto = req.headers.get("x-forwarded-proto");
-  const forwardedHost =
-    req.headers.get("x-forwarded-host") || req.headers.get("host");
+  if (config.server.mcp.oauthTrustProxy) {
+    const forwardedProto = req.headers.get("x-forwarded-proto");
+    const forwardedHost =
+      req.headers.get("x-forwarded-host") || req.headers.get("host");
 
-  if (forwardedProto && forwardedHost) {
-    return `${forwardedProto}://${forwardedHost}`;
-  }
+    if (forwardedProto && forwardedHost) {
+      return `${forwardedProto}://${forwardedHost}`;
+    }
 
-  if (forwardedHost) {
-    return `${url.protocol}//${forwardedHost}`;
+    if (forwardedHost) {
+      return `${url.protocol}//${forwardedHost}`;
+    }
   }
 
   return url.origin;

package/util/mcpServer.ts

@@ -3,6 +3,11 @@ import {
   ResourceTemplate,
 } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import type {
+  ServerNotification,
+  ServerRequest,
+} from "@modelcontextprotocol/sdk/types.js";
 import { randomUUID } from "crypto";
 import * as z4mini from "zod/v4-mini";
 import { api, logger } from "../api";
@@ -159,7 +164,10 @@ function registerTools(mcpServer: McpServer) {
     mcpServer.registerTool(
       toolName,
       toolConfig,
-      async (args: any, extra: any) => {
+      async (
+        args: Record<string, unknown>,
+        extra: RequestHandlerExtra<ServerRequest, ServerNotification>,
+      ) => {
         const mcpSessionId = extra.sessionId || "";
         const connection = await createMcpConnection(extra);
 

package/util/oauth.ts

@@ -40,23 +40,14 @@ export function validateRedirectUri(uri: string): {
 }
 
 /**
- * Compare two redirect URIs by origin and pathname (ignoring query params).
- * Returns `false` if either URI is malformed.
+ * Compare two redirect URIs with exact string matching, as required by
+ * RFC 6749 §3.1.2.3 and RFC 8252 §8.4.
  */
 export function redirectUrisMatch(
   registeredUri: string,
   requestedUri: string,
 ): boolean {
-  try {
-    const registered = new URL(registeredUri);
-    const requested = new URL(requestedUri);
-    return (
-      registered.origin === requested.origin &&
-      registered.pathname === requested.pathname
-    );
-  } catch {
-    return false;
-  }
+  return registeredUri === requestedUri;
 }
 
 /** Encode a byte array as a URL-safe base64 string (no padding). Used for PKCE code challenges. */

package/util/webBasicAuth.ts

@@ -0,0 +1,53 @@
+import { timingSafeEqual } from "node:crypto";
+
+// Pads to a common length so we don't leak the expected length via early-return.
+function timingSafeStringEqual(a: string, b: string): boolean {
+  const aBuf = Buffer.from(a, "utf8");
+  const bBuf = Buffer.from(b, "utf8");
+  const len = Math.max(aBuf.length, bBuf.length, 1);
+  const aPadded = Buffer.alloc(len);
+  const bPadded = Buffer.alloc(len);
+  aBuf.copy(aPadded);
+  bBuf.copy(bPadded);
+  return timingSafeEqual(aPadded, bPadded) && aBuf.length === bBuf.length;
+}
+
+/**
+ * Verifies an HTTP Basic auth `Authorization` header against expected credentials
+ * using a constant-time string compare.
+ *
+ * @param req - The incoming `Request`. Read for its `Authorization` header.
+ * @param expectedUsername - The username to match. If empty, auth is treated as
+ *   disabled and the function returns `true`.
+ * @param expectedPassword - The password to match. If empty, auth is treated as
+ *   disabled and the function returns `true`.
+ * @returns `true` when auth is disabled (either credential empty) or when the
+ *   header carries valid `Basic <base64>` credentials matching both expected
+ *   values. `false` for any malformed, missing, or wrong header.
+ */
+export function verifyBasicAuth(
+  req: Request,
+  expectedUsername: string,
+  expectedPassword: string,
+): boolean {
+  if (!expectedUsername || !expectedPassword) return true;
+
+  const header = req.headers.get("Authorization");
+  if (!header?.startsWith("Basic ")) return false;
+
+  let decoded: string;
+  try {
+    decoded = atob(header.slice(6).trim());
+  } catch {
+    return false;
+  }
+
+  const idx = decoded.indexOf(":");
+  if (idx === -1) return false;
+  const user = decoded.slice(0, idx);
+  const pass = decoded.slice(idx + 1);
+
+  const userOk = timingSafeStringEqual(user, expectedUsername);
+  const passOk = timingSafeStringEqual(pass, expectedPassword);
+  return userOk && passOk;
+}

package/util/webCompression.ts

@@ -37,7 +37,7 @@ function parseAcceptEncoding(header: string): Set<string> {
 /**
  * Pick the best encoding based on server preference order and client support.
  */
-function selectEncoding(clientEncodings: Set<string>): "br" | "gzip" | null {
+function selectEncoding(clientEncodings: Set<string>): "gzip" | null {
   for (const encoding of config.server.web.compression.encodings) {
     if (clientEncodings.has(encoding)) return encoding;
   }
@@ -53,6 +53,24 @@ function isIncompressible(contentType: string | null): boolean {
   return INCOMPRESSIBLE_TYPES.has(mimeType);
 }
 
+/**
+ * Pipe a body through a gzip `CompressionStream` and build a new `Response` carrying the
+ * compression headers (`Content-Encoding`, appended `Vary`, removed `Content-Length`).
+ */
+function compressBody(body: ReadableStream, response: Response): Response {
+  const compressionStream = new CompressionStream("gzip");
+  // @ts-ignore Bun's ReadableStream type is incompatible with Node/DOM ReadableStream
+  const stream = body.pipeThrough(compressionStream);
+
+  const headers = new Headers(response.headers);
+  headers.set("Content-Encoding", "gzip");
+  headers.append("Vary", "Accept-Encoding");
+  headers.delete("Content-Length");
+
+  // @ts-ignore Bun's ReadableStream type is incompatible with Node/DOM ReadableStream
+  return new Response(stream, { status: response.status, headers });
+}
+
 /**
  * Conditionally compress an HTTP response based on the client's `Accept-Encoding` header,
  * the response content type, and the configured compression threshold.
@@ -86,8 +104,7 @@ export async function compressResponse(
   if (!acceptEncoding) return response;
 
   const clientEncodings = parseAcceptEncoding(acceptEncoding);
-  const encoding = selectEncoding(clientEncodings);
-  if (!encoding) return response;
+  if (!selectEncoding(clientEncodings)) return response;
 
   // Skip incompressible content types
   if (isIncompressible(response.headers.get("Content-Type"))) return response;
@@ -112,40 +129,9 @@ export async function compressResponse(
       });
     }
 
-    // Compress the buffered body
-    const format: Bun.CompressionFormat = encoding === "br" ? "brotli" : "gzip";
-    // @ts-ignore Bun supports "brotli" as CompressionFormat but DOM lib does not
-    const compressionStream = new CompressionStream(format);
-    // @ts-ignore Bun's ReadableStream type is incompatible with Node/DOM ReadableStream
-    const stream = new Blob([body]).stream().pipeThrough(compressionStream);
-
-    const headers = new Headers(response.headers);
-    headers.set("Content-Encoding", encoding);
-    headers.append("Vary", "Accept-Encoding");
-    headers.delete("Content-Length");
-
-    // @ts-ignore Bun's ReadableStream type is incompatible with Node/DOM ReadableStream
-    return new Response(stream, {
-      status: response.status,
-      headers,
-    });
+    return compressBody(new Blob([body]).stream(), response);
   }
 
   // Content-Length is present and above threshold — stream-compress
-  const format: Bun.CompressionFormat = encoding === "br" ? "brotli" : "gzip";
-  // @ts-ignore Bun supports "brotli" as CompressionFormat but DOM lib does not
-  const compressionStream = new CompressionStream(format);
-  // @ts-ignore Bun's ReadableStream type is incompatible with Node/DOM ReadableStream
-  const stream = response.body.pipeThrough(compressionStream);
-
-  const headers = new Headers(response.headers);
-  headers.set("Content-Encoding", encoding);
-  headers.append("Vary", "Accept-Encoding");
-  headers.delete("Content-Length");
-
-  // @ts-ignore Bun's ReadableStream type is incompatible with Node/DOM ReadableStream
-  return new Response(stream, {
-    status: response.status,
-    headers,
-  });
+  return compressBody(response.body, response);
 }

package/util/webRouting.ts

@@ -112,6 +112,28 @@ async function readBodyWithLimit(req: Request): Promise<string> {
   return new TextDecoder().decode(merged);
 }
 
+/**
+ * Merge a value into the params object under `key`, appending to any existing
+ * value rather than replacing it. If `key` is not set, assigns `value` as-is.
+ * If it is set, produces an array containing the existing value(s) followed by
+ * the incoming value(s). Used to fold body, form-data, and query string
+ * sources into a single params object while preserving repeated keys.
+ */
+function appendParam(
+  params: Record<string, unknown>,
+  key: string,
+  value: unknown,
+): void {
+  if (params[key] === undefined) {
+    params[key] = value;
+    return;
+  }
+  const incoming = Array.isArray(value) ? value : [value];
+  params[key] = Array.isArray(params[key])
+    ? [...(params[key] as unknown[]), ...incoming]
+    : [params[key], ...incoming];
+}
+
 /**
  * Parse request parameters from path params, request body (JSON or form-data),
  * and query string into a single plain object.
@@ -179,44 +201,12 @@ export async function parseRequestParams(
     }
 
     const f = await req.formData();
-    f.forEach((value, key) => {
-      if (params[key] !== undefined) {
-        if (Array.isArray(params[key])) {
-          (params[key] as unknown[]).push(value);
-        } else {
-          params[key] = [params[key], value];
-        }
-      } else {
-        params[key] = value;
-      }
-    });
+    f.forEach((value, key) => appendParam(params, key, value));
   }
 
   if (url.query) {
     for (const [key, values] of Object.entries(url.query)) {
-      if (values !== undefined) {
-        if (Array.isArray(values)) {
-          if (params[key] !== undefined) {
-            if (Array.isArray(params[key])) {
-              (params[key] as unknown[]).push(...values);
-            } else {
-              params[key] = [params[key], ...values];
-            }
-          } else {
-            params[key] = values;
-          }
-        } else {
-          if (params[key] !== undefined) {
-            if (Array.isArray(params[key])) {
-              (params[key] as unknown[]).push(values);
-            } else {
-              params[key] = [params[key], values];
-            }
-          } else {
-            params[key] = values;
-          }
-        }
-      }
+      if (values !== undefined) appendParam(params, key, values);
     }
   }
 

package/util/zodMixins.ts

@@ -1,4 +1,4 @@
-import { eq } from "drizzle-orm";
+import { type AnyColumn, eq, type Table } from "drizzle-orm";
 import { z } from "zod/v4";
 import { api } from "../api";
 import { ErrorType, TypedError } from "../classes/TypedError";
@@ -79,9 +79,6 @@ export function paginationInputs(options?: {
   });
 }
 
-// Type for Drizzle tables with an id column
-type TableWithId = { id: any; $inferSelect: any };
-
 /**
  * Generic factory to create a Zod schema that accepts either an ID or a model object.
  * If an ID is provided, it resolves to the full model via database lookup.
@@ -91,8 +88,8 @@ type TableWithId = { id: any; $inferSelect: any };
  * @param isModel - Type guard function to check if value is already a model
  * @param entityName - Human-readable name for error messages
  */
-export function zIdOrModel<TTable extends TableWithId, TModel>(
-  table: TTable,
+export function zIdOrModel<TModel>(
+  table: Table & { id: AnyColumn },
   modelSchema: z.ZodType<TModel>,
   isModel: (val: unknown) => val is TModel,
   entityName: string,
@@ -105,8 +102,8 @@ export function zIdOrModel<TTable extends TableWithId, TModel>(
       }
       const [record] = await api.db.db
         .select()
-        .from(table as any)
-        .where(eq((table as any).id, val))
+        .from(table)
+        .where(eq(table.id, val))
         .limit(1);
 
       if (!record) {