@economic/agents 1.2.2 → 1.3.1

package/README.md

@@ -270,6 +270,58 @@ execute: async (args, { experimental_context }) => {
 
 ---
 
+### JWT Authentication
+
+Authenticate WebSocket connections by implementing `getJwtAuthConfig` on your agent. When defined, JWT verification runs in `onConnect` — failed auth closes the connection, successful auth stores claims in `session`.
+
+```typescript
+import type { JWTPayload } from "jose";
+import { ChatAgentHarness, type AgentToolContext } from "@economic/agents";
+
+interface Session {
+  clientId: string;
+  userGuid: string;
+  agreementNumber: number;
+}
+
+export class MyAgent extends ChatAgentHarness<Env, RequestBody> {
+  getJwtAuthConfig(request: Request) {
+    const origin = request.headers.get("Origin") ?? "";
+    const isStaging = origin.includes("staging");
+
+    return {
+      allowedIssuers: isStaging
+        ? [/^https:\/\/auth\.staging\.example\.com$/]
+        : ["https://auth.example.com"],
+      audience: "my-api",
+      requiredScopes: ["read"],
+      getClaims: (payload: JWTPayload): Session => ({
+        clientId: payload.client_id as string,
+        userGuid: payload.user_guid as string,
+        agreementNumber: payload.agreement_number as number,
+      }),
+    };
+  }
+
+  // Session is available in tool context
+  getModel(ctx: AgentToolContext<RequestBody>) {
+    console.log(ctx.session); // { clientId, userGuid, agreementNumber }
+    return openai("gpt-4o");
+  }
+}
+```
+
+- `allowedIssuers` — array of strings or RegExp patterns for trusted issuers
+- `audience` — expected `aud` claim
+- `requiredScopes` — optional array of required OAuth scopes
+- `getClaims(payload)` — extract claims from verified JWT payload
+
+Claims are available as `ctx.session` in `getModel`, `getSystemPrompt`, `getTools`, `getSkills`, and tool `execute` functions.
+
+If `getJwtAuthConfig` is not implemented, no authentication is performed and `ctx.session` is `undefined`.
+
+---
+
 ### Source URLs from Tools
 
 Any tool can surface source URLs into the message stream by including a `sources` array in its return value. Detected automatically by `buildLLMParams` — no additional wiring needed.
@@ -426,29 +478,6 @@ const conversations = await agent.call("getConversations");
 
 ---
 
-## Hono
-
-Hono tooling is exported on `@economic/agents/hono`.
-
-### JWT Auth Middleware
-
-Bearer JWT verification middleware for Hono, imported from `@economic/agents/hono`. Verifies tokens via JWKS derived from the token's `iss` claim.
-
-```typescript
-import { jwtAuth } from "@economic/agents/hono";
-
-app.use(
-  "/api/*",
-  jwtAuth({
-    allowedIssuers: ["https://login.example.com"],
-    audience: "my-api",
-    requiredScopes: ["read", "write"],
-  }),
-);
-```
-
----
-
 ## API Reference
 
 ### `@economic/agents`
@@ -460,7 +489,7 @@ app.use(
 | `ChatAgentHarness`     | Opinionated chat harness with getModel/getSystemPrompt/getTools/getSkills  |
 | `buildLLMParams`       | Standalone function to build streamText/generateText params                |
 | `Skill`                | Type: named group of tools with optional guidance                          |
-| `AgentToolContext`     | Type: request body merged with `logEvent` for tool context                 |
+| `AgentToolContext`     | Type: request body merged with `session` and `logEvent` for tool context   |
 | `OnChatMessageOptions` | Type: options passed to `onChatMessage`                                    |
 | `BuildLLMParamsConfig` | Type: config for standalone `buildLLMParams`                               |
 
@@ -474,13 +503,6 @@ React hooks are in a separate package. See [`@economic/agents-react`](../react/R
 | `UseAIChatAgentOptions` | Type: options for `useAIChatAgent` (`agent`, `host`, `chatId`, optional `basePath`, `toolContext`, `connectionParams`, …) |
 | `AgentConnectionStatus` | Type: `"connecting" \| "connected" \| "disconnected" \| "unauthorized"`                                                   |
 
-### `@economic/agents/hono`
-
-| Export          | Description                                 |
-| --------------- | ------------------------------------------- |
-| `jwtAuth`       | Hono middleware for Bearer JWT verification |
-| `JwtAuthConfig` | Type: config for `jwtAuth`                  |
-
 ### CLI
 
 | Command                                      | Description                              |

package/dist/index.d.mts

@@ -1,6 +1,7 @@
 import { Agent as Agent$1, AgentOptions, Connection, ConnectionContext } from "agents";
 import { AIChatAgent, OnChatMessageOptions } from "@cloudflare/ai-chat";
 import { LanguageModel, StreamTextOnFinishCallback, ToolSet, UIMessage, generateText, streamText } from "ai";
+import { JWTPayload } from "jose";
 
 //#region src/server/types.d.ts
 /**
@@ -14,8 +15,9 @@ import { LanguageModel, StreamTextOnFinishCallback, ToolSet, UIMessage, generate
  * type MyContext = AgentToolContext<MyBody>;
  * ```
  */
-type AgentToolContext<TBody = Record<string, unknown>> = TBody & {
+type AgentToolContext<TBody = Record<string, unknown>, TSession = Record<string, unknown> | undefined> = TBody & {
   logEvent: (message: string, payload?: Record<string, unknown>) => void | Promise<void>;
+  session?: TSession;
 };
 interface AgentEnv {
   AGENT_DB: D1Database;
@@ -63,6 +65,21 @@ type BuildLLMParamsConfig = Omit<LLMParams, "prompt"> & {
  */
 declare function buildLLMParams(config: BuildLLMParamsConfig): LLMParams;
 //#endregion
+//#region src/server/features/auth/index.d.ts
+interface JwtAuthConfig<TClaims extends Record<string, unknown> = Record<string, unknown>> {
+  /** Issuers whose tokens are accepted (exact string or RegExp). */
+  allowedIssuers: readonly (string | RegExp)[];
+  /** Expected `aud` claim. */
+  audience: string;
+  /** Required OAuth scopes; token `scope` must include all (empty = no scope check). */
+  requiredScopes?: readonly string[];
+  /**
+   * Extract the claims you need from the verified JWT payload.
+   * These will be stored and made available in the agent's tool context.
+   */
+  getClaims: (payload: JWTPayload) => TClaims;
+}
+//#endregion
 //#region src/server/agents/Agent.d.ts
 /**
  * Base agent for Cloudflare Agents SDK Durable Objects with lazy skill loading,
@@ -75,6 +92,19 @@ declare function buildLLMParams(config: BuildLLMParamsConfig): LLMParams;
  * extend {@link ChatAgent} instead.
  */
 declare abstract class Agent<Env extends Cloudflare.Env = Cloudflare.Env> extends Agent$1<Env & AgentEnv> {
+  /**
+   * Verified session claims from JWT authentication.
+   * Set in `onConnect` when `getJwtAuthConfig` is implemented.
+   */
+  private session?;
+  /**
+   * Override to enable JWT authentication on WebSocket connections.
+   * Return the auth config based on the incoming request, or undefined to skip auth.
+   *
+   * @param request - The WebSocket upgrade request
+   * @returns JWT auth config or undefined to skip authentication
+   */
+  protected getJwtAuthConfig?(request: Request): JwtAuthConfig<Record<string, unknown>> | undefined;
   /**
    * Returns the user ID from the durable object name.
    */
@@ -148,6 +178,19 @@ declare abstract class ChatAgent<Env extends Cloudflare.Env = Cloudflare.Env> ex
    * Default is 15.
    */
   protected maxMessagesBeforeCompaction?: number | undefined;
+  /**
+   * Verified session claims from JWT authentication.
+   * Set in `onConnect` when `getJwtAuthConfig` is implemented.
+   */
+  private session?;
+  /**
+   * Override to enable JWT authentication on WebSocket connections.
+   * Return the auth config based on the incoming request, or undefined to skip auth.
+   *
+   * @param request - The WebSocket upgrade request
+   * @returns JWT auth config or undefined to skip authentication
+   */
+  protected getJwtAuthConfig?(request: Request): JwtAuthConfig<Record<string, unknown>> | undefined;
   /**
    * Returns the user ID from the durable object name.
    */

package/dist/index.mjs

@@ -1,6 +1,7 @@
 import { Agent as Agent$1, callable, routeAgentRequest as routeAgentRequest$1 } from "agents";
 import { AIChatAgent } from "@cloudflare/ai-chat";
 import { Output, convertToModelMessages, generateText, jsonSchema, stepCountIs, streamText, tool } from "ai";
+import { createRemoteJWKSet, decodeJwt, errors, jwtVerify } from "jose";
 //#region src/server/features/skills/index.ts
 const TOOL_NAME_ACTIVATE_SKILL = "activate_skill";
 const TOOL_NAME_LIST_CAPABILITIES = "list_capabilities";
@@ -368,6 +369,106 @@ function buildTurnLogPayload(event) {
 	};
 }
 //#endregion
+//#region src/server/features/auth/index.ts
+const jwksByIssuer = /* @__PURE__ */ new Map();
+function getJwksForIssuer(issuer) {
+	const normalized = issuer.replace(/\/$/, "");
+	let jwks = jwksByIssuer.get(normalized);
+	if (!jwks) {
+		jwks = createRemoteJWKSet(new URL(`${normalized}/.well-known/openid-configuration/jwks`));
+		jwksByIssuer.set(normalized, jwks);
+	}
+	return jwks;
+}
+function isIssuerAllowed(iss, allowed) {
+	return allowed.some((rule) => typeof rule === "string" ? rule === iss : rule.test(iss));
+}
+function extractTokenFromRequest(request) {
+	const authorization = request.headers.get("Authorization");
+	if (authorization) {
+		const match = authorization.match(/^Bearer\s+(.+)$/i);
+		if (match?.[1]) return match[1].trim();
+	}
+	const wsProtocol = request.headers.get("Sec-WebSocket-Protocol");
+	if (wsProtocol) {
+		const parts = wsProtocol.split(",").map((p) => p.trim());
+		const idx = parts.indexOf("bearer");
+		if (idx !== -1 && parts[idx + 1]) return parts[idx + 1];
+	}
+	return null;
+}
+function hasRequiredScopes(tokenScope, required) {
+	if (required.length === 0) return true;
+	if (tokenScope === void 0) return false;
+	const tokens = Array.isArray(tokenScope) ? tokenScope : tokenScope.split(" ").map((s) => s.trim()).filter(Boolean);
+	const granted = new Set(tokens);
+	return required.every((scope) => granted.has(scope));
+}
+/**
+* Verify a JWT from a request and extract claims.
+*
+* Extracts the token from `Authorization: Bearer` header first,
+* then falls back to `Sec-WebSocket-Protocol: bearer, <token>` for WebSocket connections.
+*
+* Expected auth failures (missing/expired token, insufficient scope) return a failure result.
+* Unexpected errors (network issues, malformed requests, untrusted issuers) throw and should
+* be caught and logged by the caller.
+*
+* @param request - The incoming request (from ConnectionContext)
+* @param config - JWT verification configuration
+* @returns Result object with either verified claims or expected auth failure
+* @throws Error for unexpected failures that should be logged
+*/
+async function verifyJwt(request, config) {
+	const token = extractTokenFromRequest(request);
+	if (!token) return {
+		success: false,
+		status: 401,
+		message: "Unauthorized: Missing authentication token"
+	};
+	let unverifiedPayload;
+	try {
+		unverifiedPayload = decodeJwt(token);
+	} catch {
+		throw new Error("Invalid token format");
+	}
+	const iss = typeof unverifiedPayload.iss === "string" ? unverifiedPayload.iss : void 0;
+	if (!iss) throw new Error("Missing issuer claim in token");
+	if (!isIssuerAllowed(iss, config.allowedIssuers)) throw new Error(`Untrusted issuer: ${iss}`);
+	const jwks = getJwksForIssuer(iss);
+	let payload;
+	try {
+		payload = (await jwtVerify(token, jwks, {
+			issuer: iss,
+			audience: config.audience
+		})).payload;
+	} catch (error) {
+		if (error instanceof errors.JWTExpired) return {
+			success: false,
+			status: 401,
+			message: "Unauthorized: Token expired"
+		};
+		if (error instanceof errors.JWTClaimValidationFailed) return {
+			success: false,
+			status: 401,
+			message: "Unauthorized: Token claim validation failed"
+		};
+		if (error instanceof errors.JWSSignatureVerificationFailed || error instanceof errors.JWKSNoMatchingKey) throw new Error("Invalid token signature");
+		throw error;
+	}
+	const requiredScopes = config.requiredScopes ?? [];
+	const scopeClaim = payload.scope;
+	if (!hasRequiredScopes(scopeClaim, requiredScopes)) return {
+		success: false,
+		status: 403,
+		message: "Forbidden: Insufficient scope"
+	};
+	return {
+		success: true,
+		claims: config.getClaims(payload)
+	};
+}
+//#endregion
 //#region src/server/agents/Agent.ts
 /**
 * Base agent for Cloudflare Agents SDK Durable Objects with lazy skill loading,
@@ -380,6 +481,11 @@ function buildTurnLogPayload(event) {
 * extend {@link ChatAgent} instead.
 */
 var Agent = class extends Agent$1 {
+	/**
+	* Verified session claims from JWT authentication.
+	* Set in `onConnect` when `getJwtAuthConfig` is implemented.
+	*/
+	session;
 	/**
 	* Returns the user ID from the durable object name.
 	*/
@@ -388,15 +494,33 @@ var Agent = class extends Agent$1 {
 	}
 	async onConnect(connection, ctx) {
 		if (!this.env.AGENT_DB) {
-			console.error("[Agent] Connection rejected: no AGENT_DB bound");
+			console.error("[ChatAgent] Connection rejected: no AGENT_DB bound");
 			connection.close(3e3, "Could not connect to agent, database not found");
 			return;
 		}
 		if (!this.getUserId()) {
-			console.error("[Agent] Connection rejected: name must be in the format userId:uniqueChatId");
+			console.error("[ChatAgent] Connection rejected: name must be in the format userId:uniqueChatId");
 			connection.close(3e3, "Could not connect to agent, name is not in correct format");
 			return;
 		}
+		if (this.getJwtAuthConfig) {
+			const config = this.getJwtAuthConfig(ctx.request);
+			if (config) {
+				let result;
+				try {
+					result = await verifyJwt(ctx.request, config);
+				} catch (error) {
+					console.error("[ChatAgent] JWT verification error", error);
+					connection.close(4001, "Unauthorized");
+					return;
+				}
+				if (!result.success) {
+					connection.close(result.status === 401 ? 4001 : 4003, result.message);
+					return;
+				}
+				this.session = result.claims;
+			}
+		}
 		return super.onConnect(connection, ctx);
 	}
 	/**
@@ -423,7 +547,9 @@ var Agent = class extends Agent$1 {
 	async buildLLMParams(config) {
 		const activeSkills = await getStoredSkills(this.sql.bind(this));
 		const experimental_context = {
+			...config.experimental_context,
 			...config.options?.body,
+			session: this.session,
 			logEvent: this.logEvent.bind(this)
 		};
 		const onFinish = async (event) => {
@@ -680,6 +806,11 @@ var ChatAgent = class extends AIChatAgent {
 	*/
 	maxMessagesBeforeCompaction = 15;
 	/**
+	* Verified session claims from JWT authentication.
+	* Set in `onConnect` when `getJwtAuthConfig` is implemented.
+	*/
+	session;
+	/**
 	* Returns the user ID from the durable object name.
 	*/
 	getUserId() {
@@ -696,6 +827,24 @@ var ChatAgent = class extends AIChatAgent {
 			connection.close(3e3, "Could not connect to agent, name is not in correct format");
 			return;
 		}
+		if (this.getJwtAuthConfig) {
+			const config = this.getJwtAuthConfig(ctx.request);
+			if (config) {
+				let result;
+				try {
+					result = await verifyJwt(ctx.request, config);
+				} catch (error) {
+					console.error("[ChatAgent] JWT verification error", error);
+					connection.close(4001, "Unauthorized");
+					return;
+				}
+				if (!result.success) {
+					connection.close(result.status === 401 ? 4001 : 4003, result.message);
+					return;
+				}
+				this.session = result.claims;
+			}
+		}
 		return super.onConnect(connection, ctx);
 	}
 	/**
@@ -727,7 +876,9 @@ var ChatAgent = class extends AIChatAgent {
 	async buildLLMParams(config) {
 		const activeSkills = await getStoredSkills(this.sql.bind(this));
 		const experimental_context = {
+			...config.experimental_context,
 			...config.options?.body,
+			session: this.session,
 			logEvent: this.logEvent.bind(this)
 		};
 		const messages = await convertToModelMessages(this.messages);
@@ -872,7 +1023,7 @@ var ChatAgentHarness = class extends ChatAgent {
 async function routeAgentRequest(request, env, options) {
 	const response = await routeAgentRequest$1(request, env, options);
 	if (!response) return null;
-	const protocol = request.headers.get("sec-websocket-protocol");
+	const protocol = request.headers.get("Sec-WebSocket-Protocol");
 	if (response.status === 101 && protocol) {
 		const newResponse = new Response(null, response);
 		newResponse.headers.set("Sec-WebSocket-Protocol", protocol.split(",")[0].trim());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@economic/agents",
-  "version": "1.2.2",
+  "version": "1.3.1",
   "description": "A starter for creating a TypeScript package.",
   "license": "MIT",
   "bin": {
@@ -16,7 +16,6 @@
   "exports": {
     ".": "./dist/index.mjs",
     "./cli": "./dist/cli.mjs",
-    "./hono": "./dist/hono.mjs",
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -35,7 +34,6 @@
     "@types/node": "^25.6.0",
     "@typescript/native-preview": "7.0.0-dev.20260412.1",
     "ai": "^6.0.158",
-    "hono": "^4.12.12",
     "jose": "^6.2.2",
     "tsdown": "^0.21.7",
     "typescript": "^6.0.2",
@@ -45,13 +43,9 @@
     "@cloudflare/ai-chat": ">=0.1.0 <1.0.0",
     "agents": "^0.10.2",
     "ai": "^6.0.0",
-    "hono": "^4.0.0",
     "jose": "^6.0.0"
   },
   "peerDependenciesMeta": {
-    "hono": {
-      "optional": true
-    },
     "jose": {
       "optional": true
     }

package/dist/hono.d.mts

@@ -1,28 +0,0 @@
-import { Context, MiddlewareHandler } from "hono";
-
-//#region src/hono/jwt-auth.d.ts
-interface JwtAuthConfig {
-  /** Issuers whose tokens are accepted (exact string or RegExp). */
-  allowedIssuers: readonly (string | RegExp)[];
-  /** Expected `aud` claim. */
-  audience: string;
-  /** Required OAuth scopes; token `scope` must include all (empty = no scope check). */
-  requiredScopes?: readonly string[];
-  /**
-   * Custom token extraction function.
-   * If provided, replaces the default extraction entirely.
-   * Default checks Authorization header, then Sec-WebSocket-Protocol.
-   */
-  getToken?: (c: Context) => string | null | Promise<string | null>;
-}
-/**
- * Hono middleware: verify JWT via JWKS derived from the token `iss` claim,
- * after `iss` passes `allowedIssuers`.
- *
- * By default, reads the token from `Authorization: Bearer` header first,
- * then falls back to `Sec-WebSocket-Protocol: bearer, <token>` for WebSocket connections.
- * Provide a custom `getToken` function to replace this behavior entirely.
- */
-declare function jwtAuth(config: JwtAuthConfig): MiddlewareHandler;
-//#endregion
-export { type JwtAuthConfig, jwtAuth };

package/dist/hono.mjs

@@ -1,84 +0,0 @@
-import { createRemoteJWKSet, decodeJwt, errors, jwtVerify } from "jose";
-//#region src/hono/jwt-auth.ts
-const jwksByIssuer = /* @__PURE__ */ new Map();
-function getJwksForIssuer(issuer) {
-	const normalized = issuer.replace(/\/$/, "");
-	let jwks = jwksByIssuer.get(normalized);
-	if (!jwks) {
-		jwks = createRemoteJWKSet(new URL(`${normalized}/.well-known/openid-configuration/jwks`));
-		jwksByIssuer.set(normalized, jwks);
-	}
-	return jwks;
-}
-function isIssuerAllowed(iss, allowed) {
-	return allowed.some((rule) => typeof rule === "string" ? rule === iss : rule.test(iss));
-}
-function bearerTokenFromAuthorizationHeader(authorization) {
-	if (!authorization) return null;
-	return authorization.match(/^Bearer\s+(.+)$/i)?.[1]?.trim() ?? null;
-}
-function tokenFromWebSocketProtocol(header) {
-	if (!header) return null;
-	const parts = header.split(",").map((p) => p.trim());
-	const idx = parts.indexOf("bearer");
-	return idx !== -1 && parts[idx + 1] ? parts[idx + 1] : null;
-}
-function defaultGetToken(c) {
-	const authToken = bearerTokenFromAuthorizationHeader(c.req.header("Authorization"));
-	if (authToken) return authToken;
-	return tokenFromWebSocketProtocol(c.req.header("Sec-WebSocket-Protocol"));
-}
-function hasRequiredScopes(tokenScope, required) {
-	if (required.length === 0) return true;
-	if (tokenScope === void 0) return false;
-	const tokens = Array.isArray(tokenScope) ? tokenScope : tokenScope.split(" ").map((s) => s.trim()).filter(Boolean);
-	const granted = new Set(tokens);
-	return required.every((scope) => granted.has(scope));
-}
-function authErrorResponse(status, message) {
-	return new Response(message, { status });
-}
-/**
-* Hono middleware: verify JWT via JWKS derived from the token `iss` claim,
-* after `iss` passes `allowedIssuers`.
-*
-* By default, reads the token from `Authorization: Bearer` header first,
-* then falls back to `Sec-WebSocket-Protocol: bearer, <token>` for WebSocket connections.
-* Provide a custom `getToken` function to replace this behavior entirely.
-*/
-function jwtAuth(config) {
-	const requiredScopes = config.requiredScopes ?? [];
-	const getToken = config.getToken ?? defaultGetToken;
-	return async (c, next) => {
-		const token = await getToken(c);
-		if (!token) return authErrorResponse(401, "Unauthorized: Missing authentication token");
-		let unverifiedPayload;
-		try {
-			unverifiedPayload = decodeJwt(token);
-		} catch {
-			return authErrorResponse(401, "Unauthorized: Invalid token");
-		}
-		const iss = typeof unverifiedPayload.iss === "string" ? unverifiedPayload.iss : void 0;
-		if (!iss) return authErrorResponse(401, "Unauthorized: Missing issuer claim");
-		if (!isIssuerAllowed(iss, config.allowedIssuers)) return authErrorResponse(401, "Unauthorized: Untrusted issuer");
-		const jwks = getJwksForIssuer(iss);
-		let payload;
-		try {
-			payload = (await jwtVerify(token, jwks, {
-				issuer: iss,
-				audience: config.audience
-			})).payload;
-		} catch (error) {
-			console.error("Authentication failed", error);
-			if (error instanceof errors.JWTExpired) return authErrorResponse(401, "Unauthorized: Token expired");
-			if (error instanceof errors.JWTClaimValidationFailed) return authErrorResponse(401, "Unauthorized: Token claim validation failed");
-			if (error instanceof errors.JWSSignatureVerificationFailed || error instanceof errors.JWKSNoMatchingKey) return authErrorResponse(401, "Unauthorized: Invalid token signature");
-			return authErrorResponse(401, "Authentication failed");
-		}
-		const scopeClaim = payload.scope;
-		if (!hasRequiredScopes(scopeClaim, requiredScopes)) return authErrorResponse(403, "Forbidden: Insufficient scope");
-		await next();
-	};
-}
-//#endregion
-export { jwtAuth };