@djangocfg/nextjs 2.1.478 → 2.1.480

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/nextjs",
-  "version": "2.1.478",
+  "version": "2.1.480",
   "description": "Next.js server utilities: sitemap, health, OG images, contact forms, navigation, config",
   "keywords": [
     "nextjs",
@@ -144,9 +144,9 @@
     "ai-docs": "tsx src/ai/cli.ts"
   },
   "peerDependencies": {
-    "@djangocfg/devtools": "^2.1.478",
-    "@djangocfg/i18n": "^2.1.478",
-    "@djangocfg/ui-core": "^2.1.478",
+    "@djangocfg/devtools": "^2.1.480",
+    "@djangocfg/i18n": "^2.1.480",
+    "@djangocfg/ui-core": "^2.1.480",
     "next": "^16.2.2"
   },
   "peerDependenciesMeta": {
@@ -168,11 +168,11 @@
     "serwist": "^9.5.11"
   },
   "devDependencies": {
-    "@djangocfg/devtools": "^2.1.478",
-    "@djangocfg/i18n": "^2.1.478",
-    "@djangocfg/layouts": "^2.1.478",
-    "@djangocfg/typescript-config": "^2.1.478",
-    "@djangocfg/ui-core": "^2.1.478",
+    "@djangocfg/devtools": "^2.1.480",
+    "@djangocfg/i18n": "^2.1.480",
+    "@djangocfg/layouts": "^2.1.480",
+    "@djangocfg/typescript-config": "^2.1.480",
+    "@djangocfg/ui-core": "^2.1.480",
     "@types/node": "^25.9.5",
     "@types/react": "19.2.15",
     "@types/react-dom": "19.2.3",

package/src/config/createNextConfig.ts

@@ -27,6 +27,7 @@ import type { Configuration as WebpackConfig } from 'webpack';
 import { type I18nPluginOptions, withI18n } from '../i18n/plugin';
 import { type PWAPluginOptions, withPWA } from '../pwa/plugin';
 import { DEFAULT_OPTIMIZE_PACKAGES, DEFAULT_TRANSPILE_PACKAGES } from './constants';
+import { CSP_BASELINE_VENDORS, type CspVendor, resolveCspVendors } from './csp';
 import { addCompressionPlugins } from './plugins/compression';
 import { DevStartupPlugin } from './plugins/devStartup';
 import { deepMerge } from './utils/deepMerge';
@@ -87,24 +88,50 @@ export interface BaseNextConfigOptions {
    *   naming every future embed's origin is not worth the maintenance —
    *   `X-Content-Type-Options`/`Referrer-Policy`/`X-Frame-Options` below
    *   still apply.
-   * - object — keep the baseline CSP but additively loosen specific
-   *   directives for named trusted origins (the pattern `stripe` above is
-   *   a hardcoded special case of). Every array is additive; omit a key to
-   *   leave that directive untouched.
+   * - object — keep the baseline CSP but additively loosen it. Prefer
+   *   `vendors` (declare WHAT you use by name; the package owns which origins
+   *   that implies) over hand-listing origins per directive. Every array is
+   *   additive; omit a key to leave that directive untouched.
    * - omitted — tightest default (`frame-src 'self'`, etc.), same as today.
    *
+   * **The deployment platform counts as a vendor.** Some origins are injected
+   * into the response by the EDGE, after Next.js has emitted this header —
+   * Cloudflare Web Analytics rewrites `beacon.min.js` into the HTML when the
+   * feature is on for the zone. Nothing in the source tree reveals that, so
+   * any app served through such a zone must name the platform in `vendors`
+   * (e.g. `'cloudflare'`) or it will violate its own CSP in production only.
+   *
    * @example
    * ```ts
-   * // No CSP at all — simplest option for a low-risk app with ad hoc embeds
-   * createBaseNextConfig({ csp: false })
+   * // Declare the third parties this app actually uses — origins come from
+   * // the shared registry, so a vendor host change is fixed in one place.
+   * createBaseNextConfig({ csp: { vendors: ['stripe', 'cloudflare'] } })
    *
-   * // Keep CSP, just allow one trusted iframe origin
+   * // Escape hatch for something not in the registry yet
    * createBaseNextConfig({ csp: { frameSrc: ['https://www.youtube-nocookie.com'] } })
+   *
+   * // No CSP at all — simplest option for a low-risk app with ad hoc embeds
+   * createBaseNextConfig({ csp: false })
    * ```
    */
   csp?:
     | false
     | {
+        /**
+         * Named third-party vendors this app uses (`'stripe'`, `'cloudflare'`,
+         * `'google-analytics'`, …). Each expands to the exact origins that
+         * vendor needs across the relevant directives. See `CSP_VENDOR_PRESETS`
+         * for the full list. Unknown names warn at build time, never throw.
+         */
+        vendors?: (CspVendor | (string & {}))[];
+        /**
+         * Cloudflare Web Analytics origins are in the baseline (see
+         * `CSP_BASELINE_VENDORS`) because DjangoCFG apps are Cloudflare-served
+         * and the beacon is injected at the edge, where no app can see it.
+         * Set `false` only for an app served off Cloudflare entirely.
+         * @default true
+         */
+        cloudflare?: boolean;
         /** Extra `frame-src` origins (iframes this app embeds). */
         frameSrc?: string[];
         /** Extra `script-src` origins (third-party SDK scripts). */
@@ -255,25 +282,39 @@ export function createBaseNextConfig(
       // In dev the backend (Django, Centrifugo) is plain http/ws on localhost,
       // so connect/img must allow http:/ws:. Production stays strict (https/wss
       // only) to forbid downgrade/cleartext exfiltration.
-      // Stripe.js needs its SDK host in script-src, its iframe hosts in
-      // frame-src, and its API host in connect-src. Opt-in per app via
-      // `options.stripe` — one hardcoded special case of the general
-      // `options.csp` additive-origin escape hatch below.
-      const stripeScript = options.stripe ? ' https://js.stripe.com' : '';
-      const stripeConnect = options.stripe ? ' https://api.stripe.com' : '';
-      const stripeFrame = options.stripe
-        ? ' https://js.stripe.com https://checkout.stripe.com'
-        : '';
-
-      const extraScript = cspExtra?.scriptSrc?.length ? ' ' + cspExtra.scriptSrc.join(' ') : '';
-      const extraConnect = cspExtra?.connectSrc?.length ? ' ' + cspExtra.connectSrc.join(' ') : '';
-      const extraFrame = cspExtra?.frameSrc?.length ? ' ' + cspExtra.frameSrc.join(' ') : '';
-      const extraImg = cspExtra?.imgSrc?.length ? ' ' + cspExtra.imgSrc.join(' ') : '';
-      const extraFont = cspExtra?.fontSrc?.length ? ' ' + cspExtra.fontSrc.join(' ') : '';
+      //
+      // Third-party origins come from the shared vendor registry (./csp), so
+      // "which hosts does Stripe need" is answered in exactly one place. The
+      // legacy `stripe: true` flag is just sugar for `vendors: ['stripe']` and
+      // resolves through that same registry — no second copy of the origins.
+      // Baseline vendors apply unless explicitly opted out. Cloudflare is in
+      // here rather than per-app because the edge injects its beacon into the
+      // response AFTER this header is emitted — an app cannot detect that from
+      // its own source, so leaving it opt-in guarantees a silent production
+      // breakage in every app that forgets it (which was all of them).
+      const vendorNames = [
+        ...(cspExtra?.cloudflare === false ? [] : CSP_BASELINE_VENDORS),
+        ...(options.stripe ? ['stripe'] : []),
+        ...(cspExtra?.vendors ?? []),
+      ];
+      const vendor = resolveCspVendors(vendorNames);
+
+      // Vendor-derived origins and the per-directive escape hatch are equivalent
+      // and additive; a host named by both is emitted once.
+      const join = (...groups: (string[] | undefined)[]) => {
+        const all = [...new Set(groups.flatMap((g) => g ?? []))];
+        return all.length ? ' ' + all.join(' ') : '';
+      };
+
+      const extraScript = join(vendor.scriptSrc, cspExtra?.scriptSrc);
+      const extraConnect = join(vendor.connectSrc, cspExtra?.connectSrc);
+      const extraFrame = join(vendor.frameSrc, cspExtra?.frameSrc);
+      const extraImg = join(vendor.imgSrc, cspExtra?.imgSrc);
+      const extraFont = join(vendor.fontSrc, cspExtra?.fontSrc);
 
       const connectSrc = isDev
-        ? `connect-src 'self' http: https: ws: wss:${stripeConnect}${extraConnect}`
-        : `connect-src 'self' https: wss:${stripeConnect}${extraConnect}`;
+        ? `connect-src 'self' http: https: ws: wss:${extraConnect}`
+        : `connect-src 'self' https: wss:${extraConnect}`;
       const imgSrc = isDev
         ? `img-src 'self' data: blob: http: https:${extraImg}`
         : `img-src 'self' data: blob: https:${extraImg}`;
@@ -282,15 +323,15 @@ export function createBaseNextConfig(
         const cspDirectives = [
           "default-src 'self'",
           // Next.js requires inline + eval for its runtime/HMR. Tighten to nonces later.
-          `script-src 'self' 'unsafe-inline' 'unsafe-eval'${stripeScript}${extraScript}`,
+          `script-src 'self' 'unsafe-inline' 'unsafe-eval'${extraScript}`,
           "style-src 'self' 'unsafe-inline'",
           imgSrc,
           `font-src 'self' data:${extraFont}`,
           // API/websocket calls go cross-origin to Django/Centrifugo.
           connectSrc,
-          // Stripe Elements/Checkout and any app-declared trusted origins
-          // (options.csp.frameSrc) mount iframes; add their hosts when enabled.
-          `frame-src 'self'${stripeFrame}${extraFrame}`,
+          // Declared vendors (Stripe Elements/Checkout, video embeds…) and any
+          // app-declared trusted origins mount iframes; add their hosts here.
+          `frame-src 'self'${extraFrame}`,
           "object-src 'none'",
           "base-uri 'self'",
           "form-action 'self'",

package/src/config/csp.ts

@@ -0,0 +1,180 @@
+/**
+ * CSP Vendor Presets
+ *
+ * The problem this solves: every third-party script a DjangoCFG app loads needs
+ * its origin named in the CSP, and until now each app had to hand-list those
+ * origins (`csp: { scriptSrc: [...] }`) in its own `next.config.ts`. That
+ * repeats the same Stripe/Cloudflare/Google origin strings across every app,
+ * and — worse — nobody remembers which directive a given vendor needs, so the
+ * usual outcome is a production-only console error and a scramble.
+ *
+ * Instead, apps declare WHAT THEY USE by name (`csp: { vendors: ['stripe'] }`)
+ * and this registry owns WHICH ORIGINS that implies. When a vendor changes a
+ * host, it is fixed once here and every app inherits the fix on its next build.
+ *
+ * Adding a vendor: add an entry below, keyed by a short stable name, listing
+ * only the directives it genuinely needs. Keep the origins exact — never widen
+ * a directive to a bare `https:` to make a vendor work.
+ */
+
+/** The CSP directives a vendor preset may contribute origins to. */
+export interface CspOrigins {
+  /** `script-src` — the vendor's SDK/tag `<script>` hosts. */
+  scriptSrc?: string[];
+  /** `frame-src` — hosts the vendor mounts iframes from. */
+  frameSrc?: string[];
+  /** `connect-src` — hosts the vendor makes XHR/fetch/WebSocket calls to. */
+  connectSrc?: string[];
+  /** `img-src` — hosts the vendor loads images/pixels from. */
+  imgSrc?: string[];
+  /** `font-src` — hosts the vendor loads web fonts from. */
+  fontSrc?: string[];
+}
+
+/**
+ * Known third-party vendors and the CSP origins each one requires.
+ *
+ * Every entry is OFF by default — an app opts in via `csp.vendors`, so an app
+ * that mounts nothing third-party keeps the tightest possible policy.
+ */
+export const CSP_VENDOR_PRESETS = {
+  /**
+   * Stripe.js / Checkout / Elements.
+   *
+   * `js.stripe.com` serves the SDK and also hosts the Elements iframes;
+   * `checkout.stripe.com` is the hosted Checkout iframe; `api.stripe.com`
+   * takes the tokenization/confirm XHR. Without all three the payment form
+   * silently fails to render.
+   */
+  stripe: {
+    scriptSrc: ['https://js.stripe.com'],
+    frameSrc: ['https://js.stripe.com', 'https://checkout.stripe.com'],
+    connectSrc: ['https://api.stripe.com'],
+  },
+
+  /**
+   * Cloudflare Web Analytics (the RUM beacon).
+   *
+   * IMPORTANT: this script is NOT in the app's own HTML — when Web Analytics
+   * is enabled on the zone, Cloudflare INJECTS `beacon.min.js` into the
+   * response at the edge, after Next.js has already emitted the CSP header.
+   * So any app served through a Cloudflare zone with that feature on will
+   * violate its own CSP unless this preset is enabled, no matter what the
+   * source tree contains. The beacon also POSTs its payload back to
+   * `cloudflareinsights.com`, hence the `connect-src` entry.
+   */
+  cloudflare: {
+    scriptSrc: ['https://static.cloudflareinsights.com'],
+    connectSrc: ['https://cloudflareinsights.com', 'https://static.cloudflareinsights.com'],
+  },
+
+  /** Google Analytics 4 / gtag.js. */
+  'google-analytics': {
+    scriptSrc: ['https://www.googletagmanager.com', 'https://www.google-analytics.com'],
+    connectSrc: [
+      'https://www.google-analytics.com',
+      'https://analytics.google.com',
+      'https://region1.google-analytics.com',
+    ],
+    imgSrc: ['https://www.google-analytics.com', 'https://www.googletagmanager.com'],
+  },
+
+  /** Google Tag Manager (the container itself; tags it loads may need more). */
+  'google-tag-manager': {
+    scriptSrc: ['https://www.googletagmanager.com'],
+    connectSrc: ['https://www.googletagmanager.com'],
+    imgSrc: ['https://www.googletagmanager.com'],
+    frameSrc: ['https://www.googletagmanager.com'],
+  },
+
+  /** Google Fonts (stylesheet host + the font files themselves). */
+  'google-fonts': {
+    fontSrc: ['https://fonts.gstatic.com'],
+  },
+
+  /** Sentry browser SDK — errors/traces are POSTed to the ingest host. */
+  sentry: {
+    connectSrc: ['https://*.ingest.sentry.io', 'https://*.sentry.io'],
+  },
+
+  /** YouTube embeds (privacy-enhanced host included). */
+  youtube: {
+    frameSrc: ['https://www.youtube.com', 'https://www.youtube-nocookie.com'],
+    imgSrc: ['https://i.ytimg.com'],
+  },
+
+  /** Vimeo embeds. */
+  vimeo: {
+    frameSrc: ['https://player.vimeo.com'],
+    imgSrc: ['https://i.vimeocdn.com'],
+  },
+} as const satisfies Record<string, CspOrigins>;
+
+/** Name of a vendor preset in {@link CSP_VENDOR_PRESETS}. */
+export type CspVendor = keyof typeof CSP_VENDOR_PRESETS;
+
+/**
+ * Vendors applied to every app unless explicitly disabled.
+ *
+ * Only for origins the DEPLOYMENT PLATFORM injects, which an app therefore
+ * cannot discover by reading its own source. Cloudflare's Web Analytics beacon
+ * is rewritten into the HTML at the edge, after Next.js has already sent the
+ * CSP header — so an opt-in flag here reliably produces a production-only
+ * console error that nobody notices until a user reports it. (Observed
+ * 2026-07-22: all six DjangoCFG-served hosts were violating their own CSP.)
+ *
+ * Do NOT add ordinary third parties here; those belong in `csp.vendors` on the
+ * app that actually uses them, so unrelated apps keep the tighter policy.
+ */
+export const CSP_BASELINE_VENDORS: CspVendor[] = ['cloudflare'];
+
+/**
+ * Merge the named vendor presets into a single set of extra origins.
+ *
+ * Unknown names are ignored rather than thrown on: a typo must not break the
+ * production build of an app whose only mistake was a misspelled analytics
+ * vendor. `warnUnknown` surfaces them on the build log instead.
+ */
+export function resolveCspVendors(
+  vendors: readonly string[] | undefined,
+  warnUnknown = true
+): CspOrigins {
+  const merged: Required<CspOrigins> = {
+    scriptSrc: [],
+    frameSrc: [],
+    connectSrc: [],
+    imgSrc: [],
+    fontSrc: [],
+  };
+
+  if (!vendors?.length) return merged;
+
+  const unknown: string[] = [];
+
+  for (const name of vendors) {
+    const preset = (CSP_VENDOR_PRESETS as Record<string, CspOrigins>)[name];
+    if (!preset) {
+      unknown.push(name);
+      continue;
+    }
+    for (const key of Object.keys(merged) as (keyof Required<CspOrigins>)[]) {
+      const origins = preset[key];
+      if (origins) merged[key].push(...origins);
+    }
+  }
+
+  if (unknown.length && warnUnknown) {
+    const known = Object.keys(CSP_VENDOR_PRESETS).join(', ');
+    console.warn(
+      `[djangocfg] Unknown CSP vendor(s): ${unknown.join(', ')}. Known vendors: ${known}`
+    );
+  }
+
+  // De-duplicate so two presets sharing a host (e.g. GA + GTM both using
+  // googletagmanager.com) don't emit it twice in the header.
+  for (const key of Object.keys(merged) as (keyof Required<CspOrigins>)[]) {
+    merged[key] = [...new Set(merged[key])];
+  }
+
+  return merged;
+}

package/src/config/index.ts

@@ -24,6 +24,15 @@ export {
   DJANGO_CFG_BANNER,
 } from './constants';
 
+// CSP vendor presets — declare third parties by name instead of by origin
+export {
+  CSP_VENDOR_PRESETS,
+  CSP_BASELINE_VENDORS,
+  resolveCspVendors,
+  type CspVendor,
+  type CspOrigins,
+} from './csp';
+
 // Re-export AI constants from ai module
 export {
   MCP_BASE_URL,