Merge remote-tracking branch 'origin/main'

Author: harlan-zw

src/build/prerender.ts

@@ -21,6 +21,41 @@ export function setupPrerenderHandler(options: ModuleOptions, resolve: Resolver,
       // avoid wasm handling while prerendering
       nitroConfig.wasm = nitroConfig.wasm || {}
       nitroConfig.wasm.esmImport = false
+      // Dynamic OG URLs are runtime-only. Prevent nitro's crawler from picking
+      // them up via HTML meta extraction and writing them to disk as filenames,
+      // which would hit the filesystem 255-byte limit for long signed URLs.
+      nitroConfig.prerender = nitroConfig.prerender || {}
+      nitroConfig.prerender.ignore = nitroConfig.prerender.ignore || []
+      if (Array.isArray(nitroConfig.prerender.ignore))
+        nitroConfig.prerender.ignore.push('/_og/d/')
+    })
+
+    // Track hash-mode OG URLs whose source page isn't in the prerender graph.
+    // These 404 at context.ts because the page's defineOgImage() never ran so
+    // the hash:<hash> cache entry was never written. Clear the error so the build
+    // doesn't fail, and warn once at the end of prerender so users can investigate.
+    const orphanedOgHashes: string[] = []
+    nitro.hooks.hook('prerender:route', (route) => {
+      if (!route.error || route.error.statusCode !== 404)
+        return
+      if (!route.route.includes('/_og/s/o_'))
+        return
+      orphanedOgHashes.push(route.route)
+      route.error = undefined
+      route.contents = ''
+      route.fileName = undefined
+    })
+
+    nitro.hooks.hook('prerender:done', async () => {
+      if (orphanedOgHashes.length > 0) {
+        logger.warn(
+          `Skipped ${orphanedOgHashes.length} orphaned OG image hash URL${orphanedOgHashes.length > 1 ? 's' : ''} during prerender. `
+          + `These URLs were crawled from HTML but their source page was not prerendered, so the hash cache entry was never written. `
+          + `If your pages are prerendered but OG images are generated at runtime, enable \`security.strict\` with a \`security.secret\` to switch to signed dynamic URLs.`,
+        )
+        for (const route of orphanedOgHashes)
+          logger.info(`  ${route}`)
+      }
     })
 
     // Cleanup old build cache files after prerender

src/runtime/app/utils.ts

@@ -136,7 +136,10 @@ export function createOgImageMeta(src: string, input: OgImageOptions | OgImagePr
         }
         // Inline getOgImagePath logic: useRuntimeConfig() is unavailable in lazy callbacks
         const extension = opts.extension || defaults?.extension || 'png'
-        const isStatic = import.meta.prerender
+        // Force dynamic+signed URLs even during prerender when strict+secret are set.
+        // Otherwise /_og/s/ URLs baked into HTML are unsigned and 403 at runtime for
+        // setups where pages are prerendered but OG images are served dynamically.
+        const isStatic = import.meta.prerender && !(ogImageConfig.security?.secret && ogImageConfig.security?.strict)
         const urlOpts: Record<string, any> = { ...opts, _path: payloadBasePath }
         const componentName = opts.component || componentNames?.[0]?.pascalName
         const component = componentNames?.find((c: any) => c.pascalName === componentName || c.kebabName === componentName)
@@ -147,8 +150,11 @@ export function createOgImageMeta(src: string, input: OgImageOptions | OgImagePr
         const finalUrl = opts._query && Object.keys(opts._query).length
           ? withQuery(resolvedUrl, { _query: opts._query })
           : resolvedUrl
-        // Update prerender paths to match the lazily resolved URL
-        if (import.meta.prerender && ssrContext.event) {
+        // Update prerender paths to match the lazily resolved URL.
+        // Only emit for static URLs: dynamic (/_og/d/) URLs are runtime-only and
+        // must not be force-prerendered via x-nitro-prerender, because long ones
+        // would hit the filesystem 255-byte filename limit when nitro writes them.
+        if (isStatic && import.meta.prerender && ssrContext.event) {
           const prerenderPaths: Map<string, string> | undefined = ssrContext.event.context._ogImagePrerenderPaths
           if (prerenderPaths) {
             const ogKey = opts.key || 'og'
@@ -275,7 +281,10 @@ export function getOgImagePath(_pagePath: string, _options?: Partial<OgImageOpti
   const baseURL = runtimeConfig.app.baseURL
   const { defaults, security } = useOgImageRuntimeConfig()
   const extension = _options?.extension || defaults?.extension || 'png'
-  const isStatic = import.meta.prerender
+  // Force dynamic+signed URLs even during prerender when strict+secret are set.
+  // Otherwise /_og/s/ URLs baked into HTML are unsigned and 403 at runtime for
+  // setups where pages are prerendered but OG images are served dynamically.
+  const isStatic = import.meta.prerender && !(security?.secret && security?.strict)
   const options: Record<string, any> = { ..._options, _path: _pagePath }
   // Include the component template hash so that template changes produce different URLs,
   // busting CDN/build caches (Vercel, social platform crawlers like Twitter/Facebook, etc.)

src/runtime/server/util/eventHandlers.ts

@@ -20,23 +20,47 @@ export async function imageEventHandler(e: H3Event) {
   const { isDevToolsContextRequest, extension, renderer } = ctx
   const { debug, baseCacheKey, security } = useOgImageRuntimeConfig()
 
-  // Origin restriction: block runtime requests from unknown hosts
+  // Origin restriction: block runtime requests from unknown hosts.
+  // Loopback requests (localhost, 127.0.0.1, ::1) are allowed only when URL
+  // signing is active, so production builds running locally for e2e/CI don't
+  // need to disable the check entirely. Without a secret we cannot trust the
+  // Host / X-Forwarded-Host headers (user-controlled), so the allowlist must
+  // be enforced. With a secret, HMAC verification is what actually protects
+  // these requests; the host check is just an extra layer.
   if (!import.meta.prerender && !import.meta.dev && security?.restrictRuntimeImagesToOrigin) {
-    const siteHost = new URL(getSiteConfig(e).url).host
-    const allowedHosts = [siteHost, ...security.restrictRuntimeImagesToOrigin.map((o) => {
+    const requestHost = getRequestHost(e, { xForwardedHost: true })
+    // Parse the hostname via URL so bracketed IPv6 hosts like `[::1]:3000`
+    // are handled correctly (split(':') would yield `[` as the first segment).
+    let requestHostname: string | undefined
+    if (requestHost) {
       try {
-        return new URL(o).host
+        requestHostname = new URL(`http://${requestHost}`).hostname
       }
       catch {
-        return o
+        requestHostname = undefined
+      }
+    }
+    const isLoopback = !!security.secret && (
+      requestHostname === 'localhost'
+      || requestHostname === '127.0.0.1'
+      || requestHostname === '::1'
+    )
+    if (!isLoopback) {
+      const siteHost = new URL(getSiteConfig(e).url).host
+      const allowedHosts = [siteHost, ...security.restrictRuntimeImagesToOrigin.map((o) => {
+        try {
+          return new URL(o).host
+        }
+        catch {
+          return o
+        }
+      })]
+      if (!requestHost || !allowedHosts.includes(requestHost)) {
+        return createError({
+          statusCode: 403,
+          statusMessage: '[Nuxt OG Image] Host not allowed.',
+        })
       }
-    })]
-    const requestHost = getRequestHost(e, { xForwardedHost: true })
-    if (!requestHost || !allowedHosts.includes(requestHost)) {
-      return createError({
-        statusCode: 403,
-        statusMessage: '[Nuxt OG Image] Host not allowed.',
-      })
     }
   }
   // debug - allow in dev mode OR when debug is enabled in config

src/runtime/server/utils.ts

@@ -14,7 +14,10 @@ export function getOgImagePath(_pagePath: string, _options?: Partial<OgImageOpti
   const baseURL = useRuntimeConfig().app.baseURL
   const { defaults, security } = useOgImageRuntimeConfig()
   const extension = _options?.extension || defaults.extension
-  const isStatic = import.meta.prerender
+  // Force dynamic+signed URLs even during prerender when strict+secret are set.
+  // Otherwise /_og/s/ URLs baked into HTML are unsigned and 403 at runtime for
+  // setups where pages are prerendered but OG images are served dynamically.
+  const isStatic = import.meta.prerender && !(security?.secret && security?.strict)
   const options: Record<string, any> = { ..._options, _path: _pagePath }
   // Include the component template hash so that template changes produce different URLs,
   // busting CDN/build caches (Vercel, social platform crawlers like Twitter/Facebook, etc.)

test/unit/urlEncoding.test.ts

@@ -308,6 +308,50 @@ describe('urlEncoding', () => {
       }, 'png', true, defaults)
       expect(result.url).toBe('/_og/s/c_Test,title_Hello.png')
     })
+
+    // These tests lock in the contract that callers rely on when strict+secret
+    // are enabled. In that mode, getOgImagePath() passes isStatic=false even
+    // during prerender so the URLs baked into HTML are signed and dynamic, and
+    // pass runtime signature verification when served by the /_og/d/** handler.
+    describe('strict+secret contract', () => {
+      const SECRET = 'test-secret-key'
+
+      it('isStatic=false + secret produces signed dynamic URL', () => {
+        const result = buildOgImageUrl({ width: 1200 }, 'png', false, undefined, SECRET)
+        expect(result.url).toMatch(/^\/_og\/d\/w_1200,s_[\w-]+\.png$/)
+        expect(result.hash).toBeUndefined()
+      })
+
+      it('isStatic=true + secret produces UNSIGNED static URL (existing behavior)', () => {
+        // Static/prerendered URLs are served directly from disk and bypass the
+        // route handler, so they don't carry signatures. Preserved as-is.
+        const result = buildOgImageUrl({ width: 1200 }, 'png', true, undefined, SECRET)
+        expect(result.url).toBe('/_og/s/w_1200.png')
+        expect(result.url).not.toMatch(/,s_/)
+      })
+
+      it('long URLs + isStatic=false + secret use signed dynamic, NOT hash mode', () => {
+        // This is the core of Fix B: when strict+secret decouples isStatic from
+        // prerender, long URLs must stay in the signed dynamic path instead of
+        // hash mode (hash mode only works for URLs served from disk).
+        const longTitle = 'A'.repeat(250)
+        const result = buildOgImageUrl({ props: { title: longTitle } }, 'png', false, undefined, SECRET)
+        expect(result.url).toMatch(/^\/_og\/d\//)
+        expect(result.url).toMatch(/,s_[\w-]+\.png$/)
+        expect(result.url).not.toMatch(/\/o_[a-z0-9]+\./) // no hash-mode fallback
+        expect(result.hash).toBeUndefined()
+      })
+
+      it('signature changes when options change', () => {
+        const a = buildOgImageUrl({ width: 1200 }, 'png', false, undefined, SECRET)
+        const b = buildOgImageUrl({ width: 1201 }, 'png', false, undefined, SECRET)
+        const sigA = a.url.match(/,s_([\w-]+)\.png$/)?.[1]
+        const sigB = b.url.match(/,s_([\w-]+)\.png$/)?.[1]
+        expect(sigA).toBeDefined()
+        expect(sigB).toBeDefined()
+        expect(sigA).not.toBe(sigB)
+      })
+    })
   })
 
   describe('parseOgImageUrl', () => {