keryx 0.29.11 → 0.31.0

package/api.ts

@@ -17,7 +17,7 @@ export {
   type ChannelConstructorInputs,
   type ChannelMiddleware,
 } from "./classes/Channel";
-export { Connection } from "./classes/Connection";
+export { CONNECTION_TYPE, Connection } from "./classes/Connection";
 export { Initializer } from "./classes/Initializer";
 export { LogFormat, Logger } from "./classes/Logger";
 export { Server } from "./classes/Server";

package/classes/API.ts

@@ -26,7 +26,7 @@ export enum RUN_MODE {
 export class API {
   /** The root directory of the user's application. Set this before calling `initialize()`. */
   rootDir: string;
-  /** The root directory of the keryx package itself (auto-resolved from `import.meta.path`). */
+  /** The root directory of the keryx package itself (auto-resolved from `import.meta.filename`). */
   packageDir: string;
   /** Whether `initialize()` has completed successfully. */
   initialized: boolean;
@@ -50,7 +50,7 @@ export class API {
 
   constructor() {
     this.bootTime = new Date().getTime();
-    this.packageDir = path.join(import.meta.path, "..", "..");
+    this.packageDir = path.join(import.meta.filename, "..", "..");
     this.rootDir = this.packageDir;
     this.logger = new Logger(config.logger);
 

package/classes/Connection.ts

@@ -63,6 +63,26 @@ type ActionParamsState = {
   value: Record<string, unknown>;
 };
 
+/**
+ * The transport that originated a {@link Connection}. Use these constants
+ * instead of bare strings when checking `connection.type` so the value is
+ * consistent across the framework, plugins, and middleware.
+ */
+export enum CONNECTION_TYPE {
+  /** HTTP request handled by the web server. */
+  WEB = "web",
+  /** WebSocket message handled by the web server's `Bun.serve` upgrade. */
+  WEBSOCKET = "websocket",
+  /** Action invoked from the CLI runner. */
+  CLI = "cli",
+  /** Action invoked through the MCP transport. */
+  MCP = "mcp",
+  /** Action running as a Resque background task. */
+  TASK = "task",
+  /** Action invoked from the OAuth login/signup flow. */
+  OAUTH = "oauth",
+}
+
 /**
  * Represents a client connection to the server — HTTP request, WebSocket, or internal caller.
  * Each connection tracks its own session, channel subscriptions, and rate-limit state.
@@ -75,8 +95,8 @@ export class Connection<
   T extends Record<string, any> = Record<string, any>,
   TMeta extends Record<string, any> = Record<string, any>,
 > {
-  /** Transport type identifier (e.g., `"web"`, `"websocket"`). */
-  type: string;
+  /** Transport that originated this connection. */
+  type: CONNECTION_TYPE;
   /** A human-readable identifier for the connection, typically the remote IP or a session key. */
   identifier: string;
   /** Unique connection ID (UUID by default). Used as the key in `api.connections`. */
@@ -103,14 +123,14 @@ export class Connection<
   /**
    * Create a new connection and register it in `api.connections`.
    *
-   * @param type - Transport type (e.g., `"web"`, `"websocket"`).
+   * @param type - Transport that originated this connection.
    * @param identifier - Human-readable identifier, typically the remote IP address.
    * @param id - Unique connection ID. Defaults to a random UUID.
    * @param rawConnection - The underlying transport handle (e.g., Bun `ServerWebSocket`).
    * @param sessionId - Session ID for Redis session lookup. Defaults to `id`. Use a different value when the connection map key should differ from the session cookie (e.g., WebSocket connections).
    */
   constructor(
-    type: string,
+    type: CONNECTION_TYPE,
     identifier: string,
     id = randomUUID() as string,
     rawConnection: any = undefined,

package/index.ts

@@ -29,7 +29,7 @@ export type {
   AfterActHook,
   BeforeActHook,
 } from "./classes/Connection";
-export { Connection } from "./classes/Connection";
+export { CONNECTION_TYPE, Connection } from "./classes/Connection";
 export { LogLevel } from "./classes/Logger";
 export type { KeryxPlugin, PluginGenerator } from "./classes/Plugin";
 export { SSEResponse, StreamingResponse } from "./classes/StreamingResponse";
@@ -65,6 +65,7 @@ export { deepMerge, deepMergeDefaults, loadFromEnvIfSet } from "./util/config";
 export { getValidTypes } from "./util/generate";
 export { globLoader } from "./util/glob";
 export { type PaginatedResult, paginate } from "./util/pagination";
+export { safeCompare } from "./util/safeCompare";
 export type { JSONSchema } from "./util/swaggerSchemaGenerator";
 export {
   computeActionsHash,

package/initializers/channels.ts

@@ -10,7 +10,7 @@ import { globLoader } from "../util/glob";
 
 const namespace = "channels";
 const PRESENCE_KEY_PREFIX = "presence:";
-const LUA_DIR = join(import.meta.dir, "..", "lua");
+const LUA_DIR = join(import.meta.dirname, "..", "lua");
 
 const ADD_PRESENCE_LUA = await Bun.file(
   join(LUA_DIR, "add-presence.lua"),

package/initializers/resque.ts

@@ -10,6 +10,7 @@ import {
   Action,
   type ActionParams,
   api,
+  CONNECTION_TYPE,
   Connection,
   config,
   logger,
@@ -337,7 +338,7 @@ export class Resque extends Initializer {
           | undefined;
 
         const connection = new Connection(
-          "task",
+          CONNECTION_TYPE.TASK,
           `job:${api.process.name}:${SERVER_JOB_COUNTER++}`,
         );
         if (propagatedCorrelationId) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keryx",
-  "version": "0.29.11",
+  "version": "0.31.0",
   "module": "index.ts",
   "type": "module",
   "license": "MIT",
@@ -77,7 +77,7 @@
     "start": "bun keryx.ts start",
     "dev": "bun --watch keryx.ts start",
     "migrations": "bun run migrations.ts",
-    "test": "tsc && bun test",
+    "test": "tsc && bunx --bun vitest run",
     "compile": "bun build keryx.ts --compile --outfile keryx",
     "lint": "tsc && biome check .",
     "format": "tsc && biome check --write .",
@@ -100,11 +100,18 @@
   "peerDependencies": {
     "drizzle-orm": "^0.45.2",
     "drizzle-zod": "^0.8.3",
+    "vitest": "^4.1.9",
     "zod": "^4.3.6"
   },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@types/bun": "^1.3.12",
     "drizzle-kit": "^0.31.10",
-    "drizzle-zod": "^0.8.3"
+    "drizzle-zod": "^0.8.3",
+    "vitest": "^4.1.9"
   }
 }

package/servers/web.ts

@@ -3,7 +3,7 @@ import { parse } from "node:url";
 import type { ServerWebSocket } from "bun";
 import { api, logger } from "../api";
 import { type HTTP_METHOD } from "../classes/Action";
-import { Connection } from "../classes/Connection";
+import { CONNECTION_TYPE, Connection } from "../classes/Connection";
 import { Server } from "../classes/Server";
 import { StreamingResponse } from "../classes/StreamingResponse";
 import { ErrorStatusCodes, ErrorType, TypedError } from "../classes/TypedError";
@@ -28,6 +28,7 @@ import {
   handleWebsocketSubscribe,
   handleWebsocketUnsubscribe,
 } from "../util/webSocket";
+import { shouldWarnStackLeak } from "../util/webStackLeakWarning";
 import { handleStaticFile } from "../util/webStaticFiles";
 
 /**
@@ -151,6 +152,12 @@ export class WebServer extends Server<ReturnType<typeof Bun.serve>> {
       this.url = `http://${config.server.web.host}:${this.port}`;
       const startMessage = `started server @ ${this.url}`;
       logger.info(logger.colorize ? ansi.bgBlue(startMessage) : startMessage);
+
+      const stackLeakWarning = shouldWarnStackLeak(
+        config.server.web.host,
+        config.server.web.includeStackInErrors,
+      );
+      if (stackLeakWarning) logger.warn(stackLeakWarning);
     } catch (e) {
       await Bun.sleep(1000);
       startupAttempts++;
@@ -164,7 +171,10 @@ export class WebServer extends Server<ReturnType<typeof Bun.serve>> {
       // Send close frame to all WebSocket connections
       const wsConnections: ServerWebSocket[] = [];
       for (const connection of api.connections.connections.values()) {
-        if (connection.type === "websocket" && connection.rawConnection) {
+        if (
+          connection.type === CONNECTION_TYPE.WEBSOCKET &&
+          connection.rawConnection
+        ) {
           wsConnections.push(connection.rawConnection);
         }
       }
@@ -187,7 +197,7 @@ export class WebServer extends Server<ReturnType<typeof Bun.serve>> {
         const deadline = Date.now() + drainTimeout;
         while (Date.now() < deadline) {
           const remaining = [...api.connections.connections.values()].filter(
-            (c) => c.type === "websocket",
+            (c) => c.type === CONNECTION_TYPE.WEBSOCKET,
           );
           if (remaining.length === 0) break;
           await Bun.sleep(50);
@@ -195,7 +205,7 @@ export class WebServer extends Server<ReturnType<typeof Bun.serve>> {
 
         // Force-destroy any lingering WebSocket connections
         const lingering = [...api.connections.connections.values()].filter(
-          (c) => c.type === "websocket",
+          (c) => c.type === CONNECTION_TYPE.WEBSOCKET,
         );
         for (const connection of lingering) {
           connection.destroy();
@@ -367,7 +377,13 @@ export class WebServer extends Server<ReturnType<typeof Bun.serve>> {
   async handleWebSocketConnectionOpen(ws: ServerWebSocket) {
     //@ts-expect-error (ws.data is not defined in the bun types)
     const { ip, id, wsConnectionId } = ws.data;
-    const connection = new Connection("websocket", ip, wsConnectionId, ws, id);
+    const connection = new Connection(
+      CONNECTION_TYPE.WEBSOCKET,
+      ip,
+      wsConnectionId,
+      ws,
+      id,
+    );
     connection.onBroadcastMessageReceived = function (payload: PubSubMessage) {
       ws.send(JSON.stringify({ message: payload }));
     };
@@ -513,7 +529,7 @@ export class WebServer extends Server<ReturnType<typeof Bun.serve>> {
     let errorStatusCode = 500;
     const httpMethod = req.method?.toUpperCase() as HTTP_METHOD;
 
-    const connection = new Connection("web", ip, id);
+    const connection = new Connection(CONNECTION_TYPE.WEB, ip, id);
 
     if (
       config.server.web.correlationId.header &&

package/templates/generate/test.ts.mustache

@@ -1,4 +1,4 @@
-import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
 import { api } from "keryx";
 
 beforeAll(async () => {

package/templates/scaffold/index.ts.mustache

@@ -4,7 +4,7 @@ import { api } from "keryx";
 // actions, initializers, channels, etc. from this directory.
 // Every entry point (keryx.ts, migrations.ts, test setup) should
 // `import "./index"` to ensure rootDir is set before anything runs.
-api.rootDir = import.meta.dir;
+api.rootDir = import.meta.dirname;
 
 // Re-export everything from keryx for convenience
 export * from "keryx";

package/templates/scaffold/vitest.config.ts.mustache

@@ -0,0 +1,18 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["__tests__/**/*.test.ts"],
+    globals: false,
+    // Run on the Bun runtime via `bunx --bun vitest`. The forks pool keeps
+    // Node/Bun process APIs available; file parallelism is disabled so test
+    // files that boot the server don't race on the shared database/Redis.
+    pool: "forks",
+    fileParallelism: false,
+    testTimeout: 15_000,
+    hookTimeout: 60_000,
+    // zod (and other CJS deps consumed via named imports) must be transformed
+    // by Vite so the named-export interop works under the Bun runtime.
+    server: { deps: { inline: ["zod"] } },
+  },
+});

package/testing/index.ts

@@ -1,4 +1,4 @@
-import { afterAll, beforeAll } from "bun:test";
+import { afterAll, beforeAll } from "vitest";
 import { api } from "../api";
 import type { WebServer } from "../servers/web";
 

package/testing/websocket.ts

@@ -1,4 +1,4 @@
-import { expect } from "bun:test";
+import { expect } from "vitest";
 import { api } from "../api";
 import type { WebServer } from "../servers/web";
 

package/util/cli.ts

@@ -1,7 +1,7 @@
 import os from "node:os";
 import { Command } from "commander";
 import path from "path";
-import { Action, api, Connection, RUN_MODE } from "../api";
+import { Action, api, CONNECTION_TYPE, Connection, RUN_MODE } from "../api";
 import { ExitCode } from "./../classes/ExitCode";
 import { TypedError } from "./../classes/TypedError";
 import { config } from "../config";
@@ -274,7 +274,7 @@ async function runActionViaCLI(options: Record<string, string>, command: any) {
   await api.start(RUN_MODE.CLI);
 
   const id = "cli:" + os.userInfo().username;
-  const connection = new Connection("cli", id);
+  const connection = new Connection(CONNECTION_TYPE.CLI, id);
   const params: Record<string, unknown> = { ...options };
 
   const { response, error } = await connection.act(actionName, params);

package/util/componentRegistry.ts

@@ -24,13 +24,13 @@ export interface ComponentDef {
 }
 
 const generateTemplatesDir = path.join(
-  import.meta.dir,
+  import.meta.dirname,
   "..",
   "templates",
   "generate",
 );
 const scaffoldTemplatesDir = path.join(
-  import.meta.dir,
+  import.meta.dirname,
   "..",
   "templates",
   "scaffold",

package/util/mcpServer.ts

@@ -13,7 +13,7 @@ import * as z4mini from "zod/v4-mini";
 import { api, logger } from "../api";
 import type { Action } from "../classes/Action";
 import { MCP_RESPONSE_FORMAT } from "../classes/Action";
-import { Connection } from "../classes/Connection";
+import { CONNECTION_TYPE, Connection } from "../classes/Connection";
 import { StreamingResponse } from "../classes/StreamingResponse";
 import { ErrorType, TypedError } from "../classes/TypedError";
 import { config } from "../config";
@@ -60,7 +60,7 @@ export async function createMcpConnection(extra: {
   const authInfo = extra.authInfo;
   const clientIp = (authInfo?.extra?.ip as string) || "unknown";
   const connection = new Connection(
-    "mcp",
+    CONNECTION_TYPE.MCP,
     clientIp,
     randomUUID(),
     undefined,

package/util/oauthHandlers/authorize.ts

@@ -1,7 +1,7 @@
 import { randomUUID } from "crypto";
 import { api } from "../../api";
 import type { Action, OAuthActionResponse } from "../../classes/Action";
-import { Connection } from "../../classes/Connection";
+import { CONNECTION_TYPE, Connection } from "../../classes/Connection";
 import { config } from "../../config";
 import { redirectUrisMatch } from "../oauth";
 import {
@@ -78,7 +78,7 @@ async function runAuthAction(
   }
 
   const connection = new Connection(
-    "oauth",
+    CONNECTION_TYPE.OAUTH,
     isSignup ? "oauth-signup" : "oauth-login",
   );
   try {

package/util/oauthTemplates.ts

@@ -20,7 +20,7 @@ export type OAuthTemplates = {
   lionSvg: string;
 };
 
-const frameworkTemplatesDir = import.meta.dir + "/../templates";
+const frameworkTemplatesDir = import.meta.dirname + "/../templates";
 
 /**
  * Resolve a template file, checking the user's rootDir first, then falling back

package/util/safeCompare.ts

@@ -0,0 +1,24 @@
+import { timingSafeEqual } from "node:crypto";
+
+/**
+ * Constant-time UTF-8 string comparison. Pads both inputs to a common length
+ * before delegating to `crypto.timingSafeEqual` so the comparison time does
+ * not leak the expected length via early-return, then verifies the original
+ * lengths matched. Use this whenever you compare a user-supplied secret
+ * (password, API key, CSRF token, signed cookie value, …) against an expected
+ * value — naive `===` leaks bytes via short-circuit timing.
+ *
+ * @param a - First string.
+ * @param b - Second string.
+ * @returns `true` when the strings are byte-identical, `false` otherwise.
+ */
+export function safeCompare(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;
+}

package/util/scaffold.ts

@@ -66,7 +66,7 @@ export async function generateOAuthTemplateContents(): Promise<
     "oauth-common.css",
     "lion.svg",
   ];
-  const sourceDir = path.join(import.meta.dir, "..", "templates");
+  const sourceDir = path.join(import.meta.dirname, "..", "templates");
 
   for (const file of oauthTemplates) {
     const content = await Bun.file(path.join(sourceDir, file)).text();
@@ -85,7 +85,7 @@ export async function generateConfigFileContents(): Promise<
   Map<string, string>
 > {
   const result = new Map<string, string>();
-  const configDir = path.join(import.meta.dir, "..", "config");
+  const configDir = path.join(import.meta.dirname, "..", "config");
   const glob = new Glob("**/*.ts");
 
   for await (const file of glob.scan(configDir)) {
@@ -140,7 +140,7 @@ export async function generateBuiltinActionContents(): Promise<
 > {
   const result = new Map<string, string>();
   const builtinActions = ["status.ts", "swagger.ts"];
-  const actionsDir = path.join(import.meta.dir, "..", "actions");
+  const actionsDir = path.join(import.meta.dirname, "..", "actions");
 
   for (const file of builtinActions) {
     let content = await Bun.file(path.join(actionsDir, file)).text();
@@ -318,6 +318,7 @@ export async function scaffoldProject(
           start: "bun keryx.ts start",
           dev: "bun --watch keryx.ts start",
           ...(options.includeDb ? { migrations: "bun run migrations.ts" } : {}),
+          test: "tsc && bunx --bun vitest run",
           lint: "tsc && biome check .",
           format: "tsc && biome check --write .",
         },
@@ -334,6 +335,7 @@ export async function scaffoldProject(
         devDependencies: {
           "@biomejs/biome": "^2.4.8",
           "@types/bun": "latest",
+          vitest: "^4.1.9",
           ...(options.includeDb ? { "drizzle-kit": "^0.20.18" } : {}),
         },
       },
@@ -343,6 +345,7 @@ export async function scaffoldProject(
   );
 
   await write("tsconfig.json", generateTsconfigContents());
+  await writeTemplate("vitest.config.ts", "vitest.config.ts.mustache");
   await write(
     "biome.json",
     JSON.stringify(

package/util/webBasicAuth.ts

@@ -1,16 +1,4 @@
-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;
-}
+import { safeCompare } from "./safeCompare";
 
 /**
  * Verifies an HTTP Basic auth `Authorization` header against expected credentials
@@ -47,7 +35,7 @@ export function verifyBasicAuth(
   const user = decoded.slice(0, idx);
   const pass = decoded.slice(idx + 1);
 
-  const userOk = timingSafeStringEqual(user, expectedUsername);
-  const passOk = timingSafeStringEqual(pass, expectedPassword);
+  const userOk = safeCompare(user, expectedUsername);
+  const passOk = safeCompare(pass, expectedPassword);
   return userOk && passOk;
 }

package/util/webStackLeakWarning.ts

@@ -0,0 +1,23 @@
+/**
+ * Returns a warning message when the web server is configured to leak stack
+ * traces to remote callers, otherwise `null`. Stack traces in error responses
+ * leak deployment paths and code structure, which is fine on a developer's
+ * laptop but a footgun on a publicly reachable host.
+ */
+export function shouldWarnStackLeak(
+  host: string,
+  includeStackInErrors: boolean,
+): string | null {
+  if (!includeStackInErrors) return null;
+  const isLocalBind =
+    host === "localhost" ||
+    host === "127.0.0.1" ||
+    host === "::1" ||
+    host === "[::1]";
+  if (isLocalBind) return null;
+  return (
+    `⚠️  Stack traces are enabled in error responses (host=${host}). ` +
+    `This leaks internal paths and code structure. ` +
+    `Set NODE_ENV=production or WEB_SERVER_INCLUDE_STACK_IN_ERRORS=false before exposing this server publicly.`
+  );
+}