feat(proxy): support path aliases to hide third-party hostnames (#821)

Author: harlan-zw

FIRST_PARTY.md

@@ -53,6 +53,22 @@ Some SDKs have quirks that require targeted regex patches after AST rewriting. T
 
 Note: Google Analytics previously needed `postProcess` regex patches for dynamically constructed collect URLs. This is no longer needed since the runtime intercept plugin catches all non-same-origin URLs at the `sendBeacon`/`fetch` call site.
 
+## Path aliases (`proxy.alias`)
+
+By default proxy paths embed the verbatim third-party hostname (`/_scripts/p/us.i.posthog.com/e/`), which leaks self-hosted/internal domains and is trivially classified by ad-blockers. `scripts.proxy.alias` replaces the hostname segment with an alias:
+- `true` — auto-generate a short deterministic hash per domain (`sha256(domain).slice(0,8)`)
+- `Record<domain, alias>` — explicit aliases; unlisted domains stay verbatim
+
+The pure logic lives in `proxy-alias.ts` (`aliasForDomain`, `buildDomainAliasMap`, `invertAliasMap`, `aliasProxyValue`). The module builds a `domain → alias` map from every proxied domain (those in `domainPrivacy`) and threads it through every point that emits a proxy path:
+- **Build-time rewrites** (`transform.ts`): `to: ${proxyPrefix}/${alias ?? domain}`
+- **Auto-inject** (`applyAutoInject`): `aliasProxyValue` rewrites the host segment of the computed endpoint
+- **Runtime intercept** (`intercept.ts`): embeds the alias map; `proxyUrl` maps `parsed.host → alias`
+- **Partytown** (`generatePartytownResolveUrl`): embeds the alias map; worker requests map `url.host → alias`
+- **Server handler** (`proxy-handler.ts`): the inverted `aliasToDomain` map resolves the alias segment back to the real domain before allowlist matching and forwarding (verbatim hostnames still resolve, so aliasing is non-breaking)
+- **Devtools** (`useScript.ts` network matcher): `aliasToDomain` is exposed in devtools config so aliased requests still attribute to their script
+
+Wildcard domains (`*`) are never aliased — they have no literal path form to rewrite and only exist for runtime allowlist matching.
+
 ## Key mapping
 
 Proxy config keys match registry keys directly — no indirection layer. A script's `registryKey` is used to look up its proxy config from `proxy-configs.ts`.

docs/content/docs/1.guides/2.first-party.md

@@ -144,6 +144,49 @@ export default defineNuxtConfig({
 })
 ```
 
+## Hiding Hostnames
+
+By default, proxied requests embed the real third-party hostname in the path, for example `/_scripts/p/us.i.posthog.com/e/`. For self-hosted services this leaks your internal domain (e.g. `/_scripts/p/analytics.internal.example.com/api/send`) into client-facing URLs, and the verbatim hostname makes requests easy for ad-blockers and network observers to classify.
+
+Use `proxy.alias` to replace hostnames with an alias in the path. The real domain never appears in the URL.
+
+Set `alias: true` to auto-generate a short opaque alias per domain:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  scripts: {
+    proxy: {
+      alias: true, // /_scripts/p/a1b2c3d4/e/
+    }
+  }
+})
+```
+
+Or map specific domains to custom aliases. Domains not listed keep their verbatim hostname:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  scripts: {
+    proxy: {
+      alias: {
+        'us.i.posthog.com': 'ph',
+        'analytics.internal.example.com': 'a',
+      }
+    }
+  }
+})
+```
+
+Aliases apply everywhere a proxy path is produced: build-time URL rewrites, auto-injected endpoints (such as PostHog's `apiHost`), runtime-intercepted requests, and Partytown worker requests. The server handler resolves the alias back to the real domain before forwarding upstream.
+
+::callout{type="info"}
+Aliases only change the path segment. To also change the `/_scripts/p` prefix itself, set the top-level `prefix` option (e.g. `prefix: '/_t'`).
+::
+
+::callout{type="warning"}
+Aliases keep the real hostname out of request **URLs**, which is what ad-blockers and network observers match on. For scripts whose collection URL is built at runtime (e.g. a self-hosted endpoint passed via config), the real host can still appear in the client JavaScript, since the script needs to know where it would otherwise send. Aliasing does not obfuscate your bundle, it removes the hostname from the network-visible path.
+::
+
 ## Opting Out
 
 ### Per-Script

packages/script/src/devtools.ts

@@ -129,6 +129,8 @@ export interface ProxyDevtoolsData {
   privacyMode: string
   scripts: ProxyDevtoolsScript[]
   totalDomains: number
+  /** Path alias → real domain, so devtools can attribute aliased proxy requests. */
+  aliasToDomain?: Record<string, string>
 }
 
 function computeDevtoolsPrivacyLevel(privacy: Record<string, boolean>): 'full' | 'partial' | 'none' {
@@ -178,6 +180,7 @@ export function buildDevtoolsData(
   proxyPrefix: string,
   privacyLabel: string,
   scripts: ProxyDevtoolsScript[],
+  aliasToDomain?: Record<string, string>,
 ): ProxyDevtoolsData {
   const allDomains = new Set<string>()
   for (const s of scripts) {
@@ -190,5 +193,6 @@ export function buildDevtoolsData(
     privacyMode: privacyLabel,
     scripts,
     totalDomains: allDomains.size,
+    aliasToDomain,
   }
 }

packages/script/src/module.ts

@@ -1,6 +1,7 @@
 import type { FetchOptions } from 'ofetch'
 import type { ProxyDevtoolsScript } from './devtools'
 import type { NormalizedRegistryEntry } from './normalize'
+import type { ProxyAliasConfig } from './proxy-alias'
 import type { ProxyPrivacyInput } from './runtime/server/utils/privacy'
 import type {
   FirstPartyPrivacy,
@@ -38,6 +39,7 @@ import { extractRequiredFields, migrateDeprecatedRegistryKeys, normalizeRegistry
 import { NuxtScriptsCheckScripts } from './plugins/check-scripts'
 import { generateInterceptPluginContents } from './plugins/intercept'
 import { NuxtScriptBundleTransformer } from './plugins/transform'
+import { aliasProxyValue, buildDomainAliasMap, invertAliasMap, isSafeAliasSegment } from './proxy-alias'
 import { buildProxyConfigsFromRegistry, generatePartytownResolveUrl, getPartytownForwards, registry, resolveCapabilities } from './registry'
 import { registerTypeTemplates, templatePlugin, templateTriggerResolver } from './templates'
 import { validateScriptsEnvVars } from './validate-env'
@@ -215,6 +217,7 @@ export function applyAutoInject(
   proxyPrefix: string,
   registryKey: string,
   autoInject: ResolvedProxyAutoInject,
+  alias?: ProxyAliasConfig,
 ): void {
   if (isProxyDisabled(registryKey, registry, runtimeConfig))
     return
@@ -229,7 +232,7 @@ export function applyAutoInject(
   if (!config || config[autoInject.configField])
     return
 
-  const value = autoInject.computeValue(proxyPrefix, config)
+  const value = aliasProxyValue(autoInject.computeValue(proxyPrefix, config), proxyPrefix, alias)
   input[autoInject.configField] = value
 
   if (rtEntry && typeof rtEntry === 'object' && rtEntry !== input)
@@ -316,6 +319,23 @@ export interface ModuleOptions {
    * @default undefined (per-script defaults)
    */
   privacy?: FirstPartyPrivacy
+  /**
+   * First-party proxy behaviour.
+   */
+  proxy?: {
+    /**
+     * Replace third-party hostnames in proxy paths with aliases, so the real domain
+     * (e.g. a self-hosted analytics host) never appears in client-facing URLs.
+     *
+     * - `false` (default): paths embed the verbatim hostname (`/_scripts/p/us.i.posthog.com/...`)
+     * - `true`: auto-generate a short opaque alias per domain (`/_scripts/p/a1b2c3d4/...`)
+     * - `Record<domain, alias>`: explicit aliases (domain → alias); unlisted domains stay verbatim
+     *
+     * @default false
+     * @example { 'us.i.posthog.com': 'ph', 'analytics.internal.example.com': 'a' }
+     */
+    alias?: ProxyAliasConfig
+  }
   /**
    * The registry of supported third-party scripts. Presence enables infrastructure (proxy routes, types, bundling, composable auto-imports).
    * Scripts only auto-load globally when `trigger` is explicitly set in the config object.
@@ -853,6 +873,11 @@ export default defineNuxtModule<ModuleOptions>({
         }
       }
 
+      // Path alias config — maps real third-party domains to opaque/custom aliases so
+      // hostnames don't leak into client-facing proxy URLs. Shared with the transformer.
+      const proxyAlias = config.proxy?.alias
+      let domainAliases: Record<string, string> = {}
+
       // Finalize proxy setup: build configs, register intercept plugin, wire devtools
       if (anyNeedsProxy) {
         const builtConfigs = buildProxyConfigsFromRegistry(registryScripts, scriptByKey)
@@ -903,7 +928,7 @@ export default defineNuxtModule<ModuleOptions>({
           }
 
           if (proxyConfig.autoInject && config.registry)
-            applyAutoInject(config.registry, nuxt.options.runtimeConfig, proxyPrefix, key, proxyConfig.autoInject)
+            applyAutoInject(config.registry, nuxt.options.runtimeConfig, proxyPrefix, key, proxyConfig.autoInject, proxyAlias)
 
           if (nuxt.options.dev)
             devtoolsScripts.push(buildDevtoolsEntry(key, script, configKey, proxyConfig))
@@ -922,16 +947,37 @@ export default defineNuxtModule<ModuleOptions>({
           )
         }
 
+        // Build the domain → alias map from every proxied domain, then warn on any
+        // collision (two domains resolving to the same alias would mis-route at runtime).
+        domainAliases = buildDomainAliasMap(Object.keys(domainPrivacy), proxyAlias)
+        // Validate aliases at the build boundary so the runtime map is unambiguous:
+        // every alias must be a safe single path segment, unique, and must not equal a
+        // real proxied domain (else the verbatim-hostname fallback could pick the wrong one).
+        const realDomains = new Set(Object.keys(domainPrivacy))
+        const aliasOwner = new Map<string, string>()
+        for (const [domain, alias] of Object.entries(domainAliases)) {
+          if (!isSafeAliasSegment(alias))
+            throw new Error(`[nuxt-scripts] Invalid proxy alias "${alias}" for "${domain}": use a single URL-safe path segment (letters, digits, '-', '_', '.').`)
+          if (realDomains.has(alias))
+            throw new Error(`[nuxt-scripts] Proxy alias "${alias}" for "${domain}" collides with proxied domain "${alias}". Pick an alias that is not also a proxied hostname.`)
+          const prev = aliasOwner.get(alias)
+          if (prev)
+            throw new Error(`[nuxt-scripts] Proxy alias collision: "${prev}" and "${domain}" both map to "${alias}". Give each domain a unique alias.`)
+          aliasOwner.set(alias, domain)
+        }
+        const aliasToDomain = invertAliasMap(domainAliases)
+
         // Register intercept plugin
         addPluginTemplate({
           filename: 'nuxt-scripts-intercept.client.mjs',
-          getContents() { return generateInterceptPluginContents(proxyPrefix, { testMode: !!nuxt.options.test }) },
+          getContents() { return generateInterceptPluginContents(proxyPrefix, { testMode: !!nuxt.options.test, domainAliases }) },
         })
 
         // Server-side proxy config
         nuxt.options.runtimeConfig['nuxt-scripts-proxy'] = {
           proxyPrefix,
           domainPrivacy,
+          aliasToDomain,
           privacy: config.privacy,
         } as any
 
@@ -954,14 +1000,14 @@ export default defineNuxtModule<ModuleOptions>({
 
         // Expose devtools data
         if (nuxt.options.dev) {
-          nuxt.options.runtimeConfig.public['nuxt-scripts-devtools'] = buildDevtoolsData(proxyPrefix, privacyLabel, devtoolsScripts) as any
+          nuxt.options.runtimeConfig.public['nuxt-scripts-devtools'] = buildDevtoolsData(proxyPrefix, privacyLabel, devtoolsScripts, aliasToDomain) as any
         }
 
         // Auto-configure Partytown resolveUrl for proxy
         if (partytownScripts.size && hasNuxtModule('@nuxtjs/partytown')) {
           const partytownConfig = (nuxt.options as any).partytown || {}
           if (!partytownConfig.resolveUrl) {
-            partytownConfig.resolveUrl = generatePartytownResolveUrl(proxyPrefix)
+            partytownConfig.resolveUrl = generatePartytownResolveUrl(proxyPrefix, domainAliases)
             ;(nuxt.options as any).partytown = partytownConfig
             logger.info('[partytown] Auto-configured resolveUrl for proxy')
           }
@@ -981,6 +1027,7 @@ export default defineNuxtModule<ModuleOptions>({
         registryConfig: nuxt.options.runtimeConfig.public.scripts as Record<string, any> | undefined,
         proxyConfigs,
         proxyPrefix,
+        domainAliases,
         partytownScripts,
         moduleDetected(module) {
           if (nuxt.options.dev && module !== '@nuxt/scripts' && !moduleInstallPromises.has(module) && !hasNuxtModule(module))

packages/script/src/plugins/intercept.ts

@@ -4,16 +4,21 @@
  * that route matching URLs through the proxy. AST rewriting transforms
  * native API calls to use these wrappers at build time.
  *
- * Any non-same-origin URL is proxied through `proxyPrefix/<host><path>`.
+ * Any non-same-origin URL is proxied through `proxyPrefix/<host-or-alias><path>`.
  * No domain allowlist needed: only AST-rewritten third-party scripts call __nuxtScripts.
+ *
+ * `domainAliases` (real domain → path alias) is embedded so runtime-constructed URLs
+ * (e.g. self-hosted analytics endpoints) use the same opaque path segment as build-time
+ * rewrites, keeping hostnames out of client URLs.
  */
-export function generateInterceptPluginContents(proxyPrefix: string, options?: { testMode?: boolean }): string {
+export function generateInterceptPluginContents(proxyPrefix: string, options?: { testMode?: boolean, domainAliases?: Record<string, string> }): string {
   const testMode = options?.testMode ?? false
   return `export default defineNuxtPlugin({
   name: 'nuxt-scripts:intercept',
   enforce: 'pre',
   setup() {
     const proxyPrefix = ${JSON.stringify(proxyPrefix)};
+    const domainAliases = ${JSON.stringify(options?.domainAliases ?? {})};
     const origBeacon = typeof navigator !== 'undefined' && navigator.sendBeacon
       ? navigator.sendBeacon.bind(navigator)
       : () => false;
@@ -22,8 +27,10 @@ export function generateInterceptPluginContents(proxyPrefix: string, options?: {
     function proxyUrl(url) {
       try {
         const parsed = new URL(url, location.origin);
-        if (parsed.origin !== location.origin)
-          return location.origin + proxyPrefix + '/' + parsed.host + parsed.pathname + parsed.search;
+        if (parsed.origin !== location.origin) {
+          const seg = domainAliases[parsed.host] || parsed.host;
+          return location.origin + proxyPrefix + '/' + seg + parsed.pathname + parsed.search;
+        }
       } catch {}
       return url;
     }

packages/script/src/plugins/transform.ts

@@ -73,6 +73,8 @@ export interface AssetBundlerTransformerOptions {
    * Proxy prefix for first-party mode. Used to derive rewrite targets from domains.
    */
   proxyPrefix?: string
+  /** Map of real third-party domain → path alias, used to hide hostnames in proxy URLs. */
+  domainAliases?: Record<string, string>
   fallbackOnSrcOnBundleFail?: boolean
   fetchOptions?: FetchOptions
   cacheMaxAge?: number
@@ -469,7 +471,7 @@ export function NuxtScriptBundleTransformer(options: AssetBundlerTransformerOpti
                     // no literal form to rewrite at build time.
                     const proxyRewrites = proxyConfig?.domains?.filter(domain => !domain.includes('*')).map(domain => ({
                       from: domain,
-                      to: `${options.proxyPrefix}/${domain}`,
+                      to: `${options.proxyPrefix}/${options.domainAliases?.[domain] ?? domain}`,
                     }))
                     // Bundle-only SDK patches (independent of proxy). Used when bundling
                     // a script that needs neutralize-domain-check etc. but should keep

packages/script/src/proxy-alias.ts

@@ -0,0 +1,77 @@
+import { createHash } from 'node:crypto'
+
+/**
+ * Proxy path alias configuration.
+ * - `false` / `undefined`: proxy paths use the verbatim third-party hostname
+ *   (`/_scripts/p/us.i.posthog.com/...`).
+ * - `true`: every proxied domain gets a short deterministic opaque alias
+ *   (`/_scripts/p/a1b2c3d4/...`), so the real hostname never appears in client URLs.
+ * - `Record<domain, alias>`: explicit aliases (domain → alias). Domains not listed
+ *   keep their verbatim hostname.
+ */
+export type ProxyAliasConfig = boolean | Record<string, string> | undefined
+
+const WILDCARD_RE = /\*/
+// An alias is interpolated into `/_scripts/p/<alias>/...`, so it must be a single
+// URL path segment: no slash/query/hash/whitespace that would split or break the path.
+const SAFE_ALIAS_SEGMENT_RE = /^[\w.-]+$/
+
+/** Whether an explicit alias is a single URL-safe path segment. */
+export function isSafeAliasSegment(alias: string): boolean {
+  return SAFE_ALIAS_SEGMENT_RE.test(alias)
+}
+
+/**
+ * Resolve the alias for a single third-party domain. Pure and deterministic so the
+ * build-time rewrites and the runtime reverse map always agree without sharing state.
+ *
+ * Returns `undefined` when the domain should keep its verbatim hostname (no alias
+ * configured, or a wildcard pattern that has no literal path form to rewrite).
+ */
+export function aliasForDomain(domain: string, alias: ProxyAliasConfig): string | undefined {
+  if (!alias || WILDCARD_RE.test(domain))
+    return undefined
+  if (alias === true)
+    // 12 hex chars (48 bits) — collision space large enough that auto-aliasing never
+    // silently misroutes; explicit-alias collisions are caught at build time instead.
+    return createHash('sha256').update(domain).digest('hex').slice(0, 12)
+  // Own-property guard so a domain literally named `toString`/`constructor` can't
+  // resolve to an inherited prototype member.
+  return Object.hasOwn(alias, domain) ? (alias[domain] || undefined) : undefined
+}
+
+/** Build a `domain → alias` map for the given proxied domains. */
+export function buildDomainAliasMap(domains: Iterable<string>, alias: ProxyAliasConfig): Record<string, string> {
+  const map: Record<string, string> = {}
+  for (const domain of domains) {
+    const value = aliasForDomain(domain, alias)
+    if (value)
+      map[domain] = value
+  }
+  return map
+}
+
+/** Invert a `domain → alias` map into the `alias → domain` map the proxy handler resolves with. */
+export function invertAliasMap(map: Record<string, string>): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const [domain, alias] of Object.entries(map))
+    out[alias] = domain
+  return out
+}
+
+/**
+ * Rewrite the leading `${proxyPrefix}/${host}` segment of a generated proxy path so the
+ * host is replaced with its alias. Used for auto-injected endpoint values (e.g. PostHog's
+ * `apiHost`) where the host is produced by an arbitrary `resolve` function.
+ */
+export function aliasProxyValue(value: string, proxyPrefix: string, alias: ProxyAliasConfig): string {
+  const prefix = `${proxyPrefix}/`
+  if (!alias || !value.startsWith(prefix))
+    return value
+  const rest = value.slice(prefix.length)
+  const host = rest.match(/^[^/?#]+/)?.[0]
+  if (!host)
+    return value
+  const aliased = aliasForDomain(host, alias)
+  return aliased ? `${prefix}${aliased}${rest.slice(host.length)}` : value
+}

packages/script/src/registry.ts

@@ -869,12 +869,17 @@ export async function registry(resolve?: (path: string) => Promise<string>): Pro
 /**
  * Generate a Partytown `resolveUrl` function string for proxy routing.
  * Partytown calls this for every network request made by worker-executed scripts.
- * Any non-same-origin URL is proxied through `proxyPrefix/<host><path>`.
+ * Any non-same-origin URL is proxied through `proxyPrefix/<host-or-alias><path>`.
+ *
+ * `domainAliases` (real domain → path alias) is embedded so worker requests use the
+ * same opaque path segment as build-time rewrites, keeping hostnames out of URLs.
  */
-export function generatePartytownResolveUrl(proxyPrefix: string): string {
+export function generatePartytownResolveUrl(proxyPrefix: string, domainAliases: Record<string, string> = {}): string {
   return `function(url, location, type) {
   if (url.origin !== location.origin) {
-    return new URL(${JSON.stringify(proxyPrefix)} + '/' + url.host + url.pathname + url.search, location.origin);
+    var aliases = ${JSON.stringify(domainAliases)};
+    var seg = aliases[url.host] || url.host;
+    return new URL(${JSON.stringify(proxyPrefix)} + '/' + seg + url.pathname + url.search, location.origin);
   }
 }`
 }