Merge pull request #299 from cloudflare/fix-state-management

fix: state management using a session binding

Author: mattzcarey

demos/mcp-slack-oauth/README.md

@@ -1,6 +1,6 @@
 # Remote Slack MCP Server with OAuth
 
-This is an implementation of a remote Slack [MCP server](https://modelcontextprotocol.io/introduction) that requires users to login to their Slack account in order to use the tools to read and post messages from their channels. 
+This is an implementation of a remote Slack [MCP server](https://modelcontextprotocol.io/introduction) that requires users to login to their Slack account in order to use the tools to read and post messages from their channels.
 
 You can deploy it to your own Cloudflare account, once you create a [Slack OAuth](https://api.slack.com/authentication/oauth-v2) app.
 
@@ -11,6 +11,9 @@ The MCP server (powered by Cloudflare Workers):
 Acts as OAuth Server to your MCP clients
 Acts as OAuth Client to your real OAuth server (in this case, Slack)
 
+> [!WARNING]
+> This is a demo template designed to help you get started quickly. While we have implemented several security controls, **you must implement all preventive and defense-in-depth security measures before deploying to production**. Please review our comprehensive security guide: [Securing MCP Servers](https://github.com/cloudflare/agents/blob/main/docs/securing-mcp-servers.md)
+
 ## Available Tools
 
 - `whoami`: Get information about your Slack user

demos/mcp-slack-oauth/src/slack-handler.ts

@@ -4,6 +4,7 @@ import { Hono } from "hono";
 import { getUpstreamAuthorizeUrl } from "./utils";
 import {
 	addApprovedClient,
+	bindStateToSession,
 	createOAuthState,
 	generateCSRFProtection,
 	isClientApproved,
@@ -45,9 +46,10 @@ app.get("/authorize", async (c) => {
 
 	// Check if client is already approved
 	if (await isClientApproved(c.req.raw, clientId, c.env.COOKIE_ENCRYPTION_KEY)) {
-		// Skip approval dialog but still create secure state
+		// Skip approval dialog but still create secure state and bind to session
 		const { stateToken } = await createOAuthState(oauthReqInfo, c.env.OAUTH_KV);
-		return redirectToSlack(c.req.raw, stateToken);
+		const { setCookie: sessionBindingCookie } = await bindStateToSession(stateToken);
+		return redirectToSlack(c.req.raw, stateToken, { "Set-Cookie": sessionBindingCookie });
 	}
 
 	// Generate CSRF protection for the approval form
@@ -97,10 +99,16 @@ app.post("/authorize", async (c) => {
 			c.env.COOKIE_ENCRYPTION_KEY,
 		);
 
-		// Create OAuth state with CSRF protection
+		// Create OAuth state and bind it to this user's session
 		const { stateToken } = await createOAuthState(state.oauthReqInfo, c.env.OAUTH_KV);
+		const { setCookie: sessionBindingCookie } = await bindStateToSession(stateToken);
 
-		return redirectToSlack(c.req.raw, stateToken, { "Set-Cookie": approvedClientCookie });
+		// Set both cookies: approved client list + session binding
+		const headers = new Headers();
+		headers.append("Set-Cookie", approvedClientCookie);
+		headers.append("Set-Cookie", sessionBindingCookie);
+
+		return redirectToSlack(c.req.raw, stateToken, Object.fromEntries(headers));
 	} catch (error: any) {
 		console.error("POST /authorize error:", error);
 		if (error instanceof OAuthError) {
@@ -156,14 +164,25 @@ type SlackOauthTokenResponse =
  * It validates the state parameter, exchanges the temporary code for an access token,
  * then stores user metadata & the auth token as part of the 'props' on the token passed
  * down to the client. It ends by redirecting the client back to _its_ callback URL
+ *
+ * SECURITY: This endpoint validates that the state parameter from Slack
+ * matches both:
+ * 1. A valid state token in KV (proves it was created by our server)
+ * 2. The __Host-CONSENTED_STATE cookie (proves THIS browser consented to it)
+ *
+ * This prevents CSRF attacks where an attacker's state token is injected
+ * into a victim's OAuth flow.
  */
 app.get("/callback", async (c) => {
-	// Validate OAuth state (retrieves stored data from KV)
+	// Validate OAuth state with session binding
+	// This checks both KV storage AND the session cookie
 	let oauthReqInfo: AuthRequest;
+	let clearSessionCookie: string;
 
 	try {
 		const result = await validateOAuthState(c.req.raw, c.env.OAUTH_KV);
 		oauthReqInfo = result.oauthReqInfo;
+		clearSessionCookie = result.clearCookie;
 	} catch (error: any) {
 		if (error instanceof OAuthError) {
 			return error.toResponse();
@@ -247,7 +266,16 @@ app.get("/callback", async (c) => {
 		userId: userId,
 	});
 
-	return Response.redirect(redirectTo, 302);
+	// Clear the session binding cookie (one-time use) by creating response with headers
+	const headers = new Headers({ Location: redirectTo });
+	if (clearSessionCookie) {
+		headers.set("Set-Cookie", clearSessionCookie);
+	}
+
+	return new Response(null, {
+		status: 302,
+		headers,
+	});
 });
 
 export const SlackHandler = app;

demos/mcp-slack-oauth/src/workers-oauth-utils.ts

@@ -66,6 +66,16 @@ export interface ValidateStateResult {
 	clearCookie: string;
 }
 
+/**
+ * Result from bindStateToSession containing the cookie to set
+ */
+export interface BindStateResult {
+	/**
+	 * Set-Cookie header value to bind the state to the user's session
+	 */
+	setCookie: string;
+}
+
 /**
  * Result from generateCSRFProtection containing the CSRF token and cookie header
  */
@@ -256,8 +266,43 @@ export async function createOAuthState(
 }
 
 /**
- * Validates OAuth state from the request, ensuring the state parameter matches the cookie
- * and retrieving the stored OAuth request information
+ * Binds an OAuth state token to the user's browser session using a secure cookie.
+ * This prevents CSRF attacks where an attacker's state token is used by a victim.
+ *
+ * SECURITY: This cookie proves that the browser completing the OAuth callback
+ * is the same browser that consented to the authorization request.
+ *
+ * We hash the state token rather than storing it directly for defense-in-depth:
+ * - Even if the state parameter leaks (URL logs, referrer headers), the cookie value cannot be derived
+ * - The cookie serves as cryptographic proof of consent, not just a copy of the state
+ * - Provides an additional layer of security beyond HttpOnly/Secure flags
+ *
+ * @param stateToken - The state token to bind to the session
+ * @returns Object containing the Set-Cookie header to send to the client
+ */
+export async function bindStateToSession(stateToken: string): Promise<BindStateResult> {
+	const consentedStateCookieName = "__Host-CONSENTED_STATE";
+
+	// Hash the state token to provide defense-in-depth
+	const encoder = new TextEncoder();
+	const data = encoder.encode(stateToken);
+	const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+	const hashArray = Array.from(new Uint8Array(hashBuffer));
+	const hashHex = hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+
+	const setCookie = `${consentedStateCookieName}=${hashHex}; HttpOnly; Secure; Path=/; SameSite=Lax; Max-Age=600`;
+
+	return { setCookie };
+}
+
+/**
+ * Validates OAuth state from the request, ensuring:
+ * 1. The state parameter exists in KV (proves it was created by our server)
+ * 2. The state hash matches the session cookie (proves this browser consented to it)
+ *
+ * This prevents attacks where an attacker's valid state token is injected into
+ * a victim's OAuth flow.
+ *
  * @param request - The HTTP request containing state parameter and cookies
  * @param kv - Cloudflare KV namespace for storing OAuth state data
  * @returns Object containing the original OAuth request info and cookie to clear
@@ -267,6 +312,7 @@ export async function validateOAuthState(
 	request: Request,
 	kv: KVNamespace,
 ): Promise<ValidateStateResult> {
+	const consentedStateCookieName = "__Host-CONSENTED_STATE";
 	const url = new URL(request.url);
 	const stateFromQuery = url.searchParams.get("state");
 
@@ -280,6 +326,38 @@ export async function validateOAuthState(
 		throw new OAuthError("invalid_request", "Invalid or expired state", 400);
 	}
 
+	// SECURITY FIX: Validate that this state token belongs to this browser session
+	// by checking that the state hash matches the session cookie
+	const cookieHeader = request.headers.get("Cookie") || "";
+	const cookies = cookieHeader.split(";").map((c) => c.trim());
+	const consentedStateCookie = cookies.find((c) => c.startsWith(`${consentedStateCookieName}=`));
+	const consentedStateHash = consentedStateCookie
+		? consentedStateCookie.substring(consentedStateCookieName.length + 1)
+		: null;
+
+	if (!consentedStateHash) {
+		throw new OAuthError(
+			"invalid_request",
+			"Missing session binding cookie - authorization flow must be restarted",
+			400,
+		);
+	}
+
+	// Hash the state from query and compare with cookie
+	const encoder = new TextEncoder();
+	const data = encoder.encode(stateFromQuery);
+	const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+	const hashArray = Array.from(new Uint8Array(hashBuffer));
+	const stateHash = hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+
+	if (stateHash !== consentedStateHash) {
+		throw new OAuthError(
+			"invalid_request",
+			"State token does not match session - possible CSRF attack detected",
+			400,
+		);
+	}
+
 	let oauthReqInfo: AuthRequest;
 	try {
 		oauthReqInfo = JSON.parse(storedDataJson) as AuthRequest;
@@ -290,8 +368,8 @@ export async function validateOAuthState(
 	// Delete state from KV (one-time use)
 	await kv.delete(`oauth:state:${stateFromQuery}`);
 
-	// No cookie to clear since we're not using state cookies anymore
-	const clearCookie = "";
+	// Clear the session binding cookie (one-time use per OAuth flow)
+	const clearCookie = `${consentedStateCookieName}=; HttpOnly; Secure; Path=/; SameSite=Lax; Max-Age=0`;
 
 	return { oauthReqInfo, clearCookie };
 }

demos/mcp-stytch-b2b-okr-manager/README.md

@@ -2,14 +2,17 @@
 
 This is a Workers server that composes three functions:
 * A static website built using React and Vite on top of [Worker Assets](https://developers.cloudflare.com/workers/static-assets/)
-* A REST API built using Hono on top of [Workers KV](https://developers.cloudflare.com/kv/) 
+* A REST API built using Hono on top of [Workers KV](https://developers.cloudflare.com/kv/)
 * A [Model Context Protocol](https://modelcontextprotocol.io/introduction) Server built using on top of [Workers Durable Objects](https://developers.cloudflare.com/durable-objects/)
 
 Member, Tenant, and client identity is managed using [Stytch](https://stytch.com/). Put together, these three features show how to extend a traditional full-stack CRUD application for use by an AI agent.
 
-This demo uses the [Stytch B2B](https://stytch.com/b2b) product, which is purpose-built for B2B SaaS authentication requirements like multi-tenancy, MFA, and RBAC. 
+This demo uses the [Stytch B2B](https://stytch.com/b2b) product, which is purpose-built for B2B SaaS authentication requirements like multi-tenancy, MFA, and RBAC.
 If you are more interested in Stytch's [Consumer](https://stytch.com/b2c) product, see [this demo](https://github.com/stytchauth/mcp-stytch-consumer-todo-list/) instead.
 
+> [!WARNING]
+> This is a demo template designed to help you get started quickly. While we have implemented several security controls, **you must implement all preventive and defense-in-depth security measures before deploying to production**. Please review our comprehensive security guide: [Securing MCP Servers](https://github.com/cloudflare/agents/blob/main/docs/securing-mcp-servers.md)
+
 ![](./.github/hero.png)
 
 ## Set up

demos/mcp-stytch-consumer-todo-list/README.md

@@ -3,14 +3,17 @@
 This is a Workers server that composes three functions:
 
 * A static website built using React and Vite on top of [Worker Assets](https://developers.cloudflare.com/workers/static-assets/)
-* A REST API built using Hono on top of [Workers KV](https://developers.cloudflare.com/kv/) 
+* A REST API built using Hono on top of [Workers KV](https://developers.cloudflare.com/kv/)
 * A [Model Context Protocol](https://modelcontextprotocol.io/introduction) Server built using on top of [Workers Durable Objects](https://developers.cloudflare.com/durable-objects/)
 
 User and client identity is managed using [Stytch](https://stytch.com/). Put together, these three features show how to extend a traditional full-stack application for use by an AI agent.
 
 This demo uses the [Stytch Consumer](https://stytch.com/b2c) product, which is purpose-built for Consumer SaaS authentication requirements.
 If you are more interested in Stytch's [B2B](https://stytch.com/b2b) product, see [this demo](https://github.com/stytchauth/mcp-stytch-b2b-okr-manager/) instead.
 
+> [!WARNING]
+> This is a demo template designed to help you get started quickly. While we have implemented several security controls, **you must implement all preventive and defense-in-depth security measures before deploying to production**. Please review our comprehensive security guide: [Securing MCP Servers](https://github.com/cloudflare/agents/blob/main/docs/securing-mcp-servers.md)
+
 ## Set up
 
 Follow the steps below to get this application fully functional and running using your own Stytch credentials.

demos/remote-mcp-auth0/README.md

@@ -7,6 +7,9 @@ The MCP server (powered by [Cloudflare Workers](https://developers.cloudflare.co
 - Acts as OAuth _Server_ to your MCP clients
 - Acts as OIDC _Client_ to your Auth0 Tenant
 
+> [!WARNING]
+> This is a demo template designed to help you get started quickly. While we have implemented several security controls, **you must implement all preventive and defense-in-depth security measures before deploying to production**. Please review our comprehensive security guide: [Securing MCP Servers](https://github.com/cloudflare/agents/blob/main/docs/securing-mcp-servers.md)
+
 ## Getting Started
 
 This demo allows an MCP Server to call a protected API on behalf of the authenticated user. To get started you will need the following:

demos/remote-mcp-auth0/mcp-auth0-oidc/src/auth.ts

@@ -12,10 +12,11 @@ import * as oauth from "oauth4webapi";
 
 import type { UserProps } from "./types";
 import {
+	addApprovedClient,
+	bindStateToSession,
 	createOAuthState,
 	generateCSRFProtection,
 	isClientApproved,
-	addApprovedClient,
 	OAuthError,
 	renderApprovalDialog,
 	validateCSRFToken,
@@ -79,7 +80,7 @@ export async function authorize(c: Context<{ Bindings: Env & { OAUTH_PROVIDER: O
 			c.env.COOKIE_ENCRYPTION_KEY,
 		)
 	) {
-		// Skip approval dialog but still use secure state management
+		// Skip approval dialog but still create secure state and bind to session
 		// Generate all that is needed for the Auth0 auth request
 		const codeVerifier = oauth.generateRandomCodeVerifier();
 		const nonce = oauth.generateRandomNonce();
@@ -99,6 +100,7 @@ export async function authorize(c: Context<{ Bindings: Env & { OAUTH_PROVIDER: O
 			auth0Data,
 		};
 		const { stateToken } = await createOAuthState(extendedRequest, c.env.OAUTH_KV);
+		const { setCookie: sessionBindingCookie } = await bindStateToSession(stateToken);
 
 		// Redirect directly to Auth0
 		const { as } = await getOidcConfig({
@@ -118,7 +120,13 @@ export async function authorize(c: Context<{ Bindings: Env & { OAUTH_PROVIDER: O
 		authorizationUrl.searchParams.set("nonce", nonce);
 		authorizationUrl.searchParams.set("state", stateToken);
 
-		return c.redirect(authorizationUrl.href);
+		return new Response(null, {
+			status: 302,
+			headers: {
+				"Location": authorizationUrl.href,
+				"Set-Cookie": sessionBindingCookie,
+			},
+		});
 	}
 
 	// Generate CSRF protection for the approval form
@@ -191,12 +199,13 @@ export async function confirmConsent(
 			c.env.COOKIE_ENCRYPTION_KEY,
 		);
 
-		// Create OAuth state in KV (secure, one-time use)
+		// Create OAuth state and bind it to this user's session
 		const extendedRequest: ExtendedAuthRequest = {
 			...state.oauthReqInfo,
 			auth0Data: state.auth0Data,
 		};
 		const { stateToken } = await createOAuthState(extendedRequest, c.env.OAUTH_KV);
+		const { setCookie: sessionBindingCookie } = await bindStateToSession(stateToken);
 
 		// Get Auth0 configuration
 		const { as } = await getOidcConfig({
@@ -217,13 +226,15 @@ export async function confirmConsent(
 		authorizationUrl.searchParams.set("nonce", state.auth0Data.nonce);
 		authorizationUrl.searchParams.set("state", stateToken);
 
-		// Return redirect with cleared CSRF cookie and new approved client cookie
+		// Set both cookies: approved client list + session binding
+		const headers = new Headers();
+		headers.append("Set-Cookie", approvedClientCookie);
+		headers.append("Set-Cookie", sessionBindingCookie);
+		headers.set("Location", authorizationUrl.href);
+
 		return new Response(null, {
 			status: 302,
-			headers: {
-				Location: authorizationUrl.href,
-				"Set-Cookie": approvedClientCookie,
-			},
+			headers,
 		});
 	} catch (error: any) {
 		console.error("POST /authorize error:", error);
@@ -241,14 +252,25 @@ export async function confirmConsent(
  * This route handles the callback from Auth0 after user authentication.
  * It validates the OAuth state, exchanges the authorization code for tokens,
  * and completes the authorization process.
+ *
+ * SECURITY: This endpoint validates that the state parameter from Auth0
+ * matches both:
+ * 1. A valid state token in KV (proves it was created by our server)
+ * 2. The __Host-CONSENTED_STATE cookie (proves THIS browser consented to it)
+ *
+ * This prevents CSRF attacks where an attacker's state token is injected
+ * into a victim's OAuth flow.
  */
 export async function callback(c: Context<{ Bindings: Env & { OAUTH_PROVIDER: OAuthHelpers } }>) {
-	// Validate OAuth state (retrieves stored data from KV)
+	// Validate OAuth state with session binding
+	// This checks both KV storage AND the session cookie
 	let storedData: ExtendedAuthRequest;
+	let clearSessionCookie: string;
 
 	try {
 		const result = await validateOAuthState(c.req.raw, c.env.OAUTH_KV);
 		storedData = result.oauthReqInfo as ExtendedAuthRequest;
+		clearSessionCookie = result.clearCookie;
 	} catch (error: any) {
 		if (error instanceof OAuthError) {
 			return error.toResponse();
@@ -312,7 +334,16 @@ export async function callback(c: Context<{ Bindings: Env & { OAUTH_PROVIDER: OA
 		userId: claims.sub!,
 	});
 
-	return Response.redirect(redirectTo);
+	// Clear the session binding cookie (one-time use) by creating response with headers
+	const headers = new Headers({ Location: redirectTo });
+	if (clearSessionCookie) {
+		headers.set("Set-Cookie", clearSessionCookie);
+	}
+
+	return new Response(null, {
+		status: 302,
+		headers,
+	});
 }
 
 /**