feat: add authNext and deprecate legacy auth (#883)

* feat: add authNext and deprecate legacy auth

* docs: update docs

* chore: docs update

* chore: fix default.ts

Author: omeraplak

.changeset/floppy-dogs-hear.md

@@ -0,0 +1,41 @@
+---
+"@voltagent/server-core": patch
+"@voltagent/server-hono": patch
+---
+
+feat: add authNext and deprecate legacy auth
+
+Add a new `authNext` policy that splits routes into public, console, and user access. All routes are protected by default; use `publicRoutes` to opt out.
+
+AuthNext example:
+
+```ts
+import { jwtAuth } from "@voltagent/server-core";
+import { honoServer } from "@voltagent/server-hono";
+
+const server = honoServer({
+  authNext: {
+    provider: jwtAuth({ secret: process.env.JWT_SECRET! }),
+    publicRoutes: ["GET /health"],
+  },
+});
+```
+
+Behavior summary:
+
+- When `authNext` is set, all routes are private by default.
+- Console endpoints (agents, workflows, tools, docs, observability, updates) require a Console Access Key.
+- Execution endpoints require a user token (JWT).
+
+Console access uses `VOLTAGENT_CONSOLE_ACCESS_KEY`:
+
+```bash
+VOLTAGENT_CONSOLE_ACCESS_KEY=your-console-key
+```
+
+```bash
+curl http://localhost:3141/agents \
+  -H "x-console-access-key: your-console-key"
+```
+
+Legacy `auth` remains supported but is deprecated. Use `authNext` for new integrations.

examples/with-auth/src/index.ts

@@ -1,7 +1,7 @@
 import { openai } from "@ai-sdk/openai";
 import { Agent, Memory, VoltAgent } from "@voltagent/core";
 import { createPinoLogger } from "@voltagent/logger";
-import { honoServer, jwtAuth } from "@voltagent/server-hono";
+import { authNext, honoServer, jwtAuth } from "@voltagent/server-hono";
 
 // Import Memory and TelemetryStore from core
 import { AiSdkEmbeddingAdapter, InMemoryVectorAdapter } from "@voltagent/core";
@@ -34,11 +34,12 @@ const agent = new Agent({
 new VoltAgent({
   agents: { agent },
   server: honoServer({
-    auth: jwtAuth({
-      secret: "super-secret",
-      defaultPrivate: true,
-      publicRoutes: ["GET /api/health"],
-    }),
+    authNext: {
+      provider: jwtAuth({
+        secret: "super-secret",
+      }),
+      publicRoutes: ["/api/health"],
+    },
     configureApp: (app) => {
       app.get("/api/health", (c) => c.json({ status: "ok" }));
       app.get("/api/protected", (c) => c.json({ message: "This is protected" }));

packages/server-core/src/auth/defaults.ts

@@ -3,10 +3,9 @@
  */
 
 /**
- * Routes that don't require authentication by default
- * These are typically used by VoltOps and management tools
+ * Routes that don't require authentication by default (legacy auth)
  */
-export const DEFAULT_PUBLIC_ROUTES = [
+export const DEFAULT_LEGACY_PUBLIC_ROUTES = [
   // Agent management endpoints (VoltOps uses these)
   "GET /agents", // List all agents
   "GET /agents/:id", // Get agent details
@@ -32,6 +31,51 @@ export const DEFAULT_PUBLIC_ROUTES = [
   "GET /agents/:id/card",
 ];
 
+// Backward compatibility alias
+export const DEFAULT_PUBLIC_ROUTES = DEFAULT_LEGACY_PUBLIC_ROUTES;
+
+/**
+ * Routes that require console access when authNext is enabled
+ */
+export const DEFAULT_CONSOLE_ROUTES = [
+  // Agent management endpoints (VoltOps uses these)
+  "GET /agents", // List all agents
+  "GET /agents/:id", // Get agent details
+
+  // Workflow management endpoints
+  "GET /workflows", // List all workflows
+  "GET /workflows/:id", // Get workflow details
+
+  // Tool management endpoints
+  "GET /tools", // List all tools
+
+  // API documentation
+  "GET /doc", // OpenAPI spec
+  "GET /ui", // Swagger UI
+  "GET /", // Landing page
+
+  // MCP (public discovery)
+  "GET /mcp/servers",
+  "GET /mcp/servers/:serverId",
+  "GET /mcp/servers/:serverId/tools",
+
+  // A2A (agent-to-agent discovery)
+  "GET /agents/:id/card",
+
+  "GET /agents/:id/history",
+  "GET /workflows/executions",
+  "GET /workflows/:id/executions/:executionId/state",
+  "GET /api/logs",
+  "POST /setup-observability",
+  "/observability/*",
+  "GET /updates",
+  "POST /updates",
+  "POST /updates/:packageName",
+  "WS /ws",
+  "WS /ws/logs",
+  "WS /ws/observability/**",
+];
+
 /**
  * Routes that require authentication by default
  * These endpoints execute operations, modify state, or access sensitive data
@@ -171,7 +215,7 @@ export function requiresAuth(
   defaultPrivate?: boolean,
 ): boolean {
   // Check if it's a default public route
-  for (const publicRoute of DEFAULT_PUBLIC_ROUTES) {
+  for (const publicRoute of DEFAULT_LEGACY_PUBLIC_ROUTES) {
     if (publicRoute.includes(" ")) {
       // Route with method specified
       const [routeMethod, routePath] = publicRoute.split(" ");

packages/server-core/src/auth/index.ts

@@ -5,6 +5,7 @@
 
 export * from "./types";
 export * from "./defaults";
+export * from "./next";
 export * from "./utils";
 
 // Export auth providers

packages/server-core/src/auth/next.spec.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+import { resolveAuthNextAccess } from "./next";
+import type { AuthProvider } from "./types";
+
+const mockProvider: AuthProvider = {
+  type: "jwt",
+  verifyToken: async () => ({ id: "user-1" }),
+  publicRoutes: ["GET /provider-public"],
+};
+
+describe("resolveAuthNextAccess", () => {
+  it("treats explicit publicRoutes as public", () => {
+    const config = { provider: mockProvider, publicRoutes: ["GET /health"] };
+    expect(resolveAuthNextAccess("GET", "/health", config)).toBe("public");
+  });
+
+  it("treats provider publicRoutes as public", () => {
+    const config = { provider: mockProvider };
+    expect(resolveAuthNextAccess("GET", "/provider-public", config)).toBe("public");
+  });
+
+  it("treats default console routes as console", () => {
+    const config = { provider: mockProvider };
+    expect(resolveAuthNextAccess("GET", "/agents", config)).toBe("console");
+  });
+
+  it("treats non-console routes as user", () => {
+    const config = { provider: mockProvider };
+    expect(resolveAuthNextAccess("POST", "/agents/test-agent/text", config)).toBe("user");
+  });
+
+  it("treats websocket test connection as console", () => {
+    const config = { provider: mockProvider };
+    expect(resolveAuthNextAccess("WS", "/ws", config)).toBe("console");
+  });
+
+  it("allows publicRoutes to override console routes", () => {
+    const config = { provider: mockProvider, publicRoutes: ["GET /agents"] };
+    expect(resolveAuthNextAccess("GET", "/agents", config)).toBe("public");
+  });
+
+  it("uses custom consoleRoutes when provided", () => {
+    const config = { provider: mockProvider, consoleRoutes: ["GET /custom-console"] };
+    expect(resolveAuthNextAccess("GET", "/custom-console", config)).toBe("console");
+    expect(resolveAuthNextAccess("GET", "/agents", config)).toBe("user");
+  });
+});

packages/server-core/src/auth/next.ts

@@ -0,0 +1,66 @@
+import { DEFAULT_CONSOLE_ROUTES, pathMatches } from "./defaults";
+import type { AuthProvider } from "./types";
+
+export type AuthNextAccess = "public" | "console" | "user";
+
+export interface AuthNextRoutesConfig {
+  publicRoutes?: string[];
+  consoleRoutes?: string[];
+}
+
+export interface AuthNextConfig<TRequest = any> extends AuthNextRoutesConfig {
+  provider: AuthProvider<TRequest>;
+}
+
+export function isAuthNextConfig<TRequest>(
+  value: AuthProvider<TRequest> | AuthNextConfig<TRequest>,
+): value is AuthNextConfig<TRequest> {
+  return typeof (value as AuthNextConfig<TRequest>).provider !== "undefined";
+}
+
+export function normalizeAuthNextConfig<TRequest>(
+  value: AuthProvider<TRequest> | AuthNextConfig<TRequest>,
+): AuthNextConfig<TRequest> {
+  return isAuthNextConfig(value) ? value : { provider: value };
+}
+
+function routeMatches(method: string, path: string, routePattern: string): boolean {
+  const parts = routePattern.split(" ");
+  if (parts.length === 2) {
+    const [routeMethod, routePath] = parts;
+    if (method.toUpperCase() !== routeMethod.toUpperCase()) {
+      return false;
+    }
+    return pathMatches(path, routePath);
+  }
+
+  return pathMatches(path, routePattern);
+}
+
+function matchesAnyRoute(method: string, path: string, routes?: string[]): boolean {
+  if (!routes || routes.length === 0) {
+    return false;
+  }
+
+  return routes.some((route) => routeMatches(method, path, route));
+}
+
+export function resolveAuthNextAccess<TRequest>(
+  method: string,
+  path: string,
+  authNext: AuthNextConfig<TRequest> | AuthProvider<TRequest>,
+): AuthNextAccess {
+  const config = normalizeAuthNextConfig(authNext);
+  const publicRoutes = [...(config.publicRoutes ?? []), ...(config.provider.publicRoutes ?? [])];
+
+  if (matchesAnyRoute(method, path, publicRoutes)) {
+    return "public";
+  }
+
+  const consoleRoutes = config.consoleRoutes ?? DEFAULT_CONSOLE_ROUTES;
+  if (matchesAnyRoute(method, path, consoleRoutes)) {
+    return "console";
+  }
+
+  return "user";
+}

packages/server-core/src/auth/utils.ts

@@ -52,6 +52,9 @@ export function isDevRequest(req: Request): boolean {
  * // Production with console key
  * NODE_ENV=production + x-console-access-key=valid-key → true
  *
+ * // Production with console key in query param
+ * NODE_ENV=production + ?key=valid-key → true
+ *
  * // Production without key
  * NODE_ENV=production + no key → false
  *
@@ -68,9 +71,11 @@ export function hasConsoleAccess(req: Request): boolean {
 
   // 2. Console Access Key check (for production)
   const consoleKey = req.headers.get("x-console-access-key");
+  const url = new URL(req.url, "http://localhost");
+  const queryKey = url.searchParams.get("key");
   const configuredKey = process.env.VOLTAGENT_CONSOLE_ACCESS_KEY;
 
-  if (configuredKey && consoleKey === configuredKey) {
+  if (configuredKey && (consoleKey === configuredKey || queryKey === configuredKey)) {
     return true;
   }