feat(19.3-06): purge route accepts proxied requests on siteCache.allowProxied (WR-03)

- runtimeConfig.siteCache.allowProxied (NUXT_SITE_CACHE_ALLOW_PROXIED, default
  false) lets the shared purge route accept a request that came through a
  TLS-terminating proxy; the bearer token is then the only gate
- shared lib, route and spec stay byte-identical across the three layers,
  with updated sha256 pins and two new sitePurge specs

- version 0.5.0

server/api/__site__/cache/purge.post.ts

@@ -6,9 +6,12 @@
 // and slug only reach the log line.
 //
 // 404 without a token of at least 32 characters, and for any request that
-// came through a reverse proxy (X-Forwarded-For, X-Real-IP or Forwarded);
-// 401 for a missing or wrong bearer token. The '/api/__site__/**' route rule
-// keeps this route out of the route cache.
+// came through a reverse proxy (X-Forwarded-For, X-Real-IP or Forwarded)
+// unless runtimeConfig.siteCache.allowProxied (NUXT_SITE_CACHE_ALLOW_PROXIED)
+// is true or "true": a backend that reaches the site through a TLS-terminating
+// proxy opts in, and the bearer token is then the only gate. 401 for a
+// missing or wrong bearer token. The '/api/__site__/**' route rule keeps this
+// route out of the route cache.
 //
 // Shared: several layers ship this file byte for byte, and Nitro keeps one
 // handler per route and method.
@@ -20,10 +23,12 @@ const PROXY_HEADERS = ['x-forwarded-for', 'x-real-ip', 'forwarded']
 export default defineEventHandler(async (event) => {
   setResponseHeader(event, 'cache-control', 'no-store')
   const config = useRuntimeConfig(event)
+  const siteCache = config.siteCache as { purgeToken?: unknown; allowProxied?: unknown } | undefined
   const verdict = authorizeSitePurge({
-    token: (config.siteCache as { purgeToken?: unknown } | undefined)?.purgeToken,
+    token: siteCache?.purgeToken,
     authorization: getRequestHeader(event, 'authorization'),
     proxied: PROXY_HEADERS.some((name) => getRequestHeader(event, name) !== undefined),
+    allowProxied: siteCache?.allowProxied === true || siteCache?.allowProxied === 'true',
   })
   if (verdict === 'disabled' || verdict === 'proxied') {
     throw createError({ statusCode: 404, statusMessage: 'Not Found' })

server/lib/siteCachePurge.ts

@@ -27,6 +27,12 @@ export interface SitePurgeAuthInput {
   authorization?: string | null
   /** True when the request carried X-Forwarded-For, X-Real-IP or Forwarded. */
   proxied: boolean
+  /**
+   * runtimeConfig.siteCache.allowProxied: when true a proxied request is not
+   * refused, and the bearer token is the only gate. For a backend that reaches
+   * the site through a TLS-terminating proxy, which adds forwarding headers.
+   */
+  allowProxied?: boolean
 }
 
 function digest(value: string): Buffer {
@@ -36,13 +42,14 @@ function digest(value: string): Buffer {
 /**
  * Decides a purge request: `disabled` when no token of at least
  * MIN_SITE_PURGE_TOKEN_LENGTH characters is configured, `proxied` when the
- * request came through a reverse proxy (checked before the token), `ok` when
- * the Bearer value equals the token (compared in constant time over sha256
- * digests) and `unauthorized` otherwise.
+ * request came through a reverse proxy (checked before the token) unless
+ * allowProxied is true, `ok` when the Bearer value equals the token (compared
+ * in constant time over sha256 digests) and `unauthorized` otherwise. With
+ * allowProxied the token is the only gate, so it must stay long and secret.
  */
-export function authorizeSitePurge({ token, authorization, proxied }: SitePurgeAuthInput): SitePurgeVerdict {
+export function authorizeSitePurge({ token, authorization, proxied, allowProxied }: SitePurgeAuthInput): SitePurgeVerdict {
   if (typeof token !== 'string' || token.length < MIN_SITE_PURGE_TOKEN_LENGTH) return 'disabled'
-  if (proxied) return 'proxied'
+  if (proxied && allowProxied !== true) return 'proxied'
   const m = /^Bearer[ \t]+(\S+)[ \t]*$/i.exec(authorization ?? '')
   if (!m) return 'unauthorized'
   return timingSafeEqual(digest(m[1]), digest(token)) ? 'ok' : 'unauthorized'