feat: Implement SameSite for cookies (#100)

Author: nzakas

docs/src/content/docs/fetch-mockers/mocking-browser-requests.mdx

@@ -114,13 +114,14 @@ credentials.setCookie({
     name: "sessionId",
     value: "abc123",
     path: "/admin",      // defaults to "/"
+    sameSite: "none",    // defaults to "lax"
     secure: true,        // defaults to false
     httpOnly: true       // defaults to false
 });
 ```
 
 <Aside type="note">
-	Real cookies also allow you to specify an expiration date and the `HttpOnly` flag, but neither is useful for testing purposes and so are not supported.
+	Real cookies also allow you to specify an expiration date but that's not useful for testing purposes and so is not supported.
 </Aside>
 
 <Aside type="caution">
@@ -202,6 +203,7 @@ Cookies are included in requests based on these rules:
 1. The request domain must match or be a subdomain of the cookie's domain
 2. The request path must match or be under the cookie's path
 3. For secure cookies, the request must use HTTPS
+4. The request must match the cookie's `sameSite` policy (if set)
 
 For example:
 

src/cookie-credentials.js

@@ -17,6 +17,10 @@ import { parseUrl } from "./util.js";
 
 /** @typedef {import("./types.js").Credentials} Credentials */
 
+/**
+ * @typedef {"strict"|"lax"|"none"} SameSiteType
+ */
+
 /**
  * @typedef {Object} CookieInfo
  * @property {string} name The name of the cookie.
@@ -25,12 +29,15 @@ import { parseUrl } from "./util.js";
  * @property {string} [path] The path of the cookie.
  * @property {boolean} [secure] The secure flag of the cookie.
  * @property {boolean} [httpOnly] The HTTP-only flag of the cookie.
+ * @property {SameSiteType} [sameSite] The SameSite attribute of the cookie.
  */
 
 //-----------------------------------------------------------------------------
 // Helpers
 //-----------------------------------------------------------------------------
 
+const sameSiteValues = new Set(["strict", "lax", "none"]);
+
 /**
  * Asserts that a string is a valid domain that does not include a protocol or path.
  * @param {string|undefined} domain The domain string to verify.
@@ -47,6 +54,23 @@ function assertValidDomain(domain) {
 	}
 }
 
+/**
+ * Asserts that a string is a valid SameSite value and that the security requirements are met.
+ * @param {SameSiteType|undefined} sameSite The SameSite value to verify.
+ * @param {boolean} secure The secure flag of the cookie.
+ * @throws {TypeError} If the SameSite value is not valid or if SameSite=None without Secure.
+ */
+function assertValidSameSite(sameSite, secure) {
+	if (sameSite && !sameSiteValues.has(sameSite)) {
+		throw new TypeError(`Invalid sameSite value: ${sameSite}`);
+	}
+
+	// If sameSite is "none", secure must be true
+	if (sameSite === "none" && !secure) {
+		throw new TypeError(`SameSite=None requires Secure flag to be true`);
+	}
+}
+
 /**
  * Represents a cookie.
  * @implements {CookieInfo}
@@ -88,6 +112,12 @@ class Cookie {
 	 */
 	httpOnly;
 
+	/**
+	 * The SameSite attribute of the cookie.
+	 * @type {SameSiteType}
+	 */
+	sameSite;
+
 	/**
 	 * Creates a new CookieData instance.
 	 * @param {Object} options The options for the cookie.
@@ -97,6 +127,7 @@ class Cookie {
 	 * @param {string} [options.path=""] The path of the cookie.
 	 * @param {boolean} [options.secure=false] The secure flag of the cookie.
 	 * @param {boolean} [options.httpOnly=false] The HTTP-only flag of the cookie.
+	 * @param {SameSiteType} [options.sameSite="lax"] The SameSite attribute of the cookie.
 	 */
 	constructor({
 		name,
@@ -105,6 +136,7 @@ class Cookie {
 		path = "/",
 		secure = false,
 		httpOnly = false,
+		sameSite = "lax",
 	}) {
 		assertValidDomain(domain);
 
@@ -116,12 +148,15 @@ class Cookie {
 			throw new TypeError("Cookie value is required.");
 		}
 
+		assertValidSameSite(sameSite, secure);
+
 		this.name = name;
 		this.value = value;
 		this.domain = /** @type {string} */ (domain);
 		this.path = path;
 		this.secure = secure;
 		this.httpOnly = httpOnly;
+		this.sameSite = sameSite;
 	}
 
 	/**
@@ -142,11 +177,58 @@ class Cookie {
 	isCredentialForRequest(request) {
 		const url = parseUrl(request.url);
 
-		return (
+		// Basic checks for domain, path, and secure flag
+		const basicChecks =
 			url.hostname.endsWith(this.domain) &&
 			url.pathname.startsWith(this.path) &&
-			(this.secure ? url.protocol === "https:" : true)
-		);
+			(this.secure ? url.protocol === "https:" : true);
+
+		if (!basicChecks) {
+			return false;
+		}
+
+		// Check SameSite attribute
+		if (this.sameSite) {
+			const requestOrigin = request.headers?.get("Origin");
+
+			switch (this.sameSite) {
+				case "strict":
+					// Only send cookie if the request came from the same origin
+					if (requestOrigin && requestOrigin !== url.origin) {
+						return false;
+					}
+					break;
+
+				case "lax":
+					// Permit cookies for navigation to top-level document via "safe" methods
+					// For simplicity, we'll only block cross-origin non-GET requests in Lax mode
+					if (
+						requestOrigin &&
+						requestOrigin !== url.origin &&
+						request.method !== "GET"
+					) {
+						return false;
+					}
+					break;
+
+				case "none":
+					// Allow cross-origin requests, but cookie must be Secure
+					// We already validated secure flag in the constructor
+					break;
+
+				default:
+					// Default to Lax behavior
+					if (
+						requestOrigin &&
+						requestOrigin !== url.origin &&
+						request.method !== "GET"
+					) {
+						return false;
+					}
+			}
+		}
+
+		return true;
 	}
 
 	/**
@@ -172,6 +254,10 @@ class Cookie {
 			cookieString += `; Path=${this.path}`;
 		}
 
+		if (this.sameSite) {
+			cookieString += `; SameSite=${this.sameSite}`;
+		}
+
 		if (this.secure) {
 			cookieString += `; Secure`;
 		}

tests/cookie-credentials.test.js

@@ -151,6 +151,60 @@ describe("CookieCredentials", () => {
 				}, /value is required/gi);
 			});
 		});
+
+		describe("with sameSite", () => {
+			it("should set a cookie with sameSite=strict", () => {
+				const credentials = new CookieCredentials(BASE_URL);
+				credentials.setCookie({
+					name: "session",
+					value: "123",
+					sameSite: "strict",
+				});
+			});
+
+			it("should set a cookie with sameSite=lax", () => {
+				const credentials = new CookieCredentials(BASE_URL);
+				credentials.setCookie({
+					name: "session",
+					value: "123",
+					sameSite: "lax",
+				});
+			});
+
+			it("should set a cookie with sameSite=none if secure=true", () => {
+				const credentials = new CookieCredentials(BASE_URL);
+				credentials.setCookie({
+					name: "session",
+					value: "123",
+					sameSite: "none",
+					secure: true,
+				});
+			});
+
+			it("should throw an error when sameSite=none without secure=true", () => {
+				const credentials = new CookieCredentials(BASE_URL);
+
+				assert.throws(() => {
+					credentials.setCookie({
+						name: "session",
+						value: "123",
+						sameSite: "none",
+					});
+				}, /SameSite=None requires Secure flag to be true/gi);
+			});
+
+			it("should throw an error with invalid sameSite value", () => {
+				const credentials = new CookieCredentials(BASE_URL);
+
+				assert.throws(() => {
+					credentials.setCookie({
+						name: "session",
+						value: "123",
+						sameSite: "invalid",
+					});
+				}, /Invalid sameSite value/gi);
+			});
+		});
 	});
 
 	describe("deleteCookie()", () => {
@@ -383,5 +437,85 @@ describe("CookieCredentials", () => {
 				assert.strictEqual(headers.get("Cookie"), null);
 			});
 		});
+
+		describe("with sameSite", () => {
+			it("should include cookie with sameSite=strict for same-origin requests", () => {
+				const credentials = new CookieCredentials(BASE_URL);
+				credentials.setCookie({
+					name: "session",
+					value: "123",
+					sameSite: "strict",
+				});
+
+				const request = new Request(BASE_URL);
+				const headers = credentials.getHeadersForRequest(request);
+				assert.strictEqual(headers.get("Cookie"), "session=123");
+			});
+
+			it("should not include cookie with sameSite=strict for cross-origin requests", () => {
+				const credentials = new CookieCredentials(BASE_URL);
+				credentials.setCookie({
+					name: "session",
+					value: "123",
+					sameSite: "strict",
+				});
+
+				const request = new Request(BASE_URL);
+				// Simulate a cross-origin request by adding an Origin header
+				request.headers.set("Origin", "https://different-origin.com");
+
+				const headers = credentials.getHeadersForRequest(request);
+				assert.strictEqual(headers.get("Cookie"), null);
+			});
+
+			it("should include cookie with sameSite=lax for cross-origin GET requests", () => {
+				const credentials = new CookieCredentials(BASE_URL);
+				credentials.setCookie({
+					name: "session",
+					value: "123",
+					sameSite: "lax",
+				});
+
+				const request = new Request(BASE_URL, { method: "GET" });
+				// Simulate a cross-origin request by adding an Origin header
+				request.headers.set("Origin", "https://different-origin.com");
+
+				const headers = credentials.getHeadersForRequest(request);
+				assert.strictEqual(headers.get("Cookie"), "session=123");
+			});
+
+			it("should not include cookie with sameSite=lax for cross-origin POST requests", () => {
+				const credentials = new CookieCredentials(BASE_URL);
+				credentials.setCookie({
+					name: "session",
+					value: "123",
+					sameSite: "lax",
+				});
+
+				const request = new Request(BASE_URL, { method: "POST" });
+				// Simulate a cross-origin request by adding an Origin header
+				request.headers.set("Origin", "https://different-origin.com");
+
+				const headers = credentials.getHeadersForRequest(request);
+				assert.strictEqual(headers.get("Cookie"), null);
+			});
+
+			it("should include cookie with sameSite=none for cross-origin requests", () => {
+				const credentials = new CookieCredentials(BASE_URL);
+				credentials.setCookie({
+					name: "session",
+					value: "123",
+					sameSite: "none",
+					secure: true,
+				});
+
+				const request = new Request(BASE_URL, { method: "POST" });
+				// Simulate a cross-origin request by adding an Origin header
+				request.headers.set("Origin", "https://different-origin.com");
+
+				const headers = credentials.getHeadersForRequest(request);
+				assert.strictEqual(headers.get("Cookie"), "session=123");
+			});
+		});
 	});
 });