@nuxt/scripts 1.0.0-beta.7 → 1.0.0-rc.10

package/dist/runtime/server/utils/instagram-embed.js

@@ -0,0 +1,153 @@
+import { buildProxyUrl } from "./proxy-url.js";
+export const RSRC_RE = /url\(\/rsrc\.php([^)]+)\)/g;
+export const AMP_RE = /&/g;
+export const SCONTENT_RE = /https:\/\/scontent[^"'\s),]+\.cdninstagram\.com[^"'\s),]+/g;
+export const STATIC_CDN_RE = /https:\/\/static\.cdninstagram\.com[^"'\s),]+/g;
+export const LOOKASIDE_RE = /https:\/\/lookaside\.instagram\.com[^"'\s),]+/g;
+export const INSTAGRAM_IMAGE_HOSTS = ["scontent.cdninstagram.com", "lookaside.instagram.com"];
+export const INSTAGRAM_ASSET_HOST = "static.cdninstagram.com";
+const CHARSET_RE = /@charset\s[^;]+;/gi;
+const IMPORT_RE = /@import\s[^;]+;/gi;
+const WHITESPACE_RE = /\s/;
+const AT_RULE_NAME_RE = /@([\w-]+)/;
+const MULTI_SPACE_RE = /\s+/g;
+export function proxyImageUrl(url, prefix = "/_scripts", secret) {
+  return buildProxyUrl(`${prefix}/embed/instagram-image`, { url: url.replace(AMP_RE, "&") }, secret);
+}
+export function proxyAssetUrl(url, prefix = "/_scripts", secret) {
+  return buildProxyUrl(`${prefix}/embed/instagram-asset`, { url: url.replace(AMP_RE, "&") }, secret);
+}
+export function rewriteUrl(url, prefix = "/_scripts", secret) {
+  try {
+    const parsed = new URL(url);
+    if (parsed.hostname === INSTAGRAM_ASSET_HOST)
+      return proxyAssetUrl(url, prefix, secret);
+    if (INSTAGRAM_IMAGE_HOSTS.some((h) => parsed.hostname === h || parsed.hostname.endsWith(`.cdninstagram.com`)))
+      return proxyImageUrl(url, prefix, secret);
+  } catch {
+  }
+  return url;
+}
+export function rewriteUrlsInText(text, prefix = "/_scripts", secret) {
+  return text.replace(SCONTENT_RE, (m) => proxyImageUrl(m, prefix, secret)).replace(STATIC_CDN_RE, (m) => proxyAssetUrl(m, prefix, secret)).replace(LOOKASIDE_RE, (m) => proxyImageUrl(m, prefix, secret));
+}
+export function scopeCss(css, scopeSelector) {
+  let result = css.replace(CHARSET_RE, "");
+  result = result.replace(IMPORT_RE, "");
+  return processRules(result, scopeSelector);
+}
+function processRules(css, scopeSelector) {
+  const output = [];
+  let i = 0;
+  while (i < css.length) {
+    while (i < css.length && WHITESPACE_RE.test(css[i])) i++;
+    if (i >= css.length)
+      break;
+    if (css[i] === "@") {
+      const atRule = extractAtRule(css, i);
+      if (atRule) {
+        const atName = atRule.content.match(AT_RULE_NAME_RE)?.[1]?.toLowerCase();
+        if (atName === "media" || atName === "supports" || atName === "layer") {
+          const braceStart = atRule.content.indexOf("{");
+          if (braceStart === -1) {
+            output.push(atRule.content);
+          } else {
+            const innerCss = atRule.content.slice(braceStart + 1, -1);
+            const scopedInner = processRules(innerCss, scopeSelector);
+            output.push(`${atRule.content.slice(0, braceStart + 1)}${scopedInner}}`);
+          }
+        } else if (atName === "keyframes" || atName === "-webkit-keyframes" || atName === "font-face") {
+          output.push(atRule.content);
+        }
+        i = atRule.end;
+        continue;
+      }
+    }
+    const bracePos = css.indexOf("{", i);
+    if (bracePos === -1)
+      break;
+    const selector = css.slice(i, bracePos).trim();
+    const block = extractBlock(css, bracePos);
+    if (!block)
+      break;
+    i = block.end;
+    if (!selector)
+      continue;
+    const selectors = splitTopLevel(selector, ",").map((s) => s.trim());
+    const filteredSelectors = selectors.filter((s) => {
+      const normalized = s.replace(MULTI_SPACE_RE, " ").trim().toLowerCase();
+      return normalized !== ":root" && normalized !== "html" && normalized !== "body" && !normalized.startsWith(":root ") && !normalized.startsWith("html ") && !normalized.startsWith("body ") && normalized !== "html, body";
+    });
+    if (filteredSelectors.length === 0)
+      continue;
+    const scopedSelectors = filteredSelectors.map((s) => `${scopeSelector} ${s}`);
+    output.push(`${scopedSelectors.join(", ")} ${block.content}`);
+  }
+  return output.join("\n");
+}
+function extractAtRule(css, start) {
+  const bracePos = css.indexOf("{", start);
+  const semiPos = css.indexOf(";", start);
+  if (semiPos !== -1 && (bracePos === -1 || semiPos < bracePos)) {
+    return { content: css.slice(start, semiPos + 1), end: semiPos + 1 };
+  }
+  if (bracePos === -1)
+    return null;
+  const block = extractBlock(css, bracePos);
+  if (!block)
+    return null;
+  return {
+    content: css.slice(start, bracePos) + block.content,
+    end: block.end
+  };
+}
+function splitTopLevel(input, separator) {
+  const parts = [];
+  let depth = 0;
+  let quote = null;
+  let start = 0;
+  for (let i = 0; i < input.length; i++) {
+    const ch = input[i];
+    if (quote) {
+      if (ch === "\\") {
+        i++;
+        continue;
+      }
+      if (ch === quote)
+        quote = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      continue;
+    }
+    if (ch === "(" || ch === "[") {
+      depth++;
+      continue;
+    }
+    if (ch === ")" || ch === "]") {
+      depth--;
+      continue;
+    }
+    if (ch === separator && depth === 0) {
+      parts.push(input.slice(start, i));
+      start = i + 1;
+    }
+  }
+  parts.push(input.slice(start));
+  return parts;
+}
+function extractBlock(css, openBrace) {
+  let depth = 0;
+  for (let j = openBrace; j < css.length; j++) {
+    if (css[j] === "{") {
+      depth++;
+    } else if (css[j] === "}") {
+      depth--;
+      if (depth === 0) {
+        return { content: css.slice(openBrace, j + 1), end: j + 1 };
+      }
+    }
+  }
+  return null;
+}

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

@@ -20,7 +20,7 @@ export interface ProxyPrivacy {
  * Privacy input: `true` = full anonymize, `false` = passthrough (still strips sensitive headers),
  * or a `ProxyPrivacy` object for granular control (unset flags default to `false` — opt-in).
  */
-export type ProxyPrivacyInput = boolean | ProxyPrivacy | null;
+export type ProxyPrivacyInput = boolean | ProxyPrivacy;
 /** Resolved privacy with all flags explicitly set. */
 export type ResolvedProxyPrivacy = Required<ProxyPrivacy>;
 /**
@@ -71,7 +71,6 @@ export declare const STRIP_PARAMS: {
     browserVersion: string[];
     browserData: string[];
     location: string[];
-    canvas: string[];
     deviceInfo: string[];
 };
 /**
@@ -130,12 +129,4 @@ export declare function generalizeTimezone(value: unknown): string | number;
  * (timezone, language, screen dimensions) while keeping low-entropy values.
  */
 export declare function anonymizeDeviceInfo(value: string): string;
-/**
- * Recursively anonymize fingerprinting data in payload.
- * Fields are generalized or normalized rather than stripped, so endpoints
- * still receive valid data with reduced fingerprinting precision.
- *
- * When `privacy` is provided, only categories with their flag set to `true` are processed.
- * Default (no arg) = all categories active, so existing callers work unchanged.
- */
 export declare function stripPayloadFingerprinting(payload: Record<string, unknown>, privacy?: ResolvedProxyPrivacy): Record<string, unknown>;

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

@@ -1,8 +1,17 @@
 const FULL_PRIVACY = { ip: true, userAgent: true, language: true, screen: true, timezone: true, hardware: true };
 const NO_PRIVACY = { ip: false, userAgent: false, language: false, screen: false, timezone: false, hardware: false };
+const MAJOR_VERSION_RE = /^(\d+)/;
+const VERSION_RE = /^(\d+)(([.\-_])\d+)*/;
+const VERSION_SPLIT_RE = /[.\-_]/;
+const SNAPCHAT_VERSION_RE = /("version"\s*:\s*")(\d+(?:\.\d+)*)/g;
+const GA_VERSION_RE = /;(\d+(?:\.\d+)*)/g;
+const UPPERCASE_RE = /^[A-Z]/;
+const LANG_CODE_RE = /^[a-z]{2}(?:-[a-z]{2,})?$/i;
 export function resolvePrivacy(input) {
-  if (input === true) return { ...FULL_PRIVACY };
-  if (input === false || input === void 0 || input === null) return { ...NO_PRIVACY };
+  if (input === true)
+    return { ...FULL_PRIVACY };
+  if (input === false || input === void 0)
+    return { ...NO_PRIVACY };
   return {
     ip: input.ip ?? false,
     userAgent: input.userAgent ?? false,
@@ -13,8 +22,10 @@ export function resolvePrivacy(input) {
   };
 }
 export function mergePrivacy(base, override) {
-  if (override === void 0 || override === null) return base;
-  if (typeof override === "boolean") return resolvePrivacy(override);
+  if (override === void 0)
+    return base;
+  if (typeof override === "boolean")
+    return resolvePrivacy(override);
   return {
     ip: override.ip !== void 0 ? override.ip : base.ip,
     userAgent: override.userAgent !== void 0 ? override.userAgent : base.userAgent,
@@ -67,11 +78,13 @@ export const STRIP_PARAMS = {
   // Browser version lists — generalized to major versions (d_bvs = Snapchat, uafvl = GA Client Hints)
   browserVersion: ["d_bvs", "uafvl"],
   // Browser data lists — replaced with empty value
-  browserData: ["plugins", "fonts"],
+  browserData: ["plugins", "fonts", "audiofingerprint"],
   // Location/Timezone — generalized
   location: ["tz", "timezone", "timezoneoffset"],
-  // Canvas/WebGL/Audio fingerprints — replaced with empty value (pure fingerprints, no analytics value)
-  canvas: ["canvas", "webgl", "audiofingerprint"],
+  // Canvas/WebGL fingerprints — neutralized at build time via AST rewriting (rewrite-ast.ts).
+  // These params are no longer stripped at runtime; the source APIs (toDataURL, WEBGL_debug_renderer_info)
+  // are neutralized before the script ever runs.
+  // canvas: ['canvas', 'webgl'],
   // Combined device fingerprinting (X/Twitter dv param contains: timezone, locale, vendor, platform, screen, etc.)
   deviceInfo: ["dv", "device_info", "deviceinfo"]
 };
@@ -81,7 +94,7 @@ export const NORMALIZE_PARAMS = {
 };
 export function anonymizeIP(ip) {
   if (ip.includes(":")) {
-    return ip.split(":").slice(0, 3).join(":") + "::";
+    return `${ip.split(":").slice(0, 3).join(":")}::`;
   }
   const parts = ip.split(".");
   if (parts.length === 4) {
@@ -103,7 +116,7 @@ export function normalizeUserAgent(ua) {
     const idx = ua.indexOf(pattern);
     if (idx !== -1) {
       const versionStart = idx + pattern.length;
-      const majorVersion = ua.slice(versionStart).match(/^(\d+)/)?.[1];
+      const majorVersion = ua.slice(versionStart).match(MAJOR_VERSION_RE)?.[1];
       if (majorVersion)
         return `Mozilla/5.0 (compatible; ${family}/${majorVersion}.0)`;
     }
@@ -119,8 +132,10 @@ const SCREEN_BUCKETS = {
   mobile: { w: 360, h: 640 }
 };
 function getDeviceClass(width) {
-  if (width >= 1200) return "desktop";
-  if (width >= 700) return "tablet";
+  if (width >= 1200)
+    return "desktop";
+  if (width >= 700)
+    return "tablet";
   return "mobile";
 }
 export function generalizeScreen(value, dimension) {
@@ -139,31 +154,38 @@ export function generalizeScreen(value, dimension) {
 }
 export function generalizeHardware(value) {
   const num = typeof value === "number" ? value : Number(value);
-  if (Number.isNaN(num)) return 4;
-  if (num >= 16) return 16;
-  if (num >= 8) return 8;
-  if (num >= 4) return 4;
+  if (Number.isNaN(num))
+    return 4;
+  if (num >= 16)
+    return 16;
+  if (num >= 8)
+    return 8;
+  if (num >= 4)
+    return 4;
   return 2;
 }
 export function generalizeVersion(value) {
-  if (typeof value !== "string") return String(value);
-  const match = value.match(/^(\d+)(([.\-_])\d+)*/);
-  if (!match) return String(value);
+  if (typeof value !== "string")
+    return String(value);
+  const match = value.match(VERSION_RE);
+  if (!match)
+    return String(value);
   const major = match[1];
   const sep = match[3] || ".";
-  const segmentCount = value.split(/[.\-_]/).length;
-  return major + (sep + "0").repeat(segmentCount - 1);
+  const segmentCount = value.split(VERSION_SPLIT_RE).length;
+  return major + `${sep}0`.repeat(segmentCount - 1);
 }
 export function generalizeBrowserVersions(value) {
-  if (typeof value !== "string") return String(value);
+  if (typeof value !== "string")
+    return String(value);
   const zeroSegments = (ver) => {
     const parts = ver.split(".");
     return parts[0] + parts.slice(1).map(() => ".0").join("");
   };
   if (value.includes('"version"'))
-    return value.replace(/("version"\s*:\s*")(\d+(?:\.\d+)*)/g, (_, prefix, ver) => prefix + zeroSegments(ver));
+    return value.replace(SNAPCHAT_VERSION_RE, (_, prefix, ver) => prefix + zeroSegments(ver));
   if (value.includes(";"))
-    return value.replace(/;(\d+(?:\.\d+)*)/g, (_, ver) => ";" + zeroSegments(ver));
+    return value.replace(GA_VERSION_RE, (_, ver) => `;${zeroSegments(ver)}`);
   return value;
 }
 export function generalizeTimezone(value) {
@@ -178,15 +200,16 @@ export function generalizeTimezone(value) {
 export function anonymizeDeviceInfo(value) {
   const sep = value.includes("|") ? "|" : "&";
   const parts = value.split(sep);
-  if (parts.length < 4) return value;
+  if (parts.length < 4)
+    return value;
   const result = [...parts];
   for (let i = 0; i < parts.length; i++) {
     const part = parts[i];
-    if (part.includes("/") && /^[A-Z]/.test(part)) {
+    if (part.includes("/") && UPPERCASE_RE.test(part)) {
       result[i] = String(generalizeTimezone(part));
       continue;
     }
-    if (/^[a-z]{2}(?:-[a-z]{2,})?$/i.test(part)) {
+    if (LANG_CODE_RE.test(part)) {
       result[i] = normalizeLanguage(part);
       continue;
     }
@@ -209,6 +232,13 @@ export function anonymizeDeviceInfo(value) {
   }
   return result.join(sep);
 }
+function matchesParam(key, params) {
+  const lk = key.toLowerCase();
+  return params.some((pm) => {
+    const lp = pm.toLowerCase();
+    return lk === lp || lk.startsWith(`${lp}[`);
+  });
+}
 export function stripPayloadFingerprinting(payload, privacy) {
   const p = privacy || FULL_PRIVACY;
   const result = {};
@@ -216,18 +246,12 @@ export function stripPayloadFingerprinting(payload, privacy) {
   for (const [key, value] of Object.entries(payload)) {
     if (key.toLowerCase() === "sw") {
       const num = typeof value === "number" ? value : Number(value);
-      if (!Number.isNaN(num)) deviceClass = getDeviceClass(num);
+      if (!Number.isNaN(num))
+        deviceClass = getDeviceClass(num);
     }
   }
   for (const [key, value] of Object.entries(payload)) {
     const lowerKey = key.toLowerCase();
-    const matchesParam = (key2, params) => {
-      const lk = key2.toLowerCase();
-      return params.some((pm) => {
-        const lp = pm.toLowerCase();
-        return lk === lp || lk.startsWith(lp + "[");
-      });
-    };
     const isLanguageParam = NORMALIZE_PARAMS.language.some((pm) => lowerKey === pm.toLowerCase());
     if (isLanguageParam) {
       if (Array.isArray(value)) {
@@ -264,7 +288,7 @@ export function stripPayloadFingerprinting(payload, privacy) {
       continue;
     }
     if (matchesParam(key, STRIP_PARAMS.hardware)) {
-      result[key] = p.screen ? generalizeHardware(value) : value;
+      result[key] = p.hardware ? generalizeHardware(value) : value;
       continue;
     }
     if (matchesParam(key, STRIP_PARAMS.version)) {
@@ -280,11 +304,7 @@ export function stripPayloadFingerprinting(payload, privacy) {
       continue;
     }
     if (matchesParam(key, STRIP_PARAMS.browserData)) {
-      result[key] = p.hardware ? Array.isArray(value) ? [] : "" : value;
-      continue;
-    }
-    if (matchesParam(key, STRIP_PARAMS.canvas)) {
-      result[key] = p.hardware ? typeof value === "number" ? 0 : typeof value === "object" ? {} : "" : value;
+      result[key] = p.hardware ? Array.isArray(value) ? [] : typeof value === "number" ? 0 : "" : value;
       continue;
     }
     if (matchesParam(key, STRIP_PARAMS.deviceInfo)) {

package/dist/runtime/server/utils/proxy-url.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Build a proxy URL with query params, signing it when a secret is available.
+ *
+ * Used by embed handlers that inject proxy URLs into HTML/JSON responses.
+ * When `secret` is set, URLs are HMAC-signed so clients can fetch them without
+ * needing a page token. When it's undefined, URLs fall back to unsigned form
+ * (which is only safe when the `withSigning` middleware has no secret either).
+ */
+export declare function buildProxyUrl(path: string, query: Record<string, unknown>, secret?: string): string;

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>;