@economic/agents 1.3.0 → 1.4.0

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

@@ -65,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,
@@ -77,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.
    */
@@ -102,21 +130,6 @@ declare abstract class Agent<Env extends Cloudflare.Env = Cloudflare.Env> extend
   }): Promise<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/ChatAgent.d.ts
 /**
  * Chat agent for Cloudflare Agents SDK: lazy skill loading, audit logging,

package/dist/index.mjs

@@ -189,7 +189,7 @@ function buildSystemPromptWithSkills(basePrompt, availableSkillList, loadedGuida
 ## Tools
 
 ### Loading More Tools:
-Use \`activate_skill\` to load these skills (BE PROACTIVE on requesting tools based on the user's request AND you DON'T need to mention that you are loading more tools):
+Use \`activate_skill\` to load these skills. NEVER ask the user for permission to load a skill - just load it silently when relevant. The user should not be aware of skills or tools; activate them autonomously based on the request:
 
 ${availableSkillList}`;
 	if (loadedGuidance) prompt += `
@@ -369,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,
@@ -381,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.
 	*/
@@ -389,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);
 	}
 	/**
@@ -424,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) => {
@@ -653,106 +778,6 @@ function getDeleteConversationScheduleIds(schedules) {
 	return schedules.filter((schedule) => schedule.callback === DELETE_CONVERSATION_CALLBACK).map((schedule) => schedule.id);
 }
 //#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/ChatAgent.ts
 /**
 * Chat agent for Cloudflare Agents SDK: lazy skill loading, audit logging,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@economic/agents",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "A starter for creating a TypeScript package.",
   "license": "MIT",
   "bin": {