perf(router): skip known-empty security probes

Author: chrisbbreuer

storage/framework/core/router/src/security-headers.ts

@@ -77,25 +77,27 @@ function resolveCsp(): { header: string, value: string } | null {
  *
  * Skips overwriting any header that's already set — explicit userland
  * config wins. Skips entirely when `STACKS_SECURITY_HEADERS_DISABLE=true`.
+ * `knownMissing` is reserved for router-created responses whose security
+ * headers are known to be absent, avoiding redundant native lookups.
  */
-export function applySecurityHeaders(headers: Headers): void {
+export function applySecurityHeaders(headers: Headers, knownMissing = false): void {
   if (isDisabled())
     return
 
-  if (headers.get('X-Content-Type-Options') === null)
+  if (knownMissing || headers.get('X-Content-Type-Options') === null)
     headers.set('X-Content-Type-Options', 'nosniff')
 
-  if (headers.get('X-Frame-Options') === null)
+  if (knownMissing || headers.get('X-Frame-Options') === null)
     headers.set('X-Frame-Options', 'SAMEORIGIN')
 
-  if (headers.get('Referrer-Policy') === null)
+  if (knownMissing || headers.get('Referrer-Policy') === null)
     headers.set('Referrer-Policy', 'strict-origin-when-cross-origin')
 
-  if (isProduction() && headers.get('Strict-Transport-Security') === null)
+  if (isProduction() && (knownMissing || headers.get('Strict-Transport-Security') === null))
     headers.set('Strict-Transport-Security', 'max-age=31536000; includeSubDomains')
 
   const csp = resolveCsp()
-  if (csp && headers.get(csp.header) === null)
+  if (csp && (knownMissing || headers.get(csp.header) === null))
     headers.set(csp.header, csp.value)
 }
 

storage/framework/core/router/src/stacks-router.ts

@@ -603,6 +603,7 @@ const routeActionRegistry = new Map<string, RouterAction>()
 /** HTTP methods that mutate state and therefore need CSRF protection. */
 const CSRF_PROTECTED_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE'])
 const CSRF_SEEDED_BY_HANDLE_REQUEST = Symbol.for('stacks.router.csrfSeededByHandleRequest')
+const FRAMEWORK_SECURITY_HEADERS_MISSING = Symbol('stacks.router.frameworkSecurityHeadersMissing')
 
 interface ResolvedMiddleware {
   name: string
@@ -2015,7 +2016,9 @@ function createMiddlewareHandler(routeKey: string, handler: StacksHandler): Rout
           }
           h.set('Server-Timing', timing)
         }
-        applySecurityHeaders(h)
+        const frameworkHeadersAreMissing = (response as unknown as Record<symbol, unknown>)[FRAMEWORK_SECURITY_HEADERS_MISSING] === true
+          && !requested
+        applySecurityHeaders(h, frameworkHeadersAreMissing)
       }
 
       if (response && typeof (response).headers?.set === 'function') {
@@ -2936,8 +2939,11 @@ function formatResult(result: unknown, req: EnhancedRequest): Response {
 /** Serialize JSON once and make its size available to compression. */
 function formatJsonResult(result: unknown, req: EnhancedRequest, linkHeader?: string | null): Response {
   const encoding = req.headers.get('accept-encoding')
-  if (!encoding || encoding === 'identity')
-    return linkHeader ? Response.json(result, { headers: { Link: linkHeader } }) : Response.json(result)
+  if (!encoding || encoding === 'identity') {
+    const response = linkHeader ? Response.json(result, { headers: { Link: linkHeader } }) : Response.json(result)
+    ;(response as unknown as Record<symbol, unknown>)[FRAMEWORK_SECURITY_HEADERS_MISSING] = true
+    return response
+  }
 
   // Give compression the byte length without making it consume and rebuild
   // the response stream just to check its threshold. Count UTF-8 bytes, not
@@ -2949,7 +2955,9 @@ function formatJsonResult(result: unknown, req: EnhancedRequest, linkHeader?: st
   }
   if (linkHeader)
     headers.Link = linkHeader
-  return new Response(body, { headers })
+  const response = new Response(body, { headers })
+  ;(response as unknown as Record<symbol, unknown>)[FRAMEWORK_SECURITY_HEADERS_MISSING] = true
+  return response
 }
 
 /**

storage/framework/core/router/tests/response-headers.test.ts

@@ -36,6 +36,12 @@ beforeAll(async () => {
     return new Response('ok', { status: 200 })
   })
 
+  route.get('/_mw_headers_security_override', (request: any) => {
+    request._responseHeaders = { 'X-Frame-Options': 'DENY' }
+
+    return { ok: true }
+  })
+
   server = await route.serve({ port: 0, hostname: '127.0.0.1' })
   port = Number(server?.port ?? server?.server?.port ?? 0)
 })
@@ -69,4 +75,10 @@ describe('_responseHeaders', () => {
 
     expect(answer.headers.get('X-Request-ID')).toBe('the-router-owns-this')
   })
+
+  it('can override a security default on a framework-created response', async () => {
+    const answer = await fetch(`http://127.0.0.1:${port}/_mw_headers_security_override`)
+
+    expect(answer.headers.get('X-Frame-Options')).toBe('DENY')
+  })
 })