@nuxt/scripts 1.0.0-rc.1 → 1.0.0-rc.11

package/dist/runtime/server/utils/proxy-url.js

@@ -0,0 +1,21 @@
+import { buildSignedProxyUrl } from "./sign.js";
+export function buildProxyUrl(path, query, secret) {
+  if (secret)
+    return buildSignedProxyUrl(path, query, secret);
+  const parts = [];
+  for (const [key, value] of Object.entries(query)) {
+    if (value === void 0 || value === null)
+      continue;
+    const encodedKey = encodeURIComponent(key);
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        if (item === void 0 || item === null)
+          continue;
+        parts.push(`${encodedKey}=${encodeURIComponent(String(item))}`);
+      }
+    } else {
+      parts.push(`${encodedKey}=${encodeURIComponent(String(value))}`);
+    }
+  }
+  return parts.length ? `${path}?${parts.join("&")}` : path;
+}

package/dist/runtime/server/utils/sign-constants.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Signing constants shared between server (HMAC) and client (page-token) code.
+ *
+ * Kept in a crypto-free module so client bundles can import the param names
+ * without pulling in `node:crypto`.
+ */
+/** Query param name for the HMAC signature. */
+export declare const SIG_PARAM = "sig";
+/** Length of the hex signature (16 chars = 64 bits). */
+export declare const SIG_LENGTH = 16;
+/** Query param name for the page token. */
+export declare const PAGE_TOKEN_PARAM = "_pt";
+/** Query param name for the page token timestamp. */
+export declare const PAGE_TOKEN_TS_PARAM = "_ts";
+/** Default max age for page tokens in seconds (1 hour). */
+export declare const PAGE_TOKEN_MAX_AGE = 3600;

package/dist/runtime/server/utils/sign-constants.js

@@ -0,0 +1,5 @@
+export const SIG_PARAM = "sig";
+export const SIG_LENGTH = 16;
+export const PAGE_TOKEN_PARAM = "_pt";
+export const PAGE_TOKEN_TS_PARAM = "_ts";
+export const PAGE_TOKEN_MAX_AGE = 3600;

package/dist/runtime/server/utils/sign.d.ts

@@ -0,0 +1,101 @@
+/**
+ * HMAC URL signing for proxy endpoints.
+ *
+ * ## Why
+ *
+ * Proxy endpoints like `/_scripts/proxy/google-static-maps` inject a server-side
+ * API key and forward requests to third-party services. Without signing, anyone
+ * can call these endpoints with arbitrary parameters and burn the site owner's
+ * API quota. Signing ensures only URLs generated server-side (during SSR/prerender
+ * or via the `/_scripts/sign` endpoint) are accepted.
+ *
+ * ## How
+ *
+ * 1. The module stores a deterministic secret in `runtimeConfig.nuxt-scripts.proxySecret`
+ *    (env: `NUXT_SCRIPTS_PROXY_SECRET`).
+ * 2. URLs are canonicalized (sort query keys, strip `sig`) and signed with HMAC-SHA256.
+ * 3. The first 16 hex chars (64 bits) of the digest is appended as `?sig=<hex>`.
+ * 4. Endpoints wrapped with `withSigning()` verify the sig against the current request.
+ *
+ * A 64-bit signature is enough to defeat brute force for this threat model
+ * (a billion guesses gives a ~5% hit rate at 2^64). Longer signatures bloat
+ * prerendered HTML for no practical gain.
+ */
+import type { H3Event } from 'h3';
+import { PAGE_TOKEN_MAX_AGE, PAGE_TOKEN_PARAM, PAGE_TOKEN_TS_PARAM, SIG_LENGTH, SIG_PARAM } from './sign-constants.js';
+export { PAGE_TOKEN_MAX_AGE, PAGE_TOKEN_PARAM, PAGE_TOKEN_TS_PARAM, SIG_LENGTH, SIG_PARAM };
+/**
+ * Canonicalize a query object into a deterministic string suitable for HMAC input.
+ *
+ * Rules:
+ * - The `sig` param is stripped (it can't sign itself).
+ * - `undefined` and `null` values are skipped (mirrors `ufo.withQuery`).
+ * - Keys are sorted alphabetically so order-independent reconstruction works.
+ * - Arrays expand to repeated keys (e.g. `markers=a&markers=b`), matching how
+ *   `ufo.withQuery` serializes array-valued params.
+ * - Objects are JSON-stringified (rare, but consistent with `ufo.withQuery`).
+ * - Encoding uses `encodeURIComponent` for both keys and values so the canonical
+ *   form matches what shows up on the wire.
+ *
+ * The resulting string is stable across server/client and different JS runtimes
+ * because it does not depend on `URLSearchParams` insertion order.
+ */
+export declare function canonicalizeQuery(query: Record<string, unknown>): string;
+/**
+ * Sign a path + query using HMAC-SHA256 and return the 16-char hex digest.
+ *
+ * The HMAC input is `${path}?${canonicalQuery}` so that the same query signed
+ * against a different endpoint yields a different signature (prevents cross-
+ * endpoint signature reuse).
+ *
+ * `path` should be the URL path without query string (e.g. `/_scripts/proxy/google-static-maps`).
+ * Callers should not include origin / host since the signing contract is path-relative.
+ */
+export declare function signProxyUrl(path: string, query: Record<string, unknown>, secret: string): string;
+/**
+ * Build a fully-formed signed URL (path + query + sig).
+ *
+ * This is the primary helper for code paths that need to emit a proxy URL
+ * (SSR components, server-side URL rewriters like instagram-embed).
+ */
+export declare function buildSignedProxyUrl(path: string, query: Record<string, unknown>, secret: string): string;
+/**
+ * Generate a page token that authorizes client-side proxy requests.
+ *
+ * Embedded in the SSR payload so the browser can attach it to reactive proxy
+ * URL updates without needing a `/sign` round-trip. The token is scoped to
+ * a timestamp and expires after `PAGE_TOKEN_MAX_AGE` seconds.
+ *
+ * Construction: first 16 hex chars of `HMAC(secret, "proxy-access:<timestamp>")`.
+ */
+export declare function generateProxyToken(secret: string, timestamp: number): string;
+/**
+ * Verify a page token against the current time.
+ *
+ * Returns `true` if the token matches the HMAC for the given timestamp AND
+ * the timestamp is within `maxAge` seconds of `now`.
+ */
+export declare function verifyProxyToken(token: string, timestamp: number, secret: string, maxAge?: number, now?: number): boolean;
+/**
+ * Verify a request against either a URL signature or a page token.
+ *
+ * Two verification modes, checked in order:
+ *
+ * 1. **URL signature** (`sig` param): the exact URL was signed server-side
+ *    during SSR/prerender. Locked to the specific path + query params.
+ *
+ * 2. **Page token** (`_pt` + `_ts` params): the client received a short-lived
+ *    token during SSR and is making a reactive proxy request with new params.
+ *    Valid for any params on the target path, but expires after `maxAge`.
+ *
+ * Returns `false` if neither mode validates.
+ */
+export declare function verifyProxyRequest(event: H3Event, secret: string, maxAge?: number): boolean;
+/**
+ * Constant-time string comparison.
+ *
+ * Both inputs are expected to be equal-length hex strings. The loop runs over
+ * the longer length so an early-exit on length mismatch doesn't leak the
+ * expected length (though both are fixed at `SIG_LENGTH` in practice).
+ */
+export declare function constantTimeEqual(a: string, b: string): boolean;

package/dist/runtime/server/utils/sign.js

@@ -0,0 +1,91 @@
+import { createHmac } from "node:crypto";
+import { getQuery } from "h3";
+import {
+  PAGE_TOKEN_MAX_AGE,
+  PAGE_TOKEN_PARAM,
+  PAGE_TOKEN_TS_PARAM,
+  SIG_LENGTH,
+  SIG_PARAM
+} from "./sign-constants.js";
+export { PAGE_TOKEN_MAX_AGE, PAGE_TOKEN_PARAM, PAGE_TOKEN_TS_PARAM, SIG_LENGTH, SIG_PARAM };
+export function canonicalizeQuery(query) {
+  const keys = Object.keys(query).filter((k) => k !== SIG_PARAM && query[k] !== void 0 && query[k] !== null).sort();
+  const parts = [];
+  for (const key of keys) {
+    const value = query[key];
+    const encodedKey = encodeURIComponent(key);
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        if (item === void 0 || item === null)
+          continue;
+        parts.push(`${encodedKey}=${encodeURIComponent(serializeValue(item))}`);
+      }
+    } else {
+      parts.push(`${encodedKey}=${encodeURIComponent(serializeValue(value))}`);
+    }
+  }
+  return parts.join("&");
+}
+function serializeValue(value) {
+  if (typeof value === "string")
+    return value;
+  if (typeof value === "object")
+    return JSON.stringify(value);
+  return String(value);
+}
+export function signProxyUrl(path, query, secret) {
+  const canonical = canonicalizeQuery(query);
+  const input = canonical ? `${path}?${canonical}` : path;
+  return createHmac("sha256", secret).update(input).digest("hex").slice(0, SIG_LENGTH);
+}
+export function buildSignedProxyUrl(path, query, secret) {
+  const sig = signProxyUrl(path, query, secret);
+  const canonical = canonicalizeQuery(query);
+  const queryString = canonical ? `${canonical}&${SIG_PARAM}=${sig}` : `${SIG_PARAM}=${sig}`;
+  return `${path}?${queryString}`;
+}
+export function generateProxyToken(secret, timestamp) {
+  return createHmac("sha256", secret).update(`proxy-access:${timestamp}`).digest("hex").slice(0, SIG_LENGTH);
+}
+export function verifyProxyToken(token, timestamp, secret, maxAge = PAGE_TOKEN_MAX_AGE, now = Math.floor(Date.now() / 1e3)) {
+  if (!token || !secret || typeof timestamp !== "number")
+    return false;
+  if (token.length !== SIG_LENGTH)
+    return false;
+  const age = now - timestamp;
+  if (age > maxAge || age < -60)
+    return false;
+  const expected = generateProxyToken(secret, timestamp);
+  return constantTimeEqual(expected, token);
+}
+export function verifyProxyRequest(event, secret, maxAge) {
+  if (!secret)
+    return false;
+  const query = getQuery(event);
+  const rawSig = query[SIG_PARAM];
+  const sig = Array.isArray(rawSig) ? rawSig[0] : rawSig;
+  if (typeof sig === "string" && sig.length === SIG_LENGTH) {
+    const path = (event.path || "").split("?")[0] || "";
+    const expected = signProxyUrl(path, query, secret);
+    if (constantTimeEqual(expected, sig))
+      return true;
+  }
+  const rawToken = query[PAGE_TOKEN_PARAM];
+  const rawTs = query[PAGE_TOKEN_TS_PARAM];
+  const token = Array.isArray(rawToken) ? rawToken[0] : rawToken;
+  const ts = Array.isArray(rawTs) ? rawTs[0] : rawTs;
+  if (typeof token === "string" && ts !== void 0) {
+    const timestamp = Number(ts);
+    if (!Number.isNaN(timestamp))
+      return verifyProxyToken(token, timestamp, secret, maxAge);
+  }
+  return false;
+}
+export function constantTimeEqual(a, b) {
+  if (a.length !== b.length)
+    return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++)
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}

package/dist/runtime/server/utils/withSigning.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Middleware wrapper that enforces HMAC signature verification on a proxy handler.
+ *
+ * Usage:
+ * ```ts
+ * export default withSigning(defineEventHandler(async (event) => {
+ *   // ... handler logic
+ * }))
+ * ```
+ *
+ * Behavior:
+ * - Reads `runtimeConfig.nuxt-scripts.proxySecret` (server-only).
+ * - If no secret is configured: passes through (signing not yet enabled).
+ *   This allows shipping handler wiring before components emit signed URLs.
+ *   Once `NUXT_SCRIPTS_PROXY_SECRET` is set, verification is enforced.
+ * - If a secret IS configured and the request's signature is invalid: 403.
+ * - Otherwise, delegates to the wrapped handler.
+ *
+ * The outer wrapper runs before any handler logic, so unauthorized requests
+ * never reach the upstream fetch and cannot consume API quota.
+ */
+import type { EventHandler, EventHandlerRequest, EventHandlerResponse } from 'h3';
+export declare function withSigning<Req extends EventHandlerRequest = EventHandlerRequest, Res extends EventHandlerResponse = EventHandlerResponse>(handler: EventHandler<Req, Res>): EventHandler<Req, Res>;

package/dist/runtime/server/utils/withSigning.js

@@ -0,0 +1,19 @@
+import { createError, defineEventHandler } from "h3";
+import { useRuntimeConfig } from "nitropack/runtime";
+import { verifyProxyRequest } from "./sign.js";
+export function withSigning(handler) {
+  return defineEventHandler(async (event) => {
+    const runtimeConfig = useRuntimeConfig(event);
+    const scriptsConfig = runtimeConfig["nuxt-scripts"];
+    const secret = scriptsConfig?.proxySecret;
+    if (!secret)
+      return handler(event);
+    if (!verifyProxyRequest(event, secret, scriptsConfig?.pageTokenMaxAge)) {
+      throw createError({
+        statusCode: 403,
+        statusMessage: "Invalid signature"
+      });
+    }
+    return handler(event);
+  });
+}

package/dist/runtime/server/x-embed-image.d.ts

@@ -1,2 +1,2 @@
-declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<any>>;
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<Buffer<ArrayBufferLike>>>;
 export default _default;

package/dist/runtime/server/x-embed.js

@@ -1,7 +1,20 @@
 import { createError, defineEventHandler, getQuery, setHeader } from "h3";
-import { $fetch } from "ofetch";
+import { useRuntimeConfig } from "nitropack/runtime";
+import { createCachedJsonFetch } from "./utils/cached-upstream.js";
+import { rewriteTweetImages } from "./utils/embed-rewriters.js";
+import { withSigning } from "./utils/withSigning.js";
 const TWEET_ID_RE = /^\d+$/;
-export default defineEventHandler(async (event) => {
+const EMBED_X_SUFFIX_RE = /\/embed\/x$/;
+const TWEET_ID_FROM_URL_RE = /[?&]id=(\d+)/;
+const cachedTweetFetch = createCachedJsonFetch(
+  "nuxt-scripts-x-tweet",
+  600,
+  (url) => {
+    const match = url.match(TWEET_ID_FROM_URL_RE);
+    return match?.[1] || url;
+  }
+);
+export default withSigning(defineEventHandler(async (event) => {
   const query = getQuery(event);
   const tweetId = query.id;
   if (!tweetId || !TWEET_ID_RE.test(tweetId)) {
@@ -12,7 +25,7 @@ export default defineEventHandler(async (event) => {
   }
   const randomToken = Array.from(Array.from({ length: 11 }), () => (Math.random() * 36).toString(36)[2]).join("");
   const params = new URLSearchParams({ id: tweetId, token: randomToken });
-  const tweetData = await $fetch(
+  const tweetRaw = await cachedTweetFetch(
     `https://cdn.syndication.twimg.com/tweet-result?${params.toString()}`,
     {
       headers: {
@@ -26,7 +39,13 @@ export default defineEventHandler(async (event) => {
       statusMessage: error.statusMessage || "Failed to fetch tweet"
     });
   });
+  const tweetData = structuredClone(tweetRaw);
+  const handlerPath = event.path?.split("?")[0] || "";
+  const prefix = handlerPath.replace(EMBED_X_SUFFIX_RE, "") || "/_scripts";
+  const imagePath = `${prefix}/embed/x-image`;
+  const secret = useRuntimeConfig(event)["nuxt-scripts"]?.proxySecret;
+  rewriteTweetImages(tweetData, imagePath, secret);
   setHeader(event, "Content-Type", "application/json");
   setHeader(event, "Cache-Control", "public, max-age=600, s-maxage=600");
   return tweetData;
-});
+}));

package/dist/runtime/types.d.ts

@@ -41,13 +41,38 @@ import type { XEmbedInput } from './registry/x-embed.js';
 import type { XPixelInput } from './registry/x-pixel.js';
 import type { YouTubePlayerInput } from './registry/youtube-player.js';
 import type { ProxyPrivacyInput } from './server/utils/privacy.js';
+export type { Cluster, ClusterStats, MarkerClustererContext, MarkerClustererInstance, MarkerClustererOptions } from './components/GoogleMaps/types.js';
+export { MARKER_CLUSTERER_INJECTION_KEY } from './components/GoogleMaps/types.js';
 export type WarmupStrategy = false | 'preload' | 'preconnect' | 'dns-prefetch';
-export type UseScriptContext<T extends Record<symbol | string, any>> = VueScriptInstance<T> & {
+/**
+ * GCMv2 consent category value.
+ * @see https://developers.google.com/tag-platform/security/guides/consent
+ */
+export type ConsentCategoryValue = 'granted' | 'denied';
+/**
+ * Canonical GCMv2 consent state shape used by vendors that natively consume
+ * Consent Mode v2 (Google Analytics, Google Tag Manager, Bing UET).
+ */
+export interface ConsentState {
+    ad_storage?: ConsentCategoryValue;
+    ad_user_data?: ConsentCategoryValue;
+    ad_personalization?: ConsentCategoryValue;
+    analytics_storage?: ConsentCategoryValue;
+    functionality_storage?: ConsentCategoryValue;
+    personalization_storage?: ConsentCategoryValue;
+    security_storage?: ConsentCategoryValue;
+}
+export type UseScriptContext<T extends Record<symbol | string, any>, C = unknown> = VueScriptInstance<T> & {
     /**
      * Remove and reload the script. Useful for scripts that need to re-execute
      * after SPA navigation (e.g., DOM-scanning scripts like iubenda).
      */
     reload: () => Promise<T>;
+    /**
+     * Vendor-native consent controls attached by registry scripts.
+     * Shape depends on the vendor (GCMv2 update, binary grant/revoke, three-state, etc.).
+     */
+    consent?: C;
 };
 export type NuxtUseScriptOptions<T extends Record<symbol | string, any> = {}> = Omit<UseScriptOptions<T>, 'trigger'> & {
     /**
@@ -233,7 +258,7 @@ export type BuiltInRegistryScriptKey = 'bingUet' | 'blueskyEmbed' | 'carbonAds'
  * Includes both built-in and augmented keys.
  */
 export type RegistryScriptKey = Exclude<keyof ScriptRegistry, `${string}-npm`>;
-type RegistryConfigInput<T> = [T] extends [true] ? Record<string, never> : T;
+type RegistryConfigInput<T> = 0 extends 1 & T ? Record<string, any> : [T] extends [true] ? Record<string, never> : T;
 export type NuxtConfigScriptRegistryEntry<T> = true | false | 'mock' | (RegistryConfigInput<T> & {
     trigger?: NuxtUseScriptOptionsSerializable['trigger'] | false;
     proxy?: boolean;
@@ -241,9 +266,12 @@ export type NuxtConfigScriptRegistryEntry<T> = true | false | 'mock' | (Registry
     partytown?: boolean;
     privacy?: ProxyPrivacyInput;
 });
-export type NuxtConfigScriptRegistry<T extends keyof ScriptRegistry = keyof ScriptRegistry> = Partial<{
-    [key in T]: NuxtConfigScriptRegistryEntry<ScriptRegistry[key]>;
-}> & Record<string & {}, NuxtConfigScriptRegistryEntry<any>>;
+type _NuxtConfigScriptRegistryEntries = {
+    [K in keyof ScriptRegistry as K extends `${string}-npm` ? never : K]?: NuxtConfigScriptRegistryEntry<ScriptRegistry[K]>;
+};
+export interface NuxtConfigScriptRegistry extends _NuxtConfigScriptRegistryEntries {
+    [key: string]: any;
+}
 export type UseFunctionType<T, U> = T extends {
     use: infer V;
 } ? V extends (...args: any) => any ? ReturnType<V> : U : U;
@@ -263,6 +291,14 @@ export interface RegistryScriptServerHandler {
     route: string;
     handler: string;
     middleware?: boolean;
+    /**
+     * Whether this handler verifies HMAC signatures via `withSigning()`.
+     *
+     * When any enabled script registers a handler with `requiresSigning: true`,
+     * the module enforces that `NUXT_SCRIPTS_PROXY_SECRET` is set in production,
+     * and the `/_scripts/sign` endpoint will accept this route as a signable path.
+     */
+    requiresSigning?: boolean;
 }
 /**
  * Declares what optimization modes a script supports and what's active by default.
@@ -453,4 +489,3 @@ export interface ProxyConfig {
     /** AST-level SDK patches applied during URL rewriting. */
     sdkPatches?: SdkPatch[];
 }
-export {};

package/dist/runtime/types.js

@@ -0,0 +1 @@
+export { MARKER_CLUSTERER_INJECTION_KEY } from "./components/GoogleMaps/types.js";