@juspay/neurolink 12.48.0 → 12.48.2

package/dist/cli/commands/serve.d.ts

@@ -36,6 +36,11 @@ export declare class ServeCommandFactory {
      * Returns a mutable reference wrapper so signal handlers always access the current server.
      */
     private static createAndStartServer;
+    /**
+     * Put every route except health behind the API key(s) in
+     * NEUROLINK_SERVER_API_KEY. Must run before the routes are registered.
+     */
+    private static applyApiKeyAuth;
     /**
      * Save server state and print the startup info banner.
      */

package/dist/cli/commands/serve.js

@@ -16,7 +16,7 @@ import { NeuroLink } from "../../neurolink.js";
 import { ConfigurationError, ServerStartError, } from "../../server/errors.js";
 import { withTimeout } from "../../utils/errorHandling.js";
 import { logger } from "../../utils/logger.js";
-import { formatUptime, isProcessRunning, StateFileManager, } from "../utils/serverUtils.js";
+import { clearStateOnExit, createServerApiKeyMiddleware, formatUptime, isOtherServerRunning, isProcessRunning, readServerApiKeys, resolveServerPort, SERVER_API_KEY_ENV, StateFileManager, } from "../utils/serverUtils.js";
 // ============================================
 // State Management
 // ============================================
@@ -143,6 +143,8 @@ export class ServeCommandFactory {
             command: "serve [subcommand]",
             describe: "Start NeuroLink HTTP server with server adapters",
             builder: (yargs) => {
+                // The server options carry no yargs defaults: a default would always
+                // win over the --config file. Defaults are applied after merging.
                 return yargs
                     .command("status", "Show server status", (yargs) => ServeCommandFactory.buildStatusOptions(yargs), (argv) => ServeCommandFactory.executeStatus(argv))
                     .command("voice", "Start the real-time voice assistant server (OpenAI Realtime / Gemini Live)", (yargs) => yargs.option("port", {
@@ -157,43 +159,36 @@ export class ServeCommandFactory {
                     .option("port", {
                     type: "number",
                     alias: "p",
-                    default: 3000,
-                    description: "Port to listen on",
+                    description: "Port to listen on (default: config file, then $PORT, then 3000)",
                 })
                     .option("host", {
                     type: "string",
                     alias: "H",
-                    default: "0.0.0.0",
-                    description: "Host to bind to",
+                    description: "Host to bind to (default: 0.0.0.0)",
                 })
                     .option("framework", {
                     type: "string",
                     alias: "f",
                     choices: ["hono", "express", "fastify", "koa"],
-                    default: "hono",
-                    description: "Web framework to use (hono recommended)",
+                    description: "Web framework to use (default: hono, recommended)",
                 })
                     .option("basePath", {
                     type: "string",
                     alias: "b",
-                    default: "/api",
-                    description: "Base path for all routes",
+                    description: "Base path for all routes (default: /api)",
                 })
                     .option("cors", {
                     type: "boolean",
-                    default: true,
-                    description: "Enable CORS middleware",
+                    description: "Enable CORS middleware (default: true)",
                 })
                     .option("rate-limit", {
                     type: "number",
                     alias: "rateLimit",
-                    default: 100,
-                    description: "Rate limit (requests per 15 min window, 0 to disable)",
+                    description: "Rate limit (requests per 15 min window, 0 to disable; default: 100)",
                 })
                     .option("swagger", {
                     type: "boolean",
-                    default: false,
-                    description: "Enable OpenAPI/Swagger documentation",
+                    description: "Enable OpenAPI/Swagger documentation (default: false)",
                 })
                     .option("config", {
                     type: "string",
@@ -224,6 +219,7 @@ export class ServeCommandFactory {
                     .example("neurolink serve --cors --rate-limit 50", "Start server with CORS and rate limiting (50 req/15min)")
                     .example("neurolink serve --swagger", "Start server with OpenAPI documentation enabled")
                     .example("neurolink serve --watch", "Start server in watch mode (restart on changes)")
+                    .example("NEUROLINK_SERVER_API_KEY=secret neurolink serve", "Require 'Authorization: Bearer secret' (or X-API-Key) on every route except health")
                     .example("neurolink serve status", "Show server status")
                     .help();
             },
@@ -266,7 +262,7 @@ export class ServeCommandFactory {
             // Load config file if provided
             const fileConfig = ServeCommandFactory.loadFileConfig(argv, spinner);
             // Merge CLI args with file config (CLI takes precedence)
-            const port = argv.port ?? fileConfig.port ?? 3000;
+            const port = resolveServerPort(argv.port, fileConfig.port);
             const host = argv.host ?? fileConfig.host ?? "0.0.0.0";
             const framework = argv.framework ?? fileConfig.framework ?? "hono";
             const basePath = argv.basePath ?? fileConfig.basePath ?? "/api";
@@ -307,7 +303,7 @@ export class ServeCommandFactory {
      */
     static guardAlreadyRunning(spinner) {
         const existingState = loadServeState();
-        if (existingState && isProcessRunning(existingState.pid)) {
+        if (existingState && isOtherServerRunning(existingState.pid)) {
             if (spinner) {
                 spinner.fail(chalk.red(`Server already running on port ${existingState.port} (PID: ${existingState.pid})`));
             }
@@ -391,6 +387,7 @@ export class ServeCommandFactory {
                 config: opts.serverConfig,
             }),
         };
+        ServeCommandFactory.applyApiKeyAuth(serverRef.current, opts.basePath);
         registerAllRoutes(serverRef.current, opts.basePath);
         if (spinner) {
             spinner.text = "Initializing server...";
@@ -399,6 +396,16 @@ export class ServeCommandFactory {
         await withTimeout(serverRef.current.start(), 30000, new ServerStartError("Server startup timed out after 30 seconds", undefined, opts.port, opts.host));
         return serverRef;
     }
+    /**
+     * Put every route except health behind the API key(s) in
+     * NEUROLINK_SERVER_API_KEY. Must run before the routes are registered.
+     */
+    static applyApiKeyAuth(server, basePath) {
+        const apiKeys = readServerApiKeys();
+        if (apiKeys.length > 0) {
+            server.registerMiddleware(createServerApiKeyMiddleware(apiKeys, basePath));
+        }
+    }
     /**
      * Save server state and print the startup info banner.
      */
@@ -413,6 +420,7 @@ export class ServeCommandFactory {
             configFile: opts.argv.config,
         };
         saveServeState(state);
+        clearStateOnExit(clearServeState);
         if (spinner) {
             spinner.succeed(chalk.green("NeuroLink server started successfully"));
         }
@@ -432,6 +440,7 @@ export class ServeCommandFactory {
             rateLimitValue,
             swaggerEnabled,
             watchEnabled: opts.argv.watch ?? false,
+            authEnabled: readServerApiKeys().length > 0,
         });
         return state;
     }
@@ -458,6 +467,7 @@ export class ServeCommandFactory {
         if (info.watchEnabled) {
             logger.always(`  Watch Mode:  ${chalk.green("enabled")}`);
         }
+        logger.always(`  API Key:     ${info.authEnabled ? chalk.green("required (health routes exempt)") : chalk.yellow(`disabled — set ${SERVER_API_KEY_ENV} before exposing this server`)}`);
         logger.always("");
         logger.always(chalk.bold("Available Endpoints:"));
         logger.always(chalk.gray("  Health & Monitoring:"));
@@ -507,6 +517,7 @@ export class ServeCommandFactory {
                     framework: ctx.framework,
                     config: ctx.serverConfig,
                 });
+                ServeCommandFactory.applyApiKeyAuth(newServer, ctx.basePath);
                 registerNewRoutes(newServer, ctx.basePath);
                 // Initialize and start with timeouts
                 await withTimeout(newServer.initialize(), 30000, new ServerStartError("Server initialization timed out during restart", undefined, ctx.port, ctx.host));

package/dist/cli/commands/server.js

@@ -9,7 +9,7 @@ import path from "path";
 import { logger } from "../../utils/logger.js";
 import { NeuroLink } from "../../neurolink.js";
 import { withTimeout } from "../../utils/errorHandling.js";
-import { isProcessRunning, formatUptime, ensureStateDir, getNeuroLinkDir, } from "../utils/serverUtils.js";
+import { isProcessRunning, formatUptime, ensureStateDir, getNeuroLinkDir, clearStateOnExit, createServerApiKeyMiddleware, isOtherServerRunning, readServerApiKeys, resolveServerPort, SERVER_API_KEY_ENV, } from "../utils/serverUtils.js";
 // ============================================
 // State Management
 // ============================================
@@ -160,8 +160,7 @@ export class ServerCommandFactory {
             .option("port", {
             type: "number",
             alias: "p",
-            default: 3000,
-            description: "Port to listen on",
+            description: "Port to listen on (default: $PORT, then 3000)",
         })
             .option("host", {
             type: "string",
@@ -344,7 +343,7 @@ export class ServerCommandFactory {
         try {
             // Check if server is already running
             const existingState = loadServerState();
-            if (existingState && isProcessRunning(existingState.pid)) {
+            if (existingState && isOtherServerRunning(existingState.pid)) {
                 if (spinner) {
                     spinner.fail(chalk.red(`Server already running on port ${existingState.port} (PID: ${existingState.pid})`));
                 }
@@ -355,12 +354,13 @@ export class ServerCommandFactory {
             const neurolink = new NeuroLink();
             // Dynamically import server module
             const { createServer, registerAllRoutes } = await import("../../server/index.js");
+            const port = resolveServerPort(argv.port);
             const framework = (argv.framework ?? "hono");
             // Create server
             const server = await createServer(neurolink, {
                 framework,
                 config: {
-                    port: argv.port ?? 3000,
+                    port,
                     host: argv.host ?? "0.0.0.0",
                     basePath: argv.basePath ?? "/api",
                     cors: {
@@ -372,6 +372,11 @@ export class ServerCommandFactory {
                     disableBuiltInHealth: true, // We register health routes separately
                 },
             });
+            // API key (if configured) must be registered ahead of the routes it guards
+            const apiKeys = readServerApiKeys();
+            if (apiKeys.length > 0) {
+                server.registerMiddleware(createServerApiKeyMiddleware(apiKeys, argv.basePath ?? "/api"));
+            }
             // Register all routes
             registerAllRoutes(server, argv.basePath ?? "/api");
             // Initialize and start with timeout
@@ -380,13 +385,14 @@ export class ServerCommandFactory {
             // Save state
             const state = {
                 pid: process.pid,
-                port: argv.port ?? 3000,
+                port,
                 host: argv.host ?? "0.0.0.0",
                 framework,
                 startTime: new Date().toISOString(),
                 basePath: argv.basePath ?? "/api",
             };
             saveServerState(state);
+            clearStateOnExit(clearServerState);
             if (spinner) {
                 spinner.succeed(chalk.green("Server started successfully"));
             }
@@ -396,6 +402,7 @@ export class ServerCommandFactory {
             logger.always(`  Framework: ${chalk.cyan(framework)}`);
             logger.always(`  Base Path: ${chalk.cyan(state.basePath)}`);
             logger.always(`  PID: ${chalk.cyan(state.pid)}`);
+            logger.always(`  API Key: ${apiKeys.length > 0 ? chalk.green("required (health routes exempt)") : chalk.yellow(`disabled — set ${SERVER_API_KEY_ENV} before exposing this server`)}`);
             logger.always(chalk.bold("\nAvailable Endpoints:"));
             logger.always(`  ${chalk.green("GET")}  ${state.basePath}/health`);
             logger.always(`  ${chalk.green("GET")}  ${state.basePath}/ready`);

package/dist/cli/utils/serverUtils.d.ts

@@ -2,6 +2,22 @@
  * Server Utilities for NeuroLink CLI
  * Shared utility functions for server management commands (serve.ts and server.ts)
  */
+import type { MiddlewareDefinition } from "../../types/index.js";
+export declare const DEFAULT_SERVER_PORT = 3000;
+/** Comma-separated API keys; when set, every route except health needs one. */
+export declare const SERVER_API_KEY_ENV = "NEUROLINK_SERVER_API_KEY";
+/**
+ * Resolve the listen port: --port, then the config file, then the PORT
+ * environment variable (what container platforms set), then 3000.
+ */
+export declare function resolveServerPort(cliPort?: number, filePort?: number): number;
+export declare function readServerApiKeys(): string[];
+/**
+ * Require one of `apiKeys` as `Authorization: Bearer <key>` or `X-API-Key`.
+ * Health probes stay open so orchestrators can reach them, and the dev
+ * playground header cannot bypass a key the operator configured.
+ */
+export declare function createServerApiKeyMiddleware(apiKeys: string[], basePath: string): MiddlewareDefinition;
 /**
  * Get the base directory for NeuroLink state files
  * @returns Path to ~/.neurolink directory
@@ -29,6 +45,18 @@ export declare function ensureStateDir(): void;
  * @returns true if the process is running, false otherwise
  */
 export declare function isProcessRunning(pid: number): boolean;
+/**
+ * Whether a saved server state belongs to a different, still-running process.
+ * A state naming our own PID is stale: a restarted container is PID 1 again
+ * and would otherwise refuse to start, believing it is already running.
+ */
+export declare function isOtherServerRunning(pid: number): boolean;
+/**
+ * Remove this process's state file however it exits. A graceful stop can end
+ * the process before its signal handler gets to clean up (once the listener
+ * closes, the event loop may drain), so this runs from the "exit" event.
+ */
+export declare function clearStateOnExit(clearState: () => void): void;
 /**
  * Format a duration in milliseconds to a human-readable uptime string
  * @param ms - Duration in milliseconds

package/dist/cli/utils/serverUtils.js

@@ -2,9 +2,64 @@
  * Server Utilities for NeuroLink CLI
  * Shared utility functions for server management commands (serve.ts and server.ts)
  */
+import { timingSafeEqual } from "crypto";
 import fs from "fs";
 import os from "os";
 import path from "path";
+import { ConfigurationError } from "../../server/errors.js";
+import { createAuthMiddleware } from "../../server/middleware/auth.js";
+// ============================================
+// Listen Address & Access Control
+// ============================================
+export const DEFAULT_SERVER_PORT = 3000;
+/** Comma-separated API keys; when set, every route except health needs one. */
+export const SERVER_API_KEY_ENV = "NEUROLINK_SERVER_API_KEY";
+/**
+ * Resolve the listen port: --port, then the config file, then the PORT
+ * environment variable (what container platforms set), then 3000.
+ */
+export function resolveServerPort(cliPort, filePort) {
+    const envPort = process.env.PORT?.trim();
+    const port = cliPort ?? filePort ?? (envPort ? Number(envPort) : DEFAULT_SERVER_PORT);
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        throw new ConfigurationError(`Invalid port "${cliPort ?? filePort ?? envPort}": expected an integer between 0 and 65535`);
+    }
+    return port;
+}
+export function readServerApiKeys() {
+    return (process.env[SERVER_API_KEY_ENV] ?? "")
+        .split(",")
+        .map((key) => key.trim())
+        .filter((key) => key.length > 0);
+}
+/**
+ * Constant-time for equal lengths; a length mismatch returns early, which
+ * reveals only the key's length, never its content.
+ */
+const matchesKey = (key, token) => key.length === token.length && timingSafeEqual(key, token);
+/**
+ * Require one of `apiKeys` as `Authorization: Bearer <key>` or `X-API-Key`.
+ * Health probes stay open so orchestrators can reach them, and the dev
+ * playground header cannot bypass a key the operator configured.
+ */
+export function createServerApiKeyMiddleware(apiKeys, basePath) {
+    const keys = apiKeys.map((key) => Buffer.from(key, "utf8"));
+    return createAuthMiddleware({
+        type: "custom",
+        extractToken: (ctx) => {
+            const bearer = /^Bearer\s+(.+)$/i.exec(ctx.headers["authorization"] ?? "");
+            return bearer?.[1] ?? ctx.headers["x-api-key"] ?? null;
+        },
+        validate: async (token) => {
+            const candidate = Buffer.from(token, "utf8");
+            return keys.some((key) => matchesKey(key, candidate))
+                ? { id: "api-key" }
+                : null;
+        },
+        skipPaths: [`${basePath.replace(/\/+$/, "")}/health`],
+        skipDevPlayground: false,
+    });
+}
 // ============================================
 // State Directory Management
 // ============================================
@@ -56,6 +111,22 @@ export function isProcessRunning(pid) {
         return code === "EPERM";
     }
 }
+/**
+ * Whether a saved server state belongs to a different, still-running process.
+ * A state naming our own PID is stale: a restarted container is PID 1 again
+ * and would otherwise refuse to start, believing it is already running.
+ */
+export function isOtherServerRunning(pid) {
+    return pid !== process.pid && isProcessRunning(pid);
+}
+/**
+ * Remove this process's state file however it exits. A graceful stop can end
+ * the process before its signal handler gets to clean up (once the listener
+ * closes, the event loop may drain), so this runs from the "exit" event.
+ */
+export function clearStateOnExit(clearState) {
+    process.once("exit", clearState);
+}
 // ============================================
 // Time Formatting
 // ============================================

package/dist/server/abstract/baseServerAdapter.d.ts

@@ -7,7 +7,7 @@ import { EventEmitter } from "events";
 import type { ExternalServerManager } from "../../mcp/externalServerManager.js";
 import type { MCPToolRegistry } from "../../mcp/toolRegistry.js";
 import type { NeuroLink } from "../../neurolink.js";
-import type { MiddlewareDefinition, RedactionConfig, RequiredServerAdapterConfig, RequiredShutdownConfig, RouteDefinition, ServerAdapterConfig, ServerContext, ServerLifecycleState, ServerStatus, TrackedConnection } from "../../types/index.js";
+import type { MiddlewareDefinition, RedactionConfig, RequiredServerAdapterConfig, RequiredShutdownConfig, RouteDefinition, ServerAdapterConfig, ServerAdapterEvents, ServerContext, ServerLifecycleState, ServerStatus, TrackedConnection } from "../../types/index.js";
 /**
  * Abstract base class for server adapters
  * Provides common functionality and defines the interface for framework-specific implementations
@@ -22,6 +22,9 @@ export declare abstract class BaseServerAdapter extends EventEmitter {
     protected middlewares: MiddlewareDefinition[];
     protected isRunning: boolean;
     protected startTime?: Date;
+    private frameworkReady;
+    private pendingMiddlewares;
+    private pendingRouteKeys;
     protected lifecycleState: ServerLifecycleState;
     protected activeConnections: Map<string, TrackedConnection>;
     protected readonly shutdownConfig: RequiredShutdownConfig;
@@ -107,6 +110,23 @@ export declare abstract class BaseServerAdapter extends EventEmitter {
      * Register custom middleware
      */
     registerMiddleware(middleware: MiddlewareDefinition): void;
+    /**
+     * Log a failed request. A client error (a rejected API key, a failed
+     * validation) is routine traffic, so it is a one-line warning rather than
+     * an error with a stack trace that anyone could flood the logs with.
+     */
+    protected logRequestError(source: string, requestId: string | undefined, error: Error): void;
+    /**
+     * Notify "error" listeners about a failed request. EventEmitter throws when
+     * "error" has no listener, which inside a framework's error handler turns
+     * every failure into an empty 500, so emit only when someone is listening.
+     */
+    protected emitRequestError(payload: ServerAdapterEvents["error"]): void;
+    /**
+     * Hand queued registrations to the framework. A route re-registered under
+     * the same key before initialize() is replayed once, in its final form.
+     */
+    private flushPendingRegistrations;
     /**
      * Create request context from incoming request
      */

package/dist/server/abstract/baseServerAdapter.js

@@ -8,7 +8,7 @@ import { getMetricsAggregator, SpanSerializer, SpanStatus, SpanType, } from "../
 import { withTimeout } from "../../utils/errorHandling.js";
 import { logger } from "../../utils/logger.js";
 import { tryImport } from "../../utils/tryImport.js";
-import { DrainTimeoutError, InvalidLifecycleStateError, MissingDependencyError, ShutdownTimeoutError, } from "../errors.js";
+import { DrainTimeoutError, InvalidLifecycleStateError, MissingDependencyError, ServerAdapterError, ShutdownTimeoutError, } from "../errors.js";
 /**
  * Abstract base class for server adapters
  * Provides common functionality and defines the interface for framework-specific implementations
@@ -23,6 +23,12 @@ export class BaseServerAdapter extends EventEmitter {
     middlewares = [];
     isRunning = false;
     startTime;
+    // Adapters build their framework app lazily in initialize(), so routes and
+    // middleware registered before that are queued here and replayed once the
+    // app exists — middleware first, so it still guards those routes.
+    frameworkReady = false;
+    pendingMiddlewares = [];
+    pendingRouteKeys = new Set();
     // Lifecycle management properties
     lifecycleState = "uninitialized";
     activeConnections = new Map();
@@ -146,8 +152,11 @@ export class BaseServerAdapter extends EventEmitter {
         try {
             // Initialize framework-specific setup
             await this.initializeFramework();
+            this.frameworkReady = true;
             // Register built-in middleware
             this.registerBuiltInMiddleware();
+            // Replay what callers registered before the framework app existed
+            this.flushPendingRegistrations();
             // Register built-in routes
             await this.registerBuiltInRoutes();
             this.lifecycleState = "initialized";
@@ -183,7 +192,12 @@ export class BaseServerAdapter extends EventEmitter {
             logger.warn(`[ServerAdapter] Route ${routeKey} already exists, replacing`);
         }
         this.routes.set(routeKey, route);
-        this.registerFrameworkRoute(route);
+        if (this.frameworkReady) {
+            this.registerFrameworkRoute(route);
+        }
+        else {
+            this.pendingRouteKeys.add(routeKey);
+        }
         logger.debug(`[ServerAdapter] Registered route: ${routeKey}`, {
             description: route.description,
             streaming: route.streaming?.enabled,
@@ -231,12 +245,66 @@ export class BaseServerAdapter extends EventEmitter {
      */
     registerMiddleware(middleware) {
         this.middlewares.push(middleware);
-        this.registerFrameworkMiddleware(middleware);
+        if (this.frameworkReady) {
+            this.registerFrameworkMiddleware(middleware);
+        }
+        else {
+            this.pendingMiddlewares.push(middleware);
+        }
         logger.debug(`[ServerAdapter] Registered middleware: ${middleware.name}`, {
             order: middleware.order,
             paths: middleware.paths,
         });
     }
+    /**
+     * Log a failed request. A client error (a rejected API key, a failed
+     * validation) is routine traffic, so it is a one-line warning rather than
+     * an error with a stack trace that anyone could flood the logs with.
+     */
+    logRequestError(source, requestId, error) {
+        if (error instanceof ServerAdapterError && error.getHttpStatus() < 500) {
+            logger.warn(`[${source}] Request rejected`, {
+                requestId,
+                code: error.code,
+                error: error.message,
+            });
+            return;
+        }
+        logger.error(`[${source}] Request error`, {
+            requestId,
+            error: error.message,
+            stack: error.stack,
+        });
+    }
+    /**
+     * Notify "error" listeners about a failed request. EventEmitter throws when
+     * "error" has no listener, which inside a framework's error handler turns
+     * every failure into an empty 500, so emit only when someone is listening.
+     */
+    emitRequestError(payload) {
+        if (this.listenerCount("error") > 0) {
+            this.emit("error", payload);
+        }
+    }
+    /**
+     * Hand queued registrations to the framework. A route re-registered under
+     * the same key before initialize() is replayed once, in its final form.
+     */
+    flushPendingRegistrations() {
+        const middlewares = this.pendingMiddlewares;
+        const routeKeys = this.pendingRouteKeys;
+        this.pendingMiddlewares = [];
+        this.pendingRouteKeys = new Set();
+        for (const middleware of middlewares) {
+            this.registerFrameworkMiddleware(middleware);
+        }
+        for (const routeKey of routeKeys) {
+            const route = this.routes.get(routeKey);
+            if (route) {
+                this.registerFrameworkRoute(route);
+            }
+        }
+    }
     /**
      * Create request context from incoming request
      */

package/dist/server/adapters/expressAdapter.js

@@ -239,12 +239,8 @@ export class ExpressServerAdapter extends BaseServerAdapter {
         this.errorHandlerRegistered = true;
         this.app.use((error, req, res, _next) => {
             const requestId = req.headers["x-request-id"];
-            logger.error("[ExpressAdapter] Request error", {
-                requestId,
-                error: error.message,
-                stack: error.stack,
-            });
-            this.emit("error", {
+            this.logRequestError("ExpressAdapter", requestId, error);
+            this.emitRequestError({
                 requestId,
                 error,
                 timestamp: new Date(),

package/dist/server/adapters/fastifyAdapter.js

@@ -4,7 +4,7 @@
  * Fastify is known for its high performance and low overhead
  */
 import { logger } from "../../utils/logger.js";
-import { AlreadyRunningError, ServerStartError, ServerStopError, wrapError, } from "../errors.js";
+import { AlreadyRunningError, ServerAdapterError, ServerStartError, ServerStopError, wrapError, } from "../errors.js";
 import { withTimeout } from "../../utils/errorHandling.js";
 import { BaseServerAdapter } from "../abstract/baseServerAdapter.js";
 import { isErrorResponse } from "../utils/validation.js";
@@ -91,17 +91,23 @@ export class FastifyServerAdapter extends BaseServerAdapter {
         // Global error handler
         this.app.setErrorHandler((error, request, reply) => {
             const requestId = request.id;
-            logger.error("[FastifyAdapter] Request error", {
-                requestId,
-                error: error.message,
-                stack: error.stack,
-            });
-            this.emit("error", {
+            this.logRequestError("FastifyAdapter", requestId, error);
+            this.emitRequestError({
                 requestId,
                 error,
                 timestamp: new Date(),
             });
             // Handle different error types
+            if (error instanceof ServerAdapterError) {
+                reply.status(error.getHttpStatus()).send({
+                    error: { code: error.code, message: error.message },
+                    metadata: {
+                        requestId,
+                        timestamp: new Date().toISOString(),
+                    },
+                });
+                return;
+            }
             if (error.statusCode) {
                 reply.status(error.statusCode).send({
                     error: {

package/dist/server/adapters/honoAdapter.js

@@ -4,7 +4,7 @@
  * Hono is chosen for its performance, TypeScript-first design, and edge compatibility
  */
 import { logger } from "../../utils/logger.js";
-import { AlreadyRunningError, ServerStopError, wrapError } from "../errors.js";
+import { AlreadyRunningError, ServerAdapterError, ServerStopError, wrapError, } from "../errors.js";
 import { BaseServerAdapter } from "../abstract/baseServerAdapter.js";
 import { isErrorResponse } from "../utils/validation.js";
 /**
@@ -154,16 +154,21 @@ export class HonoServerAdapter extends BaseServerAdapter {
         // Global error handler
         this.app.onError((error, c) => {
             const requestId = c.req.header("X-Request-ID") || this.generateRequestId();
-            logger.error("[HonoAdapter] Request error", {
-                requestId,
-                error: error.message,
-                stack: error.stack,
-            });
-            this.emit("error", {
+            this.logRequestError("HonoAdapter", requestId, error);
+            this.emitRequestError({
                 requestId,
                 error,
                 timestamp: new Date(),
             });
+            if (error instanceof ServerAdapterError) {
+                return c.json({
+                    error: { code: error.code, message: error.message },
+                    metadata: {
+                        requestId,
+                        timestamp: new Date().toISOString(),
+                    },
+                }, error.getHttpStatus());
+            }
             if (error instanceof HTTPException) {
                 return c.json({
                     error: {

package/dist/server/adapters/koaAdapter.d.ts

@@ -18,6 +18,7 @@ export declare class KoaServerAdapter extends BaseServerAdapter {
     private rateLimitStore;
     private rateLimitCleanupInterval?;
     private sockets;
+    private registeredMiddleware;
     constructor(neurolink: NeuroLink, config?: ServerAdapterConfig);
     /**
      * Initialize Koa framework
@@ -52,6 +53,11 @@ export declare class KoaServerAdapter extends BaseServerAdapter {
      * Register middleware with Koa
      */
     protected registerFrameworkMiddleware(middleware: MiddlewareDefinition): void;
+    /**
+     * Run registered middleware in registration order, then continue to the
+     * router. Reads the list per request, so later registrations apply too.
+     */
+    private runRegisteredMiddleware;
     /**
      * Start the Koa server
      */