create-nextblock 0.10.2 → 0.10.3

package/templates/nextblock-template/components/DeferredGoogleAnalytics.tsx

@@ -0,0 +1,70 @@
+"use client";
+
+import { useEffect, useState, type ComponentType } from "react";
+
+interface DeferredGoogleAnalyticsProps {
+  gaId?: string;
+  nonce?: string;
+}
+
+const interactionEvents: Array<keyof WindowEventMap> = [
+  "pointerdown",
+  "keydown",
+  "scroll",
+  "touchstart",
+];
+
+type GoogleAnalyticsComponent = ComponentType<{
+  gaId: string;
+  nonce?: string;
+}>;
+
+export function DeferredGoogleAnalytics({
+  gaId,
+  nonce,
+}: DeferredGoogleAnalyticsProps) {
+  const [GoogleAnalytics, setGoogleAnalytics] =
+    useState<GoogleAnalyticsComponent | null>(null);
+
+  useEffect(() => {
+    if (!gaId) {
+      return;
+    }
+
+    let isMounted = true;
+
+    function removeListeners() {
+      interactionEvents.forEach((eventName) => {
+        window.removeEventListener(eventName, enableGa);
+      });
+    }
+
+    function enableGa() {
+      removeListeners();
+
+      void import("@next/third-parties/google").then(({ GoogleAnalytics }) => {
+        if (isMounted) {
+          setGoogleAnalytics(() => GoogleAnalytics as GoogleAnalyticsComponent);
+        }
+      });
+    }
+
+    interactionEvents.forEach((eventName) => {
+      window.addEventListener(eventName, enableGa, {
+        once: true,
+        passive: true,
+      });
+    });
+
+    return () => {
+      isMounted = false;
+      removeListeners();
+    };
+  }, [gaId]);
+
+  if (!gaId || !GoogleAnalytics) {
+    return null;
+  }
+
+  return <GoogleAnalytics gaId={gaId} nonce={nonce} />;
+}

package/templates/nextblock-template/components/blocks/renderers/TextBlockRenderer.tsx

@@ -2,17 +2,18 @@ import React from "react";
 import { headers } from 'next/headers';
 import ClientTextBlockRenderer from "./ClientTextBlockRenderer";
 import type { VisualEditAttributes } from "../../../lib/visual-editing/types";
+import { substitutePrivacyMergeTags } from "../../../lib/privacy/contact-emails";
 
 export type TextBlockContent = {
     html_content?: string;
 };
 
-interface TextBlockRendererProps {
-  content: TextBlockContent;
-  languageId: number;
-  visualEditAttributes?: VisualEditAttributes;
-  renderContext?: 'prose' | 'section';
-}
+interface TextBlockRendererProps {
+  content: TextBlockContent;
+  languageId: number;
+  visualEditAttributes?: VisualEditAttributes;
+  renderContext?: 'prose' | 'section';
+}
 
 function addNonceToInlineScripts(html: string, nonce: string): string {
   if (!html || !nonce) return html || '';
@@ -24,23 +25,27 @@ function addNonceToInlineScripts(html: string, nonce: string): string {
 }
 
 const TextBlockRenderer: React.FC<TextBlockRendererProps> = async ({
-  content,
-  languageId,
-  visualEditAttributes,
-  renderContext = 'prose',
-}) => {
+  content,
+  languageId,
+  visualEditAttributes,
+  renderContext = 'prose',
+}) => {
   const hdrs = await headers();
   const nonce = hdrs.get('x-nonce') || '';
-  const htmlWithNonce = content.html_content ? addNonceToInlineScripts(content.html_content, nonce) : '';
+  let html = content.html_content || '';
+  if (html.includes('{{')) {
+    html = await substitutePrivacyMergeTags(html);
+  }
+  const htmlWithNonce = html ? addNonceToInlineScripts(html, nonce) : '';
   const patchedContent = { ...content, html_content: htmlWithNonce };
   return (
-    <ClientTextBlockRenderer
-      content={patchedContent}
-      languageId={languageId}
-      visualEditAttributes={visualEditAttributes}
-      renderContext={renderContext}
-    />
-  );
-};
+    <ClientTextBlockRenderer
+      content={patchedContent}
+      languageId={languageId}
+      visualEditAttributes={visualEditAttributes}
+      renderContext={renderContext}
+    />
+  );
+};
 
 export default TextBlockRenderer;

package/templates/nextblock-template/components/privacy/ConsentGatedAnalytics.tsx

@@ -5,10 +5,12 @@
 // shows zero analytics bytes, preserving the Lighthouse budget.
 import { useEffect, useRef, useState } from 'react';
 import { DeferredGoogleTagManager } from '../DeferredGoogleTagManager';
+import { DeferredGoogleAnalytics } from '../DeferredGoogleAnalytics';
 import { CONSENT_CHANGE_EVENT, readConsent } from '../../lib/privacy/consent-client';
 
 interface ConsentGatedAnalyticsProps {
   gtmId?: string;
+  gaMeasurementId?: string;
   customScripts?: string;
   nonce?: string;
 }
@@ -29,6 +31,7 @@ function injectCustomScripts(markup: string, nonce?: string) {
 
 export function ConsentGatedAnalytics({
   gtmId,
+  gaMeasurementId,
   customScripts,
   nonce,
 }: ConsentGatedAnalyticsProps) {
@@ -54,6 +57,14 @@ export function ConsentGatedAnalytics({
     }
   }, [analyticsAllowed, customScripts, nonce]);
 
-  if (!analyticsAllowed || !gtmId) return null;
-  return <DeferredGoogleTagManager gtmId={gtmId} nonce={nonce} />;
+  if (!analyticsAllowed) return null;
+  if (!gtmId && !gaMeasurementId) return null;
+  return (
+    <>
+      {gtmId && <DeferredGoogleTagManager gtmId={gtmId} nonce={nonce} />}
+      {gaMeasurementId && (
+        <DeferredGoogleAnalytics gaId={gaMeasurementId} nonce={nonce} />
+      )}
+    </>
+  );
 }

package/templates/nextblock-template/docs/05-DEVELOPER-GUIDE.md

@@ -109,6 +109,17 @@ repo expects at least:
 - `CRON_SECRET`, `DRAFT_MODE_SECRET`, `REVALIDATE_SECRET_TOKEN` — auto-generated
   by `npm run setup`
 
+> **Supabase key aliases.** The names above are the local-dev canon, but the app also
+> accepts the *new-style* names the hosted/Vercel Supabase Marketplace integration
+> injects: `SUPABASE_URL` (non-prefixed), `SUPABASE_PUBLISHABLE_KEY` /
+> `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY` (anon-equivalent), and `SUPABASE_SECRET_KEY`
+> (service-role-equivalent). Resolution lives in `apps/nextblock/lib/setup/env-status.ts`
+> (`resolveSupabaseUrl` / `resolveSupabaseAnonKey` / `resolveSupabaseServiceKey`); read
+> Supabase env through those (or the same inline alias chain in published libs) rather
+> than a single raw name. `DRAFT_MODE_SECRET` / `REVALIDATE_SECRET_TOKEN` are optional in
+> production — when unset they are derived from the service-role key (see
+> `apps/nextblock/lib/app-secrets.ts`). See [12-VERCEL-DEPLOYMENT.md](./12-VERCEL-DEPLOYMENT.md).
+
 Captured by `npm run setup` and needed for a complete CMS:
 
 - R2 credentials for media storage. The app builds and serves without them, but

package/templates/nextblock-template/docs/06-CLI-AND-SCAFFOLDING.md

@@ -115,11 +115,62 @@ package activation state.
 
 ## Publishing and Release Notes
 
-Inside the monorepo, CLI release work is still tied to the source workspace:
-
-- library builds and publishes happen from the workspace
-- template sync happens before CLI packaging
-- the CLI package itself is versioned in `apps/create-nextblock/package.json`
-
-If a generated project looks stale, check the sync script and template output
-before assuming the source app is missing the feature.
+A generated project installs the libraries from **npm**, so a feature only reaches
+scaffolds after the libs are republished. (The monorepo's own Vercel deploy builds the
+libs from source, so it sees changes immediately — only `npm create` scaffolds need a
+republish.)
+
+### Release commands
+
+- `npm run release:all -- <version>` — build **and publish every package** at one
+  synchronized version, in dependency order: `utils → ui → sdk → db → editor → ecom`,
+  then `release-cli.js` (which stamps the root + template + `create-nextblock`, re-syncs
+  the template, and publishes the CLI). Pass an explicit semver (e.g. `0.10.2`);
+  `--dry-run` prints the plan only.
+- `npm run build:<lib>` (`build:utils|ui|db|editor|sdk|ecom`) and
+  `node tools/scripts/release-lib.js <lib> <version>` — build + publish a **single** lib
+  (`<lib>` is the nx project name, so use `ecommerce`, which maps to the published
+  `@nextblock-cms/ecom`). `npx nx build <lib>` only *compiles*, it does not publish.
+
+### npm 2FA / OTP (and capturing a log)
+
+Publishing requires a one-time password if the npm account has 2FA. **Piping the command
+output breaks the interactive OTP prompt** — `npm run release:all -- … 2>&1 | Tee-Object …`
+(or `| tee`) fails with `npm error code EOTP` because npm no longer has a TTY. Either:
+
+- set an npm **Automation** token (`npm config set //registry.npmjs.org/:_authToken …`),
+  which bypasses 2FA — then piping to a log file is fine; or
+- capture with PowerShell `Start-Transcript -Path release.log; npm run release:all -- … ;
+  Stop-Transcript`, which records the session while npm keeps its terminal.
+
+`release:all` has no "already published" guard: if it dies partway, re-running the same
+version re-publishes from the top and 403s on the first already-published lib. Finish a
+partial release by running the **remaining** libs individually
+(`node tools/scripts/release-lib.js <lib> <version>` … then `release-cli.js <version>`),
+or bump to a fresh version and re-run the whole thing.
+
+### Library build gotchas (dts / tsconfig)
+
+Each lib emits its `.d.ts` via `vite-plugin-dts` running tsc on `tsconfig.lib.json`. When a
+lib imports a sibling (`ui`/`db` import `utils`; `ecom` imports all), how you wire the
+tsconfig decides whether the build log is clean:
+
+- A **composite** lib (`ui`, `db` — `db` inherits it) must **list the imported sibling's
+  sources in `include`** (e.g. `"../utils/src/**/*.ts"`) and keep `"references": []`.
+  Mirror `libs/editor`, which always built clean this way. A composite project
+  `reference` to the sibling triggers `TS6305` ("output not built" — vite never produces
+  the `tsc -b` out-tsc output); empty `references` *without* the `include` triggers
+  `TS6307` ("file not listed"). Both are non-fatal log noise but should stay at zero.
+- A **non-composite** lib (`ecom`, which extends `tsconfig.base.json`) just needs
+  `"references": []` — no `include` of siblings.
+- A **strict** lib (`db`/`sdk` set `noPropertyAccessFromIndexSignature`) compiles the
+  sibling's *source* under its strict rules, so `libs/utils` must stay strict-clean
+  (bracket-access undeclared keys, e.g. `process.env['R2_BUCKET_NAME']`).
+
+`vite-plugin-dts` `entryRoot: 'src'` keeps emission to the lib's own `src`, so listing
+sibling sources does **not** leak their `.d.ts` into the tarball. The published `bin` path
+in `apps/create-nextblock/package.json` should have **no leading `./`** (`bin/…`, not
+`./bin/…`) or npm "auto-corrects" it with a publish warning.
+
+If a generated project looks stale, check the sync script and template output (and whether
+the libs were actually republished) before assuming the source app is missing the feature.

package/templates/nextblock-template/docs/README.md

@@ -17,6 +17,7 @@ library surfaces rather than historical planning notes.
 - Live draft (visual editing) mode: [09-LIVE-DRAFT-MODE.md](./09-LIVE-DRAFT-MODE.md)
 - Custom blocks (data-driven CRUD): [10-CUSTOM-BLOCKS.md](./10-CUSTOM-BLOCKS.md)
 - Self-hosted local Docker stack: [11-SELF-HOSTED-DOCKER.md](./11-SELF-HOSTED-DOCKER.md)
+- One-click cloud deploy (Deploy to Vercel): [12-VERCEL-DEPLOYMENT.md](./12-VERCEL-DEPLOYMENT.md)
 
 ## Audience Guide
 
@@ -26,7 +27,9 @@ library surfaces rather than historical planning notes.
 - Custom block work: read `03`, then `10`.
 - AI / Cortex work: read `08`.
 - CLI or template work: read `06`.
+- Publishing the libraries / scaffold CLI: read `06`.
 - Running everything locally without cloud accounts: read `11`.
+- One-click cloud deploy and the browser setup wizard: read `12`.
 - AI agents: start with this index, then move directly to the subsystem file that
   matches the task. Treat `apps/nextblock`, `libs/*`, and
   `libs/db/src/supabase/migrations` as the final authority if a doc and code ever

package/templates/nextblock-template/docs/TECHNICAL_SPECIFICATION.md

@@ -2207,7 +2207,7 @@ Both endpoints enforce `Authorization: Bearer ${CRON_SECRET}` per the security m
 
 ### 3.4.8 Google Tag Manager — Analytics Delivery
 
-Google Tag Manager is loaded via `@next/third-parties` (`^16.1.1`) using the `NEXT_PUBLIC_GTM_ID` environment variable. The production CSP allowlist emitted by `apps/nextblock/proxy.ts` explicitly includes `googletagmanager.com`, `google-analytics.com`, and `analytics.google.com` per F-011's origin allowlist.
+Google Tag Manager is loaded via `@next/third-parties` (`^16.1.1`) using the GTM container id configured in the CMS at **Settings → Privacy** and stored in the `site_settings` table (`privacy_settings.gtm_id`); there is no `NEXT_PUBLIC_GTM_ID` environment variable. The id is read in the root layout via `getPrivacySettings()` and passed through the consent gate, so the tag loads only after the visitor accepts analytics. The production CSP allowlist emitted by `apps/nextblock/proxy.ts` explicitly includes `googletagmanager.com`, `google-analytics.com`, and `analytics.google.com` per F-011's origin allowlist.
 
 ## 3.5 DATABASES AND STORAGE
 
@@ -4192,7 +4192,7 @@ The integration landscape comprises eight external domains declared in `libs/env
 | Frankfurter FX | HTTPS (JSON) | Cron runs 18:00 UTC daily; `maxDuration: 30s` |
 | SMTP | SMTP + TLS | Best-effort from server actions |
 | Vercel Cron | HTTPS + Bearer `CRON_SECRET` | 03:00 UTC (reset-sandbox, 60s); 18:00 UTC (sync-currencies, 30s) |
-| Google Tag Manager | HTTPS (JS) | `NEXT_PUBLIC_GTM_ID`; allowlisted in CSP |
+| Google Tag Manager | HTTPS (JS) | GTM id from `privacy_settings` (site_settings); allowlisted in CSP |
 
 ## 5.2 COMPONENT DETAILS
 
@@ -7135,7 +7135,6 @@ Freemius has the broadest environment surface, reflecting the mixture of store-s
 |:--|:--|
 | `CRON_SECRET` | Bearer token for all `/api/cron/*` endpoints |
 | `REVALIDATE_SECRET_TOKEN` | Header token for `/api/revalidate` |
-| `NEXT_PUBLIC_GTM_ID` | Google Tag Manager container ID |
 
 ##### 6.3.4.4.7 Optional Overrides
 
@@ -7369,7 +7368,7 @@ Per Section 5.1.4.2, each external integration carries explicit SLA-like propert
 | Frankfurter | HTTPS (JSON) | Cron daily 18:00 UTC; `maxDuration: 30s` |
 | SMTP | SMTP + TLS | Best-effort from server actions |
 | Vercel Cron | HTTPS + Bearer CRON_SECRET | 03:00 UTC (reset-sandbox 60s); 18:00 UTC (sync-currencies 30s) |
-| Google Tag Manager | HTTPS (JS) | `NEXT_PUBLIC_GTM_ID`; allowlisted in CSP |
+| Google Tag Manager | HTTPS (JS) | GTM id from `privacy_settings` (site_settings); allowlisted in CSP |
 
 #### 6.3.6.2 Known Integration Limitations
 
@@ -8324,7 +8323,7 @@ The `@vercel/speed-insights ^1.3.1` package is declared in the root `package.jso
 
 ##### 6.5.2.1.2 Google Tag Manager and Client-Side Analytics
 
-Google Tag Manager is integrated via `@next/third-parties` and the `<GoogleTagManager gtmId={process.env.NEXT_PUBLIC_GTM_ID || ''} nonce={nonce} />` component, also mounted in the root layout. Configuration is environment-driven via `NEXT_PUBLIC_GTM_ID`; when the variable is not set, the tag is rendered with an empty `gtmId` and effectively disabled. The CSP allowlists `googletagmanager.com`, `google-analytics.com`, `analytics.google.com`, and `*.googletagmanager.com` origins for `script-src`, `img-src`, and `connect-src`, so analytics delivery operates without breaking the nonce policy.
+Google Tag Manager is integrated via `@next/third-parties`, wrapped by `ConsentGatedAnalytics` → `DeferredGoogleTagManager` and mounted in the root layout. The container id is database-driven: the layout resolves `const resolvedGtmId = privacySettings.gtm_id || ''` from `getPrivacySettings()` (the `privacy_settings` row of `site_settings`, edited at **Settings → Privacy**) — there is no `NEXT_PUBLIC_GTM_ID` env fallback. When the id is empty, no GTM chunk is imported; when set, the tag still loads only after the visitor consents to analytics and after the first interaction event. The CSP allowlists `googletagmanager.com`, `google-analytics.com`, `analytics.google.com`, and `*.googletagmanager.com` origins for `script-src`, `img-src`, and `connect-src`, so analytics delivery operates without breaking the nonce policy.
 
 ##### 6.5.2.1.3 Declared-but-Unused @vercel/analytics
 
@@ -8393,7 +8392,7 @@ The primary alert pathway is the **Feedback System** implemented by `FeedbackMod
 
 ##### 6.5.2.4.2 Configuration-Discovery Alerts
 
-The CMS dashboard at `/cms/dashboard/page.tsx` reads `process.env.NEXT_PUBLIC_GTM_ID` during render and conditionally displays a destructive `<Alert>` banner when GTM is unconfigured (suppressed when explicitly set to the string `'false'`). This is a CMS-admin-facing configuration alert — not a runtime monitoring alert — designed to catch missing telemetry configuration during deployment.
+The CMS dashboard at `/cms/dashboard/page.tsx` calls `getPrivacySettings()` during render and conditionally displays a destructive `<Alert>` banner (linking to **Settings → Privacy**) when no GTM container id is configured in the `privacy_settings` row. This is a CMS-admin-facing configuration alert — not a runtime monitoring alert — designed to catch missing telemetry configuration after deployment.
 
 ##### 6.5.2.4.3 Platform-Managed Alerts
 
@@ -8441,7 +8440,7 @@ flowchart TB
         end
 
         subgraph ConfigAlert["Configuration Banner"]
-            GtmBanner{{NEXT_PUBLIC_GTM_ID not set?<br/>Show destructive Alert}}
+            GtmBanner{{privacy_settings.gtm_id not set?<br/>Show destructive Alert}}
         end
 
         GtmBanner --> MetricRow
@@ -8896,7 +8895,7 @@ The following observability gaps are acknowledged and documented for honest stak
 - `apps/nextblock/app/providers.tsx` — Client provider composition order
 - `libs/ecommerce/src/lib/stripe/webhooks.ts` — Stripe webhook handler with `[Stripe Webhook Error]` prefix; `console.error` on missing `STRIPE_WEBHOOK_SECRET` and on `constructEvent` failure
 - `libs/db/src/lib/package-validation.ts` — License gate with `console.error` and 60-second `unstable_cache` tagged `'package-activation'`
-- `libs/environment.d.ts` — `NodeJS.ProcessEnv` augmentation declaring all telemetry and external-service env vars (`NEXT_PUBLIC_GTM_ID`, `NEXT_PUBLIC_IS_SANDBOX`, `REVALIDATE_SECRET_TOKEN`, `CRON_SECRET`, SMTP vars)
+- `libs/environment.d.ts` — `NodeJS.ProcessEnv` augmentation declaring external-service env vars (Supabase, R2/S3, SMTP, Freemius, OpenRouter/Cortex AI). GTM is no longer env-configured — it lives in `privacy_settings`.
 - `vercel.json` — Two cron schedule declarations: `0 3 * * *` reset-sandbox (60s) and `0 18 * * *` sync-currencies (30s)
 - `package.json` (root) — Dependency declarations including `@vercel/speed-insights ^1.3.1` and `@next/third-parties ^16.1.1`
 - `apps/nextblock/package.json` — Template-level dependency declarations including `@vercel/analytics ^1.6.1` (declared but not imported)
@@ -10423,7 +10422,7 @@ graph TB
 
     subgraph Telemetry["Observability Sinks"]
         SpeedIns[(Vercel Speed Insights<br/>LCP · INP · CLS · TTFB)]
-        GTM[(Google Tag Manager<br/>NEXT_PUBLIC_GTM_ID)]
+        GTM[(Google Tag Manager<br/>privacy_settings.gtm_id)]
         VercelLogs[(Vercel Log Stream<br/>warn + error preserved)]
         FeedbackInbox[(feedback@nextblock.ca<br/>SMTP inbox)]
     end
@@ -10541,7 +10540,7 @@ Runtime configuration is **exclusively environment-variable driven**, consumed t
 
 | Category | Variable Count | Examples |
 |:--|:--|:--|
-| Platform | 4 | `NEXT_PUBLIC_URL`, `TARGET_URL`, `NEXT_PUBLIC_IS_SANDBOX`, `NEXT_PUBLIC_GTM_ID` |
+| Platform | 3 | `NEXT_PUBLIC_URL`, `TARGET_URL`, `NEXT_PUBLIC_IS_SANDBOX` |
 | Secrets / Auth | 3 | `CRON_SECRET`, `REVALIDATE_SECRET_TOKEN`, `LHCI_GITHUB_APP_TOKEN` |
 | FX | 1 | `FX_API_BASE_URL` (defaults to `https://api.frankfurter.dev`) |
 | Supabase | 6 | `SUPABASE_PROJECT_ID`, `POSTGRES_URL`, `NEXT_PUBLIC_SUPABASE_URL`, `NEXT_PUBLIC_SUPABASE_ANON_KEY`, `SUPABASE_SERVICE_ROLE_KEY`, `SUPABASE_ACCESS_TOKEN` |
@@ -10723,7 +10722,7 @@ Eight external service integrations are declared across the workspace:
 | Frankfurter FX | native `fetch` | N/A (`api.frankfurter.dev`) | Best-effort (skipped currency telemetry) |
 | SMTP | `nodemailer` | `^7.0.10` | Best-effort degrade |
 | Vercel Speed Insights | `@vercel/speed-insights` | `^1.3.1` | Observational |
-| Google Tag Manager | `@next/third-parties` | `^16.1.1` / `1.1.1` | Observational (disabled if `NEXT_PUBLIC_GTM_ID` unset) |
+| Google Tag Manager | `@next/third-parties` | `^16.1.1` / `1.1.1` | Observational (disabled if `privacy_settings.gtm_id` unset) |
 
 ### 8.3.3 High Availability Design
 
@@ -11380,7 +11379,7 @@ graph TB
 
     subgraph InternalDash["In-App Dashboards"]
         CmsDash[/cms/dashboard<br/>Live counts via Supabase]
-        GtmBanner[GTM Config Banner<br/>when NEXT_PUBLIC_GTM_ID unset]
+        GtmBanner[GTM Config Banner<br/>when privacy_settings.gtm_id unset]
     end
 
     SpeedInsClient --> SpeedDash
@@ -11690,7 +11689,6 @@ The following table enumerates environment variables declared in the `NodeJS.Pro
 | `SMTP_FROM_NAME` | SMTP | From-name for transactional mail |
 | `NEXT_PUBLIC_URL` | Platform | Canonical application base URL |
 | `NEXT_PUBLIC_IS_SANDBOX` | Platform | Enables sandbox banner and demo behaviors |
-| `NEXT_PUBLIC_GTM_ID` | Platform | Google Tag Manager container ID |
 | `CRON_SECRET` | Platform | Bearer token authenticating cron endpoints |
 | `REVALIDATE_SECRET_TOKEN` | Platform | Validates on-demand revalidation requests |
 | `FX_API_BASE_URL` | Platform | Frankfurter FX API base URL override |

package/templates/nextblock-template/lib/auth/twoFactor.ts

@@ -10,6 +10,7 @@ import {
   setSecureCookie,
 } from './cookies';
 import { hasValidTrustedDevice } from './trustedDevices';
+import { getSecuritySettings } from '../privacy/settings';
 
 const EMAIL_CODE_TTL_MS = 5 * 60 * 1000; // 5 minutes
 const TWO_FACTOR_SESSION_TTL_SECONDS = 12 * 60 * 60; // 12 hours
@@ -117,6 +118,46 @@ export interface TwoFactorEvaluation {
   mfaType: 'totp' | 'email' | null;
 }
 
+/**
+ * Whether to surface the "set up two-factor authentication" reminder banner to the
+ * currently signed-in staff user. True only when: not in sandbox, the user is an
+ * ADMIN/WRITER, the global "encourage staff to enable 2FA" policy is on, and the user
+ * has not enrolled a second factor. Best-effort — any failure resolves to no banner.
+ */
+export async function getStaffTwoFactorReminder(): Promise<boolean> {
+  // Sandbox runs on a shared demo account; never nag it (the page is disabled there too).
+  if (process.env.NEXT_PUBLIC_IS_SANDBOX === 'true') return false;
+
+  try {
+    const supabase = createClient();
+    const {
+      data: { user },
+    } = await supabase.auth.getUser();
+    if (!user) return false;
+
+    const { data: profile } = await supabase
+      .from('profiles')
+      .select('role')
+      .eq('id', user.id)
+      .maybeSingle();
+    const role = profile?.role;
+    if (role !== 'ADMIN' && role !== 'WRITER') return false;
+
+    const { enforce_staff_2fa } = await getSecuritySettings();
+    if (!enforce_staff_2fa) return false;
+
+    const { data: settings } = await supabase
+      .from('user_security_settings')
+      .select('mfa_enabled, mfa_type')
+      .eq('user_id', user.id)
+      .maybeSingle();
+
+    return !(settings?.mfa_enabled && settings?.mfa_type);
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Decide whether the currently signed-in user still owes a second factor.
  * Used both to route sign-in and to guard /cms server-side.