@everystack/server 0.2.19 → 0.2.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/server",
-  "version": "0.2.19",
+  "version": "0.2.20",
   "description": "Server runtime primitives for Lambda — event adapters, routing, SSR, image processing",
   "license": "AGPL-3.0-only",
   "publishConfig": {

package/src/index.ts

@@ -55,9 +55,22 @@ export interface LogSink {
 
 /** Cache-Control configuration for the Lambda handler's fallback headers. */
 export interface ServerCacheConfig {
-  /** Unauthenticated GET/HEAD responses.
+  /** Unauthenticated GET/HEAD responses with a non-HTML body (e.g. JSON API).
    *  Default: 'public, max-age=60, s-maxage=2592000, stale-while-revalidate=5' */
   public?: string;
+  /** Unauthenticated GET/HEAD HTML responses (SSR documents).
+   *  INVARIANT: SSR HTML is a PUBLIC shell — it must NOT be personalized.
+   *  Personalization happens on client rehydrate, never in the server-rendered
+   *  document. This is what makes public edge-caching safe; rendering per-user
+   *  data into the SSR HTML would let the edge serve one user's page to another.
+   *
+   *  HTML pins content-hashed chunk names, so it is the mutable entry point and
+   *  must turn over fast — unlike the immutable chunks it references. A short
+   *  s-maxage bounds edge staleness (incl. the version-key empty-`_v` fallback)
+   *  so `cache:purge --origin web` / any deploy refreshes HTML within the TTL,
+   *  with no CloudFront invalidation. No stale-while-revalidate: the cap is hard.
+   *  Default: 'public, max-age=0, s-maxage=60' */
+  html?: string;
   /** Authenticated GET/HEAD responses.
    *  Default: 'private, no-store' */
   private?: string;
@@ -260,9 +273,18 @@ export function createLambdaHandler(
       if (!result.headers['cache-control']) {
         if (method === 'GET' || method === 'HEAD') {
           const isAuthenticated = !!httpEvent.headers?.authorization;
-          result.headers['cache-control'] = isAuthenticated
-            ? (options.cache?.private ?? 'private, no-store')
-            : (options.cache?.public ?? 'public, max-age=60, s-maxage=2592000, stale-while-revalidate=5');
+          if (isAuthenticated) {
+            result.headers['cache-control'] = options.cache?.private ?? 'private, no-store';
+          } else {
+            // SSR HTML is a PUBLIC shell (never personalized — personalization
+            // happens on client rehydrate), so it caches public but must turn
+            // over fast: short s-maxage, no SWR → hard ≤60s edge cap. JSON/API
+            // GETs are version-keyed and can cache long.
+            const isHtml = String(result.headers['content-type'] || '').includes('text/html');
+            result.headers['cache-control'] = isHtml
+              ? (options.cache?.html ?? 'public, max-age=0, s-maxage=60')
+              : (options.cache?.public ?? 'public, max-age=60, s-maxage=2592000, stale-while-revalidate=5');
+          }
         } else {
           result.headers['cache-control'] = options.cache?.mutation ?? 'no-store';
         }

package/src/plugin.ts

@@ -240,9 +240,17 @@ export function createPluginLambdaHandler(
       if (!result.headers['cache-control']) {
         if (method === 'GET' || method === 'HEAD') {
           const isAuthenticated = !!httpEvent.headers?.authorization;
-          result.headers['cache-control'] = isAuthenticated
-            ? (options.cache?.private ?? 'private, no-store')
-            : (options.cache?.public ?? 'public, max-age=60, s-maxage=2592000, stale-while-revalidate=5');
+          if (isAuthenticated) {
+            result.headers['cache-control'] = options.cache?.private ?? 'private, no-store';
+          } else {
+            // SSR HTML is the mutable, version-pinning document — it must turn
+            // over fast (short s-maxage, no SWR → hard ≤60s edge cap). JSON/API
+            // GETs are version-keyed and can cache long at the edge.
+            const isHtml = String(result.headers['content-type'] || '').includes('text/html');
+            result.headers['cache-control'] = isHtml
+              ? (options.cache?.html ?? 'public, max-age=0, s-maxage=60')
+              : (options.cache?.public ?? 'public, max-age=60, s-maxage=2592000, stale-while-revalidate=5');
+          }
         } else {
           result.headers['cache-control'] = options.cache?.mutation ?? 'no-store';
         }
@@ -363,6 +371,20 @@ interface SsrContext extends PluginContext {
  *   fallback: ssrPlugin(),
  *   fallback: ssrPlugin({ postProcessHtml: injectJsonLd }),
  */
+/**
+ * Re-stamp an SSR response as private/uncacheable, preserving status + body.
+ * Used when the SSR ran with a resolved cookie-user (potentially personalized).
+ */
+function withPrivateCache(response: Response): Response {
+  const headers = new Headers(response.headers);
+  headers.set('cache-control', 'private, no-store');
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+}
+
 export function ssrPlugin(options: SsrPluginOptions = {}): (ctx: PluginContext) => Promise<Handler> {
   return async (ctx: PluginContext): Promise<Handler> => {
     const { getWebHandler } = await import('./ssr');
@@ -405,7 +427,16 @@ export function ssrPlugin(options: SsrPluginOptions = {}): (ctx: PluginContext)
             }
           }
         }
-        return runWithAuthContext(user, () => webHandler(request));
+        const response = await runWithAuthContext(user, () => webHandler(request));
+        // SECURITY: when the SSR ran with a cookie-resolved user, the response
+        // may be personalized. The edge cache-control default keys on the
+        // Authorization header (absent for cookie auth), so without this such a
+        // response would be cached `public` and could be served to other users
+        // (HTML 60s, but loader-data JSON 30 days). Force it private so a
+        // personalized SSR response can never be public-cached. Anonymous SSR
+        // (no resolved user) stays publicly cacheable — the public shell / SEO
+        // path, which by invariant is never personalized.
+        return user ? withPrivateCache(response) : response;
       }
 
       return webHandler(request);