feat: add geocode proxy with CSRF protection for Google Maps billing optimization

docs/content/scripts/google-maps.md

@@ -53,16 +53,42 @@
 
 Showing an interactive JS map requires the Maps JavaScript API, which is a paid service. If a user interacts with the map, the following costs will be incurred:
 - $7 per 1000 loads for the Maps JavaScript API (default for using Google Maps)
-- $2 per 1000 loads for the Static Maps API - Only used when you don't provide a `placeholder` slot.
-- $5 per 1000 loads for the Geocoding API - Only used when you don't provide a `google.maps.LatLng` object instead of a query string for the `center` prop
+- $2 per 1000 loads for the Static Maps API - Only used when you don't provide a `placeholder` slot. **Can be cached** with `googleStaticMapsProxy`.
+- $5 per 1000 loads for the Geocoding API - Only used when you don't provide a `google.maps.LatLng` object instead of a query string for the `center` prop. **Can be cached** with `googleGeocodeProxy`.
 
 However, if the user never engages with the map, only the Static Maps API usage ($2 per 1000 loads) will be charged, assuming you're using it.
 
-Billing will be optimized in a [future update](https://github.com/nuxt/scripts/issues/83).
-
 You should consider using the [Iframe Embed](https://developers.google.com/maps/documentation/embed/get-started) instead if you want to avoid these costs
 and are okay with a less interactive map.
 
+#### Cost Optimization Proxies
+
+Enable server-side proxies to cache API responses, hide your API key from clients, and reduce billing:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  scripts: {
+    // Proxy and cache static map placeholder images (default: 1 hour)
+    googleStaticMapsProxy: {
+      enabled: true,
+      cacheMaxAge: 3600,
+    },
+    // Proxy and cache geocoding lookups for string-based centers (default: 24 hours)
+    googleGeocodeProxy: {
+      enabled: true,
+      cacheMaxAge: 86400,
+    },
+  },
+})
+```
+
+| Proxy | API Saved | Cache Default | What It Does |
+|-------|-----------|---------------|--------------|
+| `googleStaticMapsProxy` | Static Maps ($2/1k) | 1 hour | Caches placeholder images, hides API key |
+| `googleGeocodeProxy` | Places ($5/1k) | 24 hours | Caches place name → coordinate lookups |
+
+Both proxies validate the request referer to prevent external abuse and inject the API key server-side so it's never exposed to the client.
+
 ### Demo
 
 ::code-group

src/module.ts

@@ -272,6 +272,23 @@ export interface ModuleOptions {
      */
     cacheMaxAge?: number
   }
+  /**
+   * Google Geocode proxy configuration.
+   * Proxies Places API geocoding through your server with aggressive caching
+   * to reduce API costs for place name to coordinate resolution.
+   */
+  googleGeocodeProxy?: {
+    /**
+     * Enable geocode proxying through your own origin.
+     * @default false
+     */
+    enabled?: boolean
+    /**
+     * Cache duration for geocode results in seconds.
+     * @default 86400 (24 hours)
+     */
+    cacheMaxAge?: number
+  }
   /**
    * Whether the module is enabled.
    *
@@ -314,6 +331,10 @@ export default defineNuxtModule<ModuleOptions>({
       enabled: false,
       cacheMaxAge: 3600,
     },
+    googleGeocodeProxy: {
+      enabled: false,
+      cacheMaxAge: 86400,
+    },
     enabled: true,
     debug: false,
   },
@@ -335,11 +356,15 @@ export default defineNuxtModule<ModuleOptions>({
     if (unheadVersion?.startsWith('1')) {
       logger.error(`Nuxt Scripts requires Unhead >= 2, you are using v${unheadVersion}. Please run \`nuxi upgrade --clean\` to upgrade...`)
     }
+    const mapsApiKey = (nuxt.options.runtimeConfig.public.scripts as any)?.googleMaps?.apiKey
     nuxt.options.runtimeConfig['nuxt-scripts'] = {
       version: version!,
       // Private proxy config with API key (server-side only)
       googleStaticMapsProxy: config.googleStaticMapsProxy?.enabled
-        ? { apiKey: (nuxt.options.runtimeConfig.public.scripts as any)?.googleMaps?.apiKey }
+        ? { apiKey: mapsApiKey }
+        : undefined,
+      googleGeocodeProxy: config.googleGeocodeProxy?.enabled
+        ? { apiKey: mapsApiKey }
         : undefined,
     } as any
     nuxt.options.runtimeConfig.public['nuxt-scripts'] = {
@@ -350,6 +375,9 @@ export default defineNuxtModule<ModuleOptions>({
       googleStaticMapsProxy: config.googleStaticMapsProxy?.enabled
         ? { enabled: true, cacheMaxAge: config.googleStaticMapsProxy.cacheMaxAge }
         : undefined,
+      googleGeocodeProxy: config.googleGeocodeProxy?.enabled
+        ? { enabled: true, cacheMaxAge: config.googleGeocodeProxy.cacheMaxAge }
+        : undefined,
     } as any
 
     // Merge registry config with existing runtimeConfig.public.scripts for proper env var resolution
@@ -703,6 +731,14 @@ export default defineNuxtModule<ModuleOptions>({
       })
     }
 
+    // Add Google Geocode proxy handler if enabled
+    if (config.googleGeocodeProxy?.enabled) {
+      addServerHandler({
+        route: '/_scripts/google-maps-geocode-proxy',
+        handler: await resolvePath('./runtime/server/google-maps-geocode-proxy'),
+      })
+    }
+
     // Add Gravatar proxy handler when registry.gravatar is enabled
     if (config.registry?.gravatar) {
       const gravatarConfig = typeof config.registry.gravatar === 'object' && !Array.isArray(config.registry.gravatar)

src/runtime/components/GoogleMaps/ScriptGoogleMaps.vue

@@ -7,7 +7,8 @@
 import { useScriptGoogleMaps } from '#nuxt-scripts/registry/google-maps'
 import { scriptRuntimeConfig } from '#nuxt-scripts/utils'
 import { defu } from 'defu'
+import { $fetch } from 'ofetch'
 import { tryUseNuxtApp, useHead, useRuntimeConfig } from 'nuxt/app'
 import { hash } from 'ohash'
 import { withQuery } from 'ufo'
 import { computed, onBeforeUnmount, onMounted, provide, ref, shallowRef, toRaw, watch } from 'vue'
@@ -132,6 +133,7 @@
 const apiKey = props.apiKey || scriptRuntimeConfig('googleMaps')?.apiKey
 const runtimeConfig = useRuntimeConfig()
 const proxyConfig = (runtimeConfig.public['nuxt-scripts'] as any)?.googleStaticMapsProxy
+const geocodeProxyConfig = (runtimeConfig.public['nuxt-scripts'] as any)?.googleGeocodeProxy
 
 // Color mode support - try to auto-detect from @nuxtjs/color-mode
 const nuxtApp = tryUseNuxtApp()
@@ -249,7 +251,18 @@
   if (queryToLatLngCache.has(query)) {
     return Promise.resolve(queryToLatLngCache.get(query))
   }
-  // only if the query is a string we need to do a lookup
+  // Use server-side geocode proxy when enabled to save Places API costs
+  if (geocodeProxyConfig?.enabled) {
+    const data = await $fetch<{ lat: number, lng: number }>('/_scripts/google-maps-geocode-proxy', {
+      query: { input: query },
+    }).catch(() => null)
+    if (data) {
+      const latLng = new mapsApi.value!.LatLng(data.lat, data.lng)
+      queryToLatLngCache.set(query, latLng)
+      return latLng
+    }
+  }
+  // Fallback to client-side Places API
   // eslint-disable-next-line no-async-promise-executor
   return new Promise<google.maps.LatLng>(async (resolve, reject) => {
     if (!mapsApi.value) {

src/runtime/server/google-maps-geocode-proxy.ts

@@ -0,0 +1,120 @@
+import { useRuntimeConfig } from '#imports'
+import { createError, defineEventHandler, getHeader, getQuery, getRequestIP, setHeader } from 'h3'
+import { $fetch } from 'ofetch'
+import { withQuery } from 'ufo'
+
+const MAX_INPUT_LENGTH = 200
+const RATE_LIMIT_WINDOW_MS = 60_000
+const RATE_LIMIT_MAX = 30
+
+const requestCounts = new Map<string, { count: number, resetAt: number }>()
+
+function checkRateLimit(ip: string): boolean {
+  const now = Date.now()
+  const entry = requestCounts.get(ip)
+  if (!entry || now > entry.resetAt) {
+    requestCounts.set(ip, { count: 1, resetAt: now + RATE_LIMIT_WINDOW_MS })
+    return true
+  }
+  entry.count++
+  return entry.count <= RATE_LIMIT_MAX
+}
+
+export default defineEventHandler(async (event) => {
+  const runtimeConfig = useRuntimeConfig()
+  const publicConfig = (runtimeConfig.public['nuxt-scripts'] as any)?.googleGeocodeProxy
+  const privateConfig = (runtimeConfig['nuxt-scripts'] as any)?.googleGeocodeProxy
+
+  if (!publicConfig?.enabled) {
+    throw createError({
+      statusCode: 404,
+      statusMessage: 'Google Geocode proxy is not enabled',
+    })
+  }
+
+  const apiKey = privateConfig?.apiKey
+  if (!apiKey) {
+    throw createError({
+      statusCode: 500,
+      statusMessage: 'Google Maps API key not configured for geocode proxy',
+    })
+  }
+
+  // Rate limit by IP
+  const ip = getRequestIP(event, { xForwardedFor: true }) || 'unknown'
+  if (!checkRateLimit(ip)) {
+    throw createError({
+      statusCode: 429,
+      statusMessage: 'Too many geocode requests',
+    })
+  }
+
+  // Validate referer to prevent external abuse
+  const referer = getHeader(event, 'referer')
+  const host = getHeader(event, 'host')
+  if (referer && host) {
+    let refererHost: string | undefined
+    try {
+      refererHost = new URL(referer).host
+    }
+    catch {}
+    if (refererHost && refererHost !== host) {
+      throw createError({
+        statusCode: 403,
+        statusMessage: 'Invalid referer',
+      })
+    }
+  }
+
+  const query = getQuery(event)
+  const input = query.input as string
+
+  if (!input) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: 'Missing "input" query parameter',
+    })
+  }
+
+  if (input.length > MAX_INPUT_LENGTH) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: `Input too long (max ${MAX_INPUT_LENGTH} characters)`,
+    })
+  }
+
+  const googleUrl = withQuery('https://maps.googleapis.com/maps/api/place/findplacefromtext/json', {
+    input,
+    inputtype: 'textquery',
+    fields: 'name,geometry',
+    key: apiKey,
+  })
+
+  const data = await $fetch<{ candidates: Array<{ geometry: { location: { lat: number, lng: number } }, name: string }>, status: string }>(googleUrl, {
+    headers: {
+      'User-Agent': 'Nuxt Scripts Google Geocode Proxy',
+    },
+  }).catch((error: any) => {
+    throw createError({
+      statusCode: error.statusCode || 500,
+      statusMessage: error.statusMessage || 'Failed to geocode query',
+    })
+  })
+
+  if (data.status !== 'OK' || !data.candidates?.[0]?.geometry?.location) {
+    throw createError({
+      statusCode: 404,
+      statusMessage: `No location found for "${input}"`,
+    })
+  }
+
+  const location = data.candidates[0].geometry.location
+
+  // Cache aggressively - place names rarely change coordinates
+  const cacheMaxAge = publicConfig.cacheMaxAge || 86400
+  setHeader(event, 'Content-Type', 'application/json')
+  setHeader(event, 'Cache-Control', `public, max-age=${cacheMaxAge}, s-maxage=${cacheMaxAge}`)
+  setHeader(event, 'Vary', 'Accept-Encoding')
+
+  return { lat: location.lat, lng: location.lng, name: data.candidates[0].name }
+})

src/runtime/server/google-static-maps-proxy.ts

@@ -1,8 +1,30 @@
 import { useRuntimeConfig } from '#imports'
-import { createError, defineEventHandler, getHeader, getQuery, setHeader } from 'h3'
+import { createError, defineEventHandler, getHeader, getQuery, getRequestIP, setHeader } from 'h3'
 import { $fetch } from 'ofetch'
 import { withQuery } from 'ufo'
 
+const RATE_LIMIT_WINDOW_MS = 60_000
+const RATE_LIMIT_MAX = 60
+
+const ALLOWED_PARAMS = new Set([
+  'center', 'zoom', 'size', 'scale', 'format', 'maptype',
+  'language', 'region', 'markers', 'path', 'visible',
+  'style', 'map_id', 'signature',
+])
+
+const requestCounts = new Map<string, { count: number, resetAt: number }>()
+
+function checkRateLimit(ip: string): boolean {
+  const now = Date.now()
+  const entry = requestCounts.get(ip)
+  if (!entry || now > entry.resetAt) {
+    requestCounts.set(ip, { count: 1, resetAt: now + RATE_LIMIT_WINDOW_MS })
+    return true
+  }
+  entry.count++
+  return entry.count <= RATE_LIMIT_MAX
+}
+
 export default defineEventHandler(async (event) => {
   const runtimeConfig = useRuntimeConfig()
   const publicConfig = (runtimeConfig.public['nuxt-scripts'] as any)?.googleStaticMapsProxy
@@ -24,12 +46,25 @@
     })
   }
 
+  // Rate limit by IP
+  const ip = getRequestIP(event, { xForwardedFor: true }) || 'unknown'
+  if (!checkRateLimit(ip)) {
+    throw createError({
+      statusCode: 429,
+      statusMessage: 'Too many static map requests',
+    })
+  }
+
   // Validate referer to prevent external abuse
   const referer = getHeader(event, 'referer')
   const host = getHeader(event, 'host')
   if (referer && host) {
-    const refererUrl = new URL(referer).host
-    if (refererUrl !== host) {
+    let refererHost: string | undefined
+    try {
+      refererHost = new URL(referer).host
+    }
+    catch {}
+    if (refererHost && refererHost !== host) {
       throw createError({
         statusCode: 403,
         statusMessage: 'Invalid referer',
@@ -39,8 +74,12 @@
 
   const query = getQuery(event)
 
-  // Remove any client-provided key and use server-side key
-  const { key: _clientKey, ...safeQuery } = query
+  // Only allow known Static Maps API parameters
+  const safeQuery: Record<string, unknown> = {}
+  for (const [k, v] of Object.entries(query)) {
+    if (ALLOWED_PARAMS.has(k))
+      safeQuery[k] = v
+  }
 
   const googleMapsUrl = withQuery('https://maps.googleapis.com/maps/api/staticmap', {
     ...safeQuery,