@economic/agents 2.5.0 → 2.6.0

package/README.md

@@ -514,6 +514,39 @@ protected async getUserContext(jwtToken: string) {
 }
 ```
 
+If `getUserContext` throws, the socket closes with `1011` — or, when the thrown `Error` carries a numeric `closeCode` in the `4000`–`4999` range, with that code and an `"unauthorized"` status frame:
+
+```typescript
+const error = new Error("No Eva access");
+(error as Error & { closeCode: number }).closeCode = 4003;
+throw error;
+```
+
+### Token exchange
+
+For agents whose clients connect with a _down-scoped_ token — one only valid for the client ↔ agent hop — override the static `getTokenExchangeConfig(env)` to exchange it (RFC 8693) at the identity server for a token issued to the agent's own OAuth client. Requires `getJwtAuthConfig`.
+
+```typescript
+export class SupportAgent extends Agent {
+  static getTokenExchangeConfig(env: Cloudflare.Env) {
+    return {
+      tokenUrl: `${env.IDENTITY_ENDPOINT}/connect/token`,
+      clientId: env.OAUTH_CLIENT_ID,
+      clientSecret: env.OAUTH_CLIENT_SECRET, // string or Secrets Store binding
+      scopes: "api.read api.write", // always sent explicitly
+      tokenHeader: "X-EconomicToken", // default
+    };
+  }
+}
+```
+
+When configured:
+
+- The verified connect token is exchanged on every connect; the exchanged token is what `getUserContext` receives and what tools see as `ctx.tokens[tokenHeader]` each turn. **Client-sent request-body tokens for that key are ignored** — tool credentials always derive from the verified connection identity, so clients should stop sending them.
+- Renewal is connection-based. The client token rides in the WebSocket protocols, so presenting a renewed token always means a reconnect, which re-verifies and re-exchanges. Keep the `authToken` passed to the hooks current (refresh it before expiry) and the socket rotates silently — the `unauthorized` close (`4001`) then only happens when the session is genuinely dead (logout, revocation).
+- The exchanged token expires on the identity server's clock (with a 30s margin). A turn arriving after expiry closes the connection `4001` to force a reconnect; a client that refreshes its token on time never hits this.
+- Exchange failures at connect: `invalid_grant` (dead session token) → status `"unauthorized"` + close `4001`; anything else (identity server down, misconfigured client) → status `"error"` + close `1011`. Partial configuration is the app's concern — throw from `getTokenExchangeConfig` if you consider it a deployment fault, or return `undefined` to disable the exchange.
+
 ## Observability
 
 Emitted per turn from the `ai` SDK's OpenTelemetry spans, no setup beyond bindings:

package/dist/index.d.mts

@@ -26,6 +26,61 @@ type SqlFn = InstanceType<typeof Agent$1>["sql"];
 type AgentConnectionStatus = "connecting" | "connected" | "disconnected" | "unauthorized" | "error";
 type AgentConnectionType = "agent" | "chat" | "assistant";
 //#endregion
+//#region src/server/features/auth/tokenExchange.d.ts
+interface TokenExchangeConfig {
+  /** Identity server token endpoint, e.g. `${identityOrigin}/connect/token`. */
+  tokenUrl: string;
+  /** OAuth client the agent authenticates as. */
+  clientId: string;
+  /**
+   * Plain secret, or a binding resolved with `get()` (e.g. a Cloudflare
+   * Secrets Store binding). Resolved on every exchange so rotation is
+   * picked up without a redeploy.
+   */
+  clientSecret: string | {
+    get(): Promise<string>;
+  };
+  /**
+   * Space-separated scopes for the exchanged token. Always sent explicitly:
+   * omitting `scope` would make the identity server issue every scope the
+   * client is allowed, the opposite of least privilege.
+   */
+  scopes: string;
+  /**
+   * Key under the request-context `tokens` record that tools read the token
+   * from. Defaults to {@link DEFAULT_TOKEN_HEADER}.
+   */
+  tokenHeader?: string;
+}
+interface ExchangedToken {
+  accessToken: string;
+  /** Unix ms; already includes {@link EXPIRY_MARGIN_MS}. */
+  expiresAt: number;
+}
+type TokenExchangeResult = ({
+  success: true;
+} & ExchangedToken) | {
+  success: false;
+  status: number;
+  errorCode: string;
+  message: string;
+  /**
+   * True when the identity server rejected the subject token itself
+   * (RFC 6749 `invalid_grant`: expired or revoked). Re-authenticating is
+   * the only fix — other failures (`invalid_client`, `invalid_scope`,
+   * 5xx) are deployment or identity-server faults the user cannot fix by
+   * logging in again.
+   */
+  subjectTokenRejected: boolean;
+};
+/**
+ * Exchange `subjectToken` for a token issued to the agent's own OAuth client.
+ *
+ * Expected identity-server rejections return a failure result; unexpected
+ * failures (network error, timeout, malformed success response) throw.
+ */
+declare function exchangeToken(subjectToken: string, config: TokenExchangeConfig): Promise<TokenExchangeResult>;
+//#endregion
 //#region src/server/util/tools.d.ts
 type ToolSet = Record<string, Tool>;
 type Tool<Context extends Record<string, unknown> = Record<string, unknown>, INPUT extends JSONValue | unknown | never = any, OUTPUT extends JSONValue | unknown | never = any> = Tool$1<INPUT, OUTPUT> & {
@@ -141,6 +196,41 @@ declare abstract class Agent<RequestContext extends Record<string, unknown> = Re
    * @returns JWT auth config or undefined to skip authentication
    */
   static getJwtAuthConfig?(env: Cloudflare.Env): JwtAuthConfig<Record<string, unknown>> | undefined;
+  /**
+   * Override to exchange the verified connect token (RFC 8693) for a token
+   * issued to this agent's own OAuth client. Requires {@link getJwtAuthConfig}.
+   *
+   * When configured, the exchanged token is passed to {@link getUserContext}
+   * and injected into the tool context every turn under
+   * `tokens[config.tokenHeader]` — client-sent request-body tokens for that
+   * key are ignored. Renewal is connection-based: a client presenting a new
+   * token reconnects, and the connect flow re-verifies and re-exchanges.
+   *
+   * Do not add side effects to this method - return a single config from it,
+   * or undefined to disable the exchange.
+   *
+   * @param env - The worker environment variables
+   * @returns Token exchange config or undefined to disable
+   */
+  static getTokenExchangeConfig?(env: Cloudflare.Env): TokenExchangeConfig | undefined;
+  /**
+   * The exchanged token for this agent, refreshed on every authenticated
+   * connect. Kept in memory for the hot path and mirrored to DO storage so
+   * turns that run after hibernation (or without a connection at all) still
+   * have it. Short-lived by construction — at most the identity server's
+   * token lifetime.
+   */
+  private _exchangedToken?;
+  private _storeExchangedToken;
+  private _getExchangedToken;
+  /**
+   * Swaps the client-sent token for the exchanged one in a copy of the turn
+   * body. No-op when token exchange is not configured. When the exchanged
+   * token is missing or expired the turn cannot run: only a reconnect can
+   * deliver a fresh subject token, so the current connection (if any) is
+   * closed to force one, and the turn fails.
+   */
+  private _applyTokenExchange;
   /**
    * The user context for the session.
    * Define getUserContext to set a user context.
@@ -365,4 +455,4 @@ declare function skill<Context extends Record<string, unknown> = Record<string,
 //#region src/server/index.d.ts
 declare function getCurrentToolContext(): any;
 //#endregion
-export { Agent, type AgentConnectionStatus, type AgentConnectionType, type AgentEnv, Assistant, ChatAgent, type FacetStub, type LegacyChatStub, type LegacyMessageFeedback, type MigrationDeps, type Skill, type SkillSource, type Tool, type ToolContext, type ToolSet, type TurnSnapshot, getCurrentToolContext, migrateUserFromV1, routeAgentRequest, skill, tool };
+export { Agent, type AgentConnectionStatus, type AgentConnectionType, type AgentEnv, Assistant, ChatAgent, type ExchangedToken, type FacetStub, type LegacyChatStub, type LegacyMessageFeedback, type MigrationDeps, type Skill, type SkillSource, type TokenExchangeConfig, type TokenExchangeResult, type Tool, type ToolContext, type ToolSet, type TurnSnapshot, exchangeToken, getCurrentToolContext, migrateUserFromV1, routeAgentRequest, skill, tool };

package/dist/index.mjs

@@ -4,6 +4,97 @@ import { Think, skills } from "@cloudflare/think";
 import { Output, convertToModelMessages, generateText, jsonSchema, pruneMessages, tool as tool$1 } from "ai";
 import { nanoid } from "nanoid";
 import { createCompactFunction } from "agents/experimental/memory/utils";
+//#region src/server/features/auth/tokenExchange.ts
+/**
+* OAuth 2.0 Token Exchange (RFC 8693) against an identity server.
+*
+* The client connects with a token down-scoped for the client ↔ agent hop only.
+* When an agent defines `static getTokenExchangeConfig`, the verified connect
+* token is exchanged — authenticating as the agent's own OAuth client — for a
+* token carrying the scopes the agent needs against backends. Backends then see
+* the agent's `client_id` and can attribute calls to it, and the browser never
+* holds a backend-capable credential.
+*
+* Expected failures (the identity server rejecting the request) return a result
+* object; unexpected failures (network errors, malformed responses) throw. Same
+* contract as `verifyJwt` in ./index.ts.
+*/
+const TOKEN_EXCHANGE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:token-exchange";
+const ACCESS_TOKEN_TYPE = "urn:ietf:params:oauth:token-type:access_token";
+const TOKEN_EXCHANGE_TIMEOUT_MS = 3e4;
+/** Exchanged tokens are treated as expired this long before they actually are. */
+const EXPIRY_MARGIN_MS = 3e4;
+/**
+* Exchange `subjectToken` for a token issued to the agent's own OAuth client.
+*
+* Expected identity-server rejections return a failure result; unexpected
+* failures (network error, timeout, malformed success response) throw.
+*/
+async function exchangeToken(subjectToken, config) {
+	const clientSecret = typeof config.clientSecret === "string" ? config.clientSecret : await config.clientSecret.get();
+	const body = new URLSearchParams({
+		client_id: config.clientId,
+		client_secret: clientSecret,
+		grant_type: TOKEN_EXCHANGE_GRANT_TYPE,
+		subject_token: subjectToken,
+		subject_token_type: ACCESS_TOKEN_TYPE,
+		scope: config.scopes
+	});
+	const response = await fetch(config.tokenUrl, {
+		method: "POST",
+		headers: { "Content-Type": "application/x-www-form-urlencoded" },
+		body: body.toString(),
+		signal: AbortSignal.timeout(TOKEN_EXCHANGE_TIMEOUT_MS)
+	});
+	if (!response.ok) {
+		let errorCode = "unknown_error";
+		let description;
+		try {
+			const json = await response.json();
+			errorCode = json.error ?? errorCode;
+			description = json.error_description;
+		} catch {}
+		return {
+			success: false,
+			status: response.status,
+			errorCode,
+			message: `Token exchange failed with status ${response.status} (${errorCode})${description ? `: ${description}` : ""}`,
+			subjectTokenRejected: response.status === 400 && errorCode === "invalid_grant"
+		};
+	}
+	let json;
+	try {
+		json = await response.json();
+	} catch {
+		throw new Error("Token exchange response body was not valid JSON");
+	}
+	if (!json.access_token) throw new Error("Token exchange response contained no access_token");
+	if (typeof json.expires_in !== "number") throw new Error("Token exchange response contained no expires_in");
+	return {
+		success: true,
+		accessToken: json.access_token,
+		expiresAt: Date.now() + Math.max(0, json.expires_in * 1e3 - EXPIRY_MARGIN_MS)
+	};
+}
+/**
+* Returns a copy of the request body with the exchanged token injected under
+* `tokens[tokenHeader]`, overriding any client-sent value for that key.
+*
+* Never mutates `body`: think persists the original request body
+* (`_lastBody`) and replays it on continuation turns, so a mutation would
+* persist the exchanged token and replay it as a subject token later.
+*/
+function withExchangedToken(body, tokenHeader, accessToken) {
+	const tokens = body?.tokens ?? {};
+	return {
+		...body,
+		tokens: {
+			...tokens,
+			[tokenHeader]: accessToken
+		}
+	};
+}
+//#endregion
 //#region src/server/util/tools.ts
 function tool(tool) {
 	return tool$1(tool);
@@ -148,6 +239,18 @@ function buildSourcesTransform(additional) {
 }
 //#endregion
 //#region src/server/agents/Agent.ts
+const EXCHANGED_TOKEN_STORAGE_KEY = "economic:exchangedToken";
+/**
+* Close code for a getUserContext failure. Subclasses signal an intentional
+* auth-style rejection by throwing an Error carrying a numeric `closeCode`
+* in the WebSocket application range (4000-4999); anything else is treated
+* as an internal error (1011).
+*/
+function getConnectCloseCode(error) {
+	const closeCode = error?.closeCode;
+	if (typeof closeCode === "number" && closeCode >= 4e3 && closeCode <= 4999) return closeCode;
+	return 1011;
+}
 var Agent = class extends Think {
 	agentType = "agent";
 	clientIp;
@@ -207,7 +310,45 @@ var Agent = class extends Think {
 					return;
 				}
 				const token = extractTokenFromConnectRequest(ctx.request);
-				if (token && this.getUserContext) connection.setState({ userContext: await this.getUserContext(token) });
+				let effectiveToken = token;
+				const getTokenExchangeConfig = this.constructor.getTokenExchangeConfig;
+				const exchangeConfig = getTokenExchangeConfig?.(this.env);
+				if (token && exchangeConfig) {
+					let result;
+					try {
+						result = await exchangeToken(token, exchangeConfig);
+					} catch (error) {
+						sendConnectionStatus(connection, "error");
+						console.error(`[Agent] Token exchange error - ${error}`);
+						connection.close(1011, "Token exchange failed");
+						return;
+					}
+					if (!result.success) {
+						console.error(`[Agent] Token exchange failed - ${result.message}`);
+						if (result.subjectTokenRejected) {
+							sendConnectionStatus(connection, "unauthorized");
+							connection.close(4001, "Unauthorized");
+						} else {
+							sendConnectionStatus(connection, "error");
+							connection.close(1011, "Token exchange failed");
+						}
+						return;
+					}
+					await this._storeExchangedToken({
+						accessToken: result.accessToken,
+						expiresAt: result.expiresAt
+					});
+					effectiveToken = result.accessToken;
+				}
+				if (effectiveToken && this.getUserContext) try {
+					connection.setState({ userContext: await this.getUserContext(effectiveToken) });
+				} catch (error) {
+					const closeCode = getConnectCloseCode(error);
+					sendConnectionStatus(connection, closeCode === 1011 ? "error" : "unauthorized");
+					console.error(`[Agent] getUserContext error - ${error}`);
+					connection.close(closeCode, "Could not establish user context");
+					return;
+				}
 			}
 		}
 		sendConnectionStatus(connection, "connected");
@@ -231,7 +372,8 @@ var Agent = class extends Think {
 	*/
 	async beforeTurn(ctx) {
 		this.registerInstanceActivity();
-		this._toolContextForCurrentTurn = this.getToolContextForCurrentTurn(ctx.body);
+		const body = await this._applyTokenExchange(ctx.body);
+		this._toolContextForCurrentTurn = this.getToolContextForCurrentTurn(body);
 		this._toolsForCurrentTurn = ctx.tools;
 		const activeSkillName = this._getLastActivatedSkillName(ctx.messages);
 		const { tools, activeTools } = await this._getAuthorizedTools(ctx.tools, activeSkillName);
@@ -424,6 +566,48 @@ var Agent = class extends Think {
 		}
 	}
 	/**
+	* The exchanged token for this agent, refreshed on every authenticated
+	* connect. Kept in memory for the hot path and mirrored to DO storage so
+	* turns that run after hibernation (or without a connection at all) still
+	* have it. Short-lived by construction — at most the identity server's
+	* token lifetime.
+	*/
+	_exchangedToken;
+	async _storeExchangedToken(token) {
+		this._exchangedToken = token;
+		await this.ctx.storage.put(EXCHANGED_TOKEN_STORAGE_KEY, token);
+	}
+	async _getExchangedToken() {
+		if (!this._exchangedToken) this._exchangedToken = await this.ctx.storage.get(EXCHANGED_TOKEN_STORAGE_KEY);
+		if (this._exchangedToken && this._exchangedToken.expiresAt <= Date.now()) {
+			this._exchangedToken = void 0;
+			await this.ctx.storage.delete(EXCHANGED_TOKEN_STORAGE_KEY);
+		}
+		return this._exchangedToken;
+	}
+	/**
+	* Swaps the client-sent token for the exchanged one in a copy of the turn
+	* body. No-op when token exchange is not configured. When the exchanged
+	* token is missing or expired the turn cannot run: only a reconnect can
+	* deliver a fresh subject token, so the current connection (if any) is
+	* closed to force one, and the turn fails.
+	*/
+	async _applyTokenExchange(body) {
+		const getTokenExchangeConfig = this.constructor.getTokenExchangeConfig;
+		const exchangeConfig = getTokenExchangeConfig?.(this.env);
+		if (!exchangeConfig) return body;
+		const token = await this._getExchangedToken();
+		if (!token) {
+			const { connection } = getCurrentAgent();
+			if (connection) {
+				sendConnectionStatus(connection, "unauthorized");
+				connection.close(4001, "Unauthorized");
+			}
+			throw new Error("Exchanged token missing or expired - the client must reconnect");
+		}
+		return withExchangedToken(body, exchangeConfig.tokenHeader ?? "X-EconomicToken", token.accessToken);
+	}
+	/**
 	* The user context for the session.
 	* Define getUserContext to set a user context.
 	*/
@@ -1378,4 +1562,4 @@ function getCurrentToolContext() {
 	return getCurrentAgent().agent._lastBody;
 }
 //#endregion
-export { Agent, Assistant, ChatAgent, getCurrentToolContext, migrateUserFromV1, routeAgentRequest, skill, tool };
+export { Agent, Assistant, ChatAgent, exchangeToken, getCurrentToolContext, migrateUserFromV1, routeAgentRequest, skill, tool };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@economic/agents",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "A starter for creating a TypeScript package.",
   "license": "MIT",
   "files": [