fix(web): method allowlist, HEAD support, and cache hygiene for server function requests (#3069, #3071)

HEAD (and PUT/DELETE/PATCH) requests bypassed the GET method gate and
executed any registered server function. The gate is now an allowlist:
POST always dispatches, GET/HEAD dispatch only to GET-declared functions
(HEAD strips the body per spec), everything else answers 405.

Responses default to Cache-Control: no-store unless the function set its
own policy, and declared reads skip the CSRF origin gate so their
responses drop the Vary: Sec-Fetch-Site, Origin, Referer that defeated
shared-cache storage of GET responses.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: ryansolid

.changeset/server-function-http-hygiene.md

@@ -0,0 +1,5 @@
+---
+"@solidjs/web": patch
+---
+
+Harden the server function handler's HTTP layer. The method gate is now an allowlist: POST always dispatches, GET and HEAD dispatch only to `GET`-declared functions, and every other verb answers 405 — previously a HEAD (or PUT/DELETE/PATCH) request bypassed the GET gate entirely and executed any registered function with attacker-chosen query arguments (#3069). HEAD runs the function like GET and strips the body per spec. Responses now default to `Cache-Control: no-store` unless the function set its own cache policy, and GET/HEAD requests to `GET`-declared functions skip the CSRF origin gate so their responses no longer carry the `Vary: Sec-Fetch-Site, Origin, Referer` that fragmented shared-cache entries — declared reads are protected by same-origin policy, and caching becomes opt-in on the wire instead of just in prose (#3071).

packages/web/server-functions/src/server.ts

@@ -1491,17 +1491,26 @@ function forbiddenResponse() {
   );
 } /**
  * Web-standard HTTP handler for server function calls: resolves the
- * function id from the request, gates GET dispatch on the declaration (405
- * for a GET request to a function that never declared `GET`; POST is always
- * accepted), decodes arguments, runs the function under a request-event scope,
- * and encodes the result (forwarding redirect/revalidation metadata
- * through headers). Mount it on the endpoint the client transport targets
- * (default `/_server`); platform adapters (h3, express, ...) convert their
- * request shape to a web `Request` around it.
+ * function id from the request, enforces the method allowlist (POST always
+ * dispatches; GET and HEAD dispatch only to functions that declared `GET`,
+ * with HEAD returning the equivalent GET's status and headers minus the
+ * body; every other method answers 405), decodes arguments, runs the
+ * function under a request-event scope, and encodes the result (forwarding
+ * redirect/revalidation metadata through headers). Mount it on the endpoint
+ * the client transport targets (default `/_server`); platform adapters (h3,
+ * express, ...) convert their request shape to a web `Request` around it.
  *
  * Requests are same-origin by default. The handler accepts browser requests
  * proven by `Sec-Fetch-Site`, `Origin`, or `Referer`, and rejects requests
- * without usable metadata unless explicitly configured otherwise.
+ * without usable metadata unless explicitly configured otherwise. GET/HEAD
+ * requests to `GET`-declared functions skip this gate: they are reads by
+ * contract, cross-site response READING is already blocked by same-origin
+ * policy, and skipping it keeps the `Vary: Sec-Fetch-Site, Origin, Referer`
+ * it would impose off the responses shared caches are meant to store.
+ *
+ * Every response leaves with `Cache-Control: no-store` unless the function
+ * set its own cache policy (via `respond()` headers or a returned
+ * `Response`) — caching is opt-in on the wire, not just in prose.
  *
  * When the event carries a `response` head stub (`event.response`, see the
  * server entry's `ResponseStub`), the handler folds it onto every outgoing
@@ -1608,17 +1617,28 @@ export function handleServerFunctionRequest(
 export async function handleServerFunctionRequest(request, options = {}) {
   const codec = options.codec !== undefined ? options.codec : getServerFunctionsCodec();
   const url = new URL(request.url);
+  const method = request.method;
+  const functionId = resolveFunctionId(request, url);
+  // GET-declared functions are reads by contract, and the read methods are
+  // exactly where the CSRF gate costs more than it buys: same-origin policy
+  // already prevents a cross-site caller from READING the response, while
+  // the gate's `Vary: Sec-Fetch-Site, Origin, Referer` fragments (or, on
+  // CDNs that ignore Vary, poisons) the shared-cache entries the GET helper
+  // exists to enable (#3071). State-changing dispatch (POST) stays gated.
+  const declaredRead =
+    (method === "GET" || method === "HEAD") &&
+    functionId !== null &&
+    METHODS.get(functionId) === "GET";
   const csrf = options.csrf !== undefined ? options.csrf : config.csrf;
-  const protectsRequest = csrf !== false;
+  const protectsRequest = csrf !== false && !declaredRead;
   if (protectsRequest && !(await allowsServerFunctionRequest(request, csrf === true ? {} : csrf))) {
-    return forbiddenResponse();
+    return finalizeTransportResponse(forbiddenResponse(), method);
   }
   const instance = request.headers.get(INSTANCE_HEADER);
-  const functionId = resolveFunctionId(request, url);
 
   if (!functionId) {
     const response = new Response(DEV ? "Server function not found" : null, { status: 404 });
-    return protectsRequest ? withCSRFVary(response) : response;
+    return finalizeTransportResponse(protectsRequest ? withCSRFVary(response) : response, method);
   }
 
   let serverFunction;
@@ -1628,24 +1648,27 @@ export async function handleServerFunctionRequest(request, options = {}) {
     const response = new Response(DEV ? `Unknown server function: ${functionId}` : null, {
       status: 404
     });
-    return protectsRequest ? withCSRFVary(response) : response;
+    return finalizeTransportResponse(protectsRequest ? withCSRFVary(response) : response, method);
   }
 
-  // method enforcement: GET requests only dispatch to functions that
-  // declared GET (the server half of `GET` records them) — no crafted GET
-  // URLs against functions that never opted in. Declaring GET grants GET
-  // without revoking POST: the same function stays callable over the
-  // default transport (e.g. a query()-wrapped function also called
-  // directly).
-  if (request.method === "GET" && METHODS.get(functionId) !== "GET") {
+  // Method allowlist: POST always dispatches (the default transport);
+  // GET and HEAD dispatch only to functions that declared GET (the server
+  // half of `GET` records them) — no crafted read URLs against functions
+  // that never opted in, and no side door through OTHER verbs either
+  // (before #3069 a HEAD — sent freely by link checkers, uptime probes and
+  // prefetchers — bypassed the gate entirely and executed any registered
+  // function). Declaring GET grants the read methods without revoking POST:
+  // the same function stays callable over the default transport (e.g. a
+  // query()-wrapped function also called directly).
+  if (method !== "POST" && !declaredRead) {
     const response = new Response(
       DEV ? `Method not allowed for server function: ${functionId}` : null,
       {
         status: 405,
-        headers: { Allow: "POST" }
+        headers: { Allow: METHODS.get(functionId) === "GET" ? "POST, GET, HEAD" : "POST" }
       }
     );
-    return protectsRequest ? withCSRFVary(response) : response;
+    return finalizeTransportResponse(protectsRequest ? withCSRFVary(response) : response, method);
   }
 
   const event = options.createEvent ? options.createEvent(request) : { request, locals: {} };
@@ -1875,5 +1898,47 @@ export async function handleServerFunctionRequest(request, options = {}) {
     }
   };
   const response = commitEventResponse(await dispatch(), event);
-  return protectsRequest ? withCSRFVary(response) : response;
+  return finalizeTransportResponse(protectsRequest ? withCSRFVary(response) : response, method);
+}
+
+/**
+ * Last-mile transport hygiene applied to every response leaving the handler.
+ *
+ * - `Cache-Control: no-store` unless the function set its own (via
+ *   `respond()` headers or a returned Response): caching is opt-in ON THE
+ *   WIRE the way the docs describe it in prose. Without the default, CDN
+ *   zones with override-TTL or "cache everything" rules store per-user RPC
+ *   responses (#3071).
+ * - HEAD responses drop their body, as HTTP requires — the function still
+ *   ran (HEAD is gated identically to GET), so status and headers are those
+ *   of the equivalent GET (#3069).
+ */
+function finalizeTransportResponse(response, method) {
+  const stripBody = method === "HEAD" && response.body !== null;
+  if (stripBody || !response.headers.has("Cache-Control")) {
+    try {
+      if (!response.headers.has("Cache-Control")) {
+        response.headers.set("Cache-Control", "no-store");
+      }
+      if (!stripBody) return response;
+      // discard, don't leak: the encoded body may be a live codec stream
+      response.body.cancel().catch(() => {});
+      return new Response(null, {
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers
+      });
+    } catch {
+      // immutable headers (e.g. a raw fetch() Response passed through)
+      const headers = new Headers(response.headers);
+      if (!headers.has("Cache-Control")) headers.set("Cache-Control", "no-store");
+      if (stripBody) response.body.cancel().catch(() => {});
+      return new Response(stripBody ? null : response.body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers
+      });
+    }
+  }
+  return response;
 }

packages/web/test/server/server-functions-http-hygiene.spec.tsx

@@ -0,0 +1,200 @@
+/**
+ * HTTP-layer hygiene of `handleServerFunctionRequest` (#3069, #3071):
+ *
+ * - The method allowlist: POST always dispatches; GET and HEAD dispatch only
+ *   to `GET`-declared functions (HEAD used to bypass the gate entirely and
+ *   execute any registered function); every other verb answers 405.
+ * - HEAD responses carry the equivalent GET's status and headers, minus the
+ *   body.
+ * - GET/HEAD requests to declared functions skip the CSRF gate, so their
+ *   responses carry no `Vary: Sec-Fetch-Site, Origin, Referer` and shared
+ *   caches can store them. POST dispatch stays gated.
+ * - Every response defaults to `Cache-Control: no-store` unless the function
+ *   set its own cache policy — caching is opt-in on the wire.
+ *
+ * Runs against the built bundles like the other server-function specs.
+ */
+import { describe, expect, it, vi } from "vitest";
+import {
+  GET as serverGET,
+  createServerReference,
+  handleServerFunctionRequest,
+  registerServerFunction,
+  registerServerReference
+} from "@solidjs/web/server-functions/server";
+
+const provideEvent = <T,>(_event: unknown, run: () => T): T => run();
+
+function readRequest(id: string, method: string, headers: Record<string, string> = {}) {
+  return new Request(`https://app.example/_server?id=${id}`, { method, headers });
+}
+
+function postRequest(id: string, headers: Record<string, string> = {}) {
+  return new Request("https://app.example/_server", {
+    method: "POST",
+    headers: {
+      "Sec-Fetch-Site": "same-origin",
+      ...headers,
+      "X-Server-Function-Id": id,
+      "X-Server-Function-Instance": "server-function:test"
+    }
+  });
+}
+
+function declareGET(id: string, fn: (...args: any[]) => any) {
+  serverGET(createServerReference(registerServerReference(id, fn)));
+}
+
+describe("server-function method allowlist (#3069)", () => {
+  it("gates HEAD exactly like GET: 405 for undeclared functions, nothing executes", async () => {
+    const fn = vi.fn(async () => "side effect happened");
+    registerServerFunction("hygiene-post-only", fn);
+
+    for (const method of ["HEAD", "GET"]) {
+      const response = await handleServerFunctionRequest(
+        readRequest("hygiene-post-only", method, { "Sec-Fetch-Site": "same-origin" }),
+        { provideEvent }
+      );
+      expect(response.status).toBe(405);
+      expect(response.headers.get("Allow")).toBe("POST");
+    }
+    expect(fn).not.toHaveBeenCalled();
+  });
+
+  it("rejects other verbs too — the gate is an allowlist, not a GET special case", async () => {
+    const fn = vi.fn(async () => "ok");
+    registerServerFunction("hygiene-verbs", fn);
+
+    for (const method of ["PUT", "DELETE", "PATCH"]) {
+      const response = await handleServerFunctionRequest(
+        new Request("https://app.example/_server?id=hygiene-verbs", {
+          method,
+          headers: { "Sec-Fetch-Site": "same-origin" }
+        }),
+        { provideEvent }
+      );
+      expect(response.status).toBe(405);
+    }
+    expect(fn).not.toHaveBeenCalled();
+
+    // and on a GET-declared function the Allow header advertises the reads
+    declareGET("hygiene-declared-verbs", async () => "ok");
+    const response = await handleServerFunctionRequest(
+      new Request("https://app.example/_server?id=hygiene-declared-verbs", {
+        method: "PUT",
+        headers: { "Sec-Fetch-Site": "same-origin" }
+      }),
+      { provideEvent }
+    );
+    expect(response.status).toBe(405);
+    expect(response.headers.get("Allow")).toBe("POST, GET, HEAD");
+  });
+
+  it("HEAD on a declared function runs it and returns the GET response minus the body", async () => {
+    let calls = 0;
+    declareGET("hygiene-head-ok", async (n: number = 1) => {
+      calls++;
+      return { doubled: n * 2 };
+    });
+
+    const get = await handleServerFunctionRequest(readRequest("hygiene-head-ok", "GET"), {
+      provideEvent
+    });
+    expect(get.status).toBe(200);
+    expect(await get.json()).toEqual({ doubled: 2 });
+
+    const head = await handleServerFunctionRequest(readRequest("hygiene-head-ok", "HEAD"), {
+      provideEvent
+    });
+    expect(head.status).toBe(200);
+    expect(head.body).toBeNull();
+    expect(head.headers.get("Content-Type")).toBe(get.headers.get("Content-Type"));
+    expect(calls).toBe(2);
+  });
+});
+
+describe("server-function cache hygiene (#3071)", () => {
+  it("declared reads skip the CSRF gate: no origin proof required, no Vary emitted", async () => {
+    declareGET("hygiene-read-ungated", async () => ({ who: "public menu" }));
+
+    // no Sec-Fetch-Site / Origin / Referer at all — a CDN edge or curl
+    const bare = await handleServerFunctionRequest(readRequest("hygiene-read-ungated", "GET"), {
+      provideEvent
+    });
+    expect(bare.status).toBe(200);
+    expect(bare.headers.get("Vary")).toBeNull();
+
+    // even explicitly cross-site: SOP already blocks cross-origin reads
+    const crossSite = await handleServerFunctionRequest(
+      readRequest("hygiene-read-ungated", "GET", { "Sec-Fetch-Site": "cross-site" }),
+      { provideEvent }
+    );
+    expect(crossSite.status).toBe(200);
+  });
+
+  it("POST dispatch stays gated and keeps its Vary", async () => {
+    const fn = vi.fn(async () => "ok");
+    registerServerFunction("hygiene-post-gated", fn);
+
+    const rejected = await handleServerFunctionRequest(
+      postRequest("hygiene-post-gated", { "Sec-Fetch-Site": "cross-site" }),
+      { provideEvent }
+    );
+    expect(rejected.status).toBe(403);
+    expect(fn).not.toHaveBeenCalled();
+
+    const accepted = await handleServerFunctionRequest(postRequest("hygiene-post-gated"), {
+      provideEvent
+    });
+    expect(accepted.status).toBe(200);
+    expect(accepted.headers.get("Vary")).toBe("Sec-Fetch-Site, Origin, Referer");
+  });
+
+  it("defaults every response to Cache-Control: no-store", async () => {
+    registerServerFunction("hygiene-no-store", async () => ({ private: true }));
+    declareGET("hygiene-no-store-get", async () => ({ public: true }));
+
+    const post = await handleServerFunctionRequest(postRequest("hygiene-no-store"), {
+      provideEvent
+    });
+    expect(post.status).toBe(200);
+    expect(post.headers.get("Cache-Control")).toBe("no-store");
+
+    // opt-in stays opt-in even for declared reads
+    const get = await handleServerFunctionRequest(readRequest("hygiene-no-store-get", "GET"), {
+      provideEvent
+    });
+    expect(get.headers.get("Cache-Control")).toBe("no-store");
+
+    const missing = await handleServerFunctionRequest(
+      readRequest("hygiene-nonexistent", "GET", { "Sec-Fetch-Site": "same-origin" }),
+      { provideEvent }
+    );
+    expect(missing.status).toBe(404);
+    expect(missing.headers.get("Cache-Control")).toBe("no-store");
+
+    const undeclared = await handleServerFunctionRequest(
+      readRequest("hygiene-no-store", "GET", { "Sec-Fetch-Site": "same-origin" }),
+      { provideEvent }
+    );
+    expect(undeclared.status).toBe(405);
+    expect(undeclared.headers.get("Cache-Control")).toBe("no-store");
+  });
+
+  it("preserves a cache policy the function set itself", async () => {
+    declareGET(
+      "hygiene-opt-in",
+      async () => new Response(null, { headers: { "Cache-Control": "public, max-age=60" } })
+    );
+
+    const response = await handleServerFunctionRequest(
+      new Request("https://app.example/_server?id=hygiene-opt-in", {
+        method: "GET",
+        headers: { "X-Server-Function-Instance": "server-function:test" }
+      }),
+      { provideEvent }
+    );
+    expect(response.status).toBe(200);
+    expect(response.headers.get("Cache-Control")).toBe("public, max-age=60");
+  });
+});