create-nextblock 0.13.7 → 0.13.8

package/templates/nextblock-template/app/cms/settings/security/components/SecurityPanel.tsx

@@ -1,10 +1,13 @@
 'use client';
 
-import { useRef, useState, useTransition } from 'react';
+import { useEffect, useRef, useState, useTransition } from 'react';
+import Link from 'next/link';
 import { useRouter } from 'next/navigation';
+import { MailWarning } from 'lucide-react';
 import {
   Alert,
   AlertDescription,
+  AlertTitle,
   Badge,
   Button,
   Card,
@@ -32,11 +35,19 @@ import {
   updateGlobalSecuritySettings,
   verifyEmailEnrollment,
   verifyTotpEnrollment,
+  type ActionResult,
   type SecurityPanelData,
 } from '../actions';
 
 type EnrollMode = 'idle' | 'totp' | 'email';
 
+/**
+ * How long the resend button stays parked after a successful send. Relays queue for
+ * seconds-to-minutes, and hammering resend is what leaves a user holding several codes
+ * with no idea which to type — they all work now, but the wait is still the real fix.
+ */
+const RESEND_COOLDOWN_SECONDS = 30;
+
 function formatDate(value: string): string {
   try {
     return new Date(value).toLocaleDateString(undefined, {
@@ -60,16 +71,37 @@ export default function SecurityPanel({ data }: { data: SecurityPanelData }) {
   );
   const [emailSent, setEmailSent] = useState(false);
   const [code, setCode] = useState('');
+  const [cooldown, setCooldown] = useState(0);
+  // Server-reported: catches SMTP breaking between page load and the click, when the
+  // server-rendered `data.emailConfigured` is already stale.
+  const [smtpUnavailable, setSmtpUnavailable] = useState(false);
+  const emailAvailable = data.emailConfigured && !smtpUnavailable;
+
+  useEffect(() => {
+    if (cooldown <= 0) return;
+    const timer = setTimeout(() => setCooldown((seconds) => seconds - 1), 1000);
+    return () => clearTimeout(timer);
+  }, [cooldown]);
 
-  const run = (fn: () => Promise<unknown>, after?: () => void) => {
+  /**
+   * Actions report failure by returning it, so a failed one must not run `onSuccess` — a
+   * rejected code has to leave the QR / code entry on screen for another attempt.
+   */
+  const run = (fn: () => Promise<ActionResult>, onSuccess?: () => void) => {
     setMessage(null);
     startTransition(async () => {
       try {
-        const result = (await fn()) as { message?: string } | undefined;
-        if (result?.message) setMessage({ success: result.message });
-        after?.();
+        const result = await fn();
+        if (!result.ok) {
+          if (result.needsSmtp) setSmtpUnavailable(true);
+          setMessage({ error: result.error });
+          return;
+        }
+        setMessage({ success: result.message });
+        onSuccess?.();
         router.refresh();
       } catch (error) {
+        // Transport-level only (the actions themselves no longer throw).
         setMessage({
           error: error instanceof Error ? error.message : 'Something went wrong.',
         });
@@ -109,13 +141,45 @@ export default function SecurityPanel({ data }: { data: SecurityPanelData }) {
     run(() => verifyTotpEnrollment(formData), resetEnrollment);
   };
 
-  const beginEmail = () => {
-    setMode('email');
+  /** Used for both the initial "Secure Email Code" click and the Resend button. */
+  const requestEmailCode = () => {
+    if (!emailAvailable) return;
     setTotp(null);
-    run(async () => {
-      const result = await sendEmailEnrollmentCode();
-      setEmailSent(true);
-      return result;
+    setMessage(null);
+    if (mode !== 'email') {
+      setMode('email');
+      setCode('');
+    }
+
+    if (cooldown > 0) {
+      setMessage({
+        success: `A code is already on its way to ${data.email}. You can request another in ${cooldown}s.`,
+      });
+      return;
+    }
+
+    startTransition(async () => {
+      try {
+        const result = await sendEmailEnrollmentCode();
+        if (result.ok) {
+          setEmailSent(true);
+          setCooldown(RESEND_COOLDOWN_SECONDS);
+          setMessage({ success: result.message });
+          return;
+        }
+        if (result.needsSmtp) setSmtpUnavailable(true);
+        // Never leave the panel stuck on "Sending…" — drop back to the chooser so the
+        // failure and the fix (configure SMTP) are the only things on screen.
+        setEmailSent(false);
+        setMode('idle');
+        setMessage({ error: result.error });
+      } catch (error) {
+        setEmailSent(false);
+        setMode('idle');
+        setMessage({
+          error: error instanceof Error ? error.message : 'Could not send a code.',
+        });
+      }
     });
   };
 
@@ -185,6 +249,8 @@ export default function SecurityPanel({ data }: { data: SecurityPanelData }) {
             </div>
           ) : (
             <div className="space-y-4">
+              {!emailAvailable && <SmtpRequiredNotice isAdmin={data.isAdmin} />}
+
               {/* Method chooser */}
               <div className="grid gap-3 sm:grid-cols-2">
                 <button
@@ -201,14 +267,25 @@ export default function SecurityPanel({ data }: { data: SecurityPanelData }) {
                 </button>
                 <button
                   type="button"
-                  onClick={beginEmail}
-                  className={`rounded-lg border p-4 text-left transition hover:border-primary ${
+                  onClick={requestEmailCode}
+                  disabled={!emailAvailable}
+                  aria-describedby={!emailAvailable ? 'smtp-required-notice' : undefined}
+                  className={`rounded-lg border p-4 text-left transition enabled:hover:border-primary disabled:cursor-not-allowed disabled:opacity-60 ${
                     mode === 'email' ? 'border-primary ring-1 ring-primary' : ''
                   }`}
                 >
-                  <p className="font-medium text-sm">Secure Email Code</p>
+                  <p className="font-medium text-sm">
+                    Secure Email Code
+                    {!emailAvailable && (
+                      <Badge variant="secondary" className="ml-2 align-middle text-[10px]">
+                        Needs SMTP
+                      </Badge>
+                    )}
+                  </p>
                   <p className="text-xs text-slate-500">
-                    Receive a 6-digit code at your account email each time you sign in.
+                    {emailAvailable
+                      ? 'Receive a 6-digit code at your account email each time you sign in.'
+                      : 'Unavailable until an email (SMTP) server is configured for this site.'}
                   </p>
                 </button>
               </div>
@@ -298,16 +375,23 @@ export default function SecurityPanel({ data }: { data: SecurityPanelData }) {
                     </Button>
                     <Button
                       variant="ghost"
-                      onClick={beginEmail}
-                      disabled={isPending}
+                      onClick={requestEmailCode}
+                      disabled={isPending || cooldown > 0}
                       title="Send a new code"
                     >
-                      Resend
+                      {cooldown > 0 ? `Resend in ${cooldown}s` : 'Resend'}
                     </Button>
                     <Button variant="ghost" onClick={resetEnrollment} disabled={isPending}>
                       Cancel
                     </Button>
                   </div>
+                  {emailSent && (
+                    <p className="text-xs text-slate-500">
+                      Delivery depends on your mail provider and can take a minute. If you
+                      request another code, the earlier ones keep working for 5 minutes — enter
+                      whichever arrives first.
+                    </p>
+                  )}
                 </div>
               )}
             </div>
@@ -383,6 +467,38 @@ export default function SecurityPanel({ data }: { data: SecurityPanelData }) {
   );
 }
 
+/**
+ * Shown when no SMTP transport resolves. Without one the email factor is a dead end — the
+ * code is minted and the panel claims success, but nothing is ever delivered — so the tile
+ * is disabled and this points at the fix instead.
+ */
+function SmtpRequiredNotice({ isAdmin }: { isAdmin: boolean }) {
+  return (
+    <Alert variant="warning" id="smtp-required-notice">
+      <MailWarning className="h-4 w-4" />
+      <AlertTitle>Email codes need an SMTP server</AlertTitle>
+      <AlertDescription className="space-y-2">
+        <p>
+          This site has no outgoing mail server configured, so a verification code cannot
+          reach your inbox. Use an authenticator app instead, or set up SMTP first.
+        </p>
+        {isAdmin ? (
+          <Link
+            href="/cms/settings/email"
+            className="inline-flex items-center font-medium underline underline-offset-4"
+          >
+            Configure email (SMTP) →
+          </Link>
+        ) : (
+          <p className="font-medium">
+            Ask an administrator to configure it under Settings → Email.
+          </p>
+        )}
+      </AlertDescription>
+    </Alert>
+  );
+}
+
 function SignupPolicyCard({
   initial,
   isPending,

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

@@ -0,0 +1,254 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const dbServerMocks = vi.hoisted(() => ({
+  createClient: vi.fn(),
+  getServiceRoleSupabaseClient: vi.fn(),
+}));
+
+vi.mock('@nextblock-cms/db/server', () => dbServerMocks);
+vi.mock('./cookies', () => ({
+  TWO_FACTOR_COOKIE: 'nb_2fa',
+  clearCookie: vi.fn(),
+  getCookieValue: vi.fn(),
+  setSecureCookie: vi.fn(),
+}));
+vi.mock('./trustedDevices', () => ({ hasValidTrustedDevice: vi.fn() }));
+vi.mock('../privacy/settings', () => ({ getSecuritySettings: vi.fn() }));
+vi.mock('server-only', () => ({}));
+
+import {
+  createEmailChallenge,
+  getEmailResendCooldownSeconds,
+  hasPendingEmailChallenge,
+  verifyEmailChallenge,
+} from './twoFactor';
+
+type ChallengeRow = {
+  id: string;
+  user_id: string;
+  token_hash: string;
+  expires_at: string;
+  consumed_at: string | null;
+  created_at: string;
+};
+
+/**
+ * Minimal in-memory stand-in for the `email_2fa_challenges` table, supporting exactly the
+ * PostgREST chains twoFactor.ts builds. Rows get strictly increasing `created_at` values so
+ * the "newest N codes" window is deterministic rather than clock-resolution dependent.
+ */
+function createFakeDb() {
+  const rows: ChallengeRow[] = [];
+  let sequence = 0;
+
+  function makeQuery(kind: 'select' | 'update', patch?: Partial<ChallengeRow>) {
+    const filters: Array<(row: ChallengeRow) => boolean> = [];
+    let newestFirst = false;
+    let max = Number.POSITIVE_INFINITY;
+
+    const run = () => {
+      let matched = rows.filter((row) => filters.every((keep) => keep(row)));
+      if (newestFirst) {
+        matched = [...matched].sort((a, b) => b.created_at.localeCompare(a.created_at));
+      }
+      matched = matched.slice(0, max);
+      if (kind === 'update') {
+        matched.forEach((row) => Object.assign(row, patch));
+      }
+      return { data: matched.map((row) => ({ ...row })), error: null };
+    };
+
+    const query = {
+      eq(column: keyof ChallengeRow, value: unknown) {
+        filters.push((row) => row[column] === value);
+        return query;
+      },
+      is(column: keyof ChallengeRow, value: unknown) {
+        filters.push((row) => row[column] === value);
+        return query;
+      },
+      gt(column: keyof ChallengeRow, value: string) {
+        filters.push((row) => String(row[column]) > value);
+        return query;
+      },
+      order(_column: string, options?: { ascending?: boolean }) {
+        newestFirst = options?.ascending === false;
+        return query;
+      },
+      limit(count: number) {
+        max = count;
+        return query;
+      },
+      then<TResult>(
+        onFulfilled: (value: ReturnType<typeof run>) => TResult,
+        onRejected?: (reason: unknown) => TResult,
+      ) {
+        return Promise.resolve(run()).then(onFulfilled, onRejected);
+      },
+    };
+    return query;
+  }
+
+  const client = {
+    from(table: string) {
+      if (table !== 'email_2fa_challenges') {
+        throw new Error(`Unexpected table in test: ${table}`);
+      }
+      return {
+        insert(values: Omit<ChallengeRow, 'id' | 'consumed_at' | 'created_at'>) {
+          sequence += 1;
+          rows.push({
+            id: `row-${sequence}`,
+            consumed_at: null,
+            // Distinct, ordered timestamps regardless of how fast the test runs.
+            created_at: new Date(Date.UTC(2026, 0, 1) + sequence).toISOString(),
+            ...values,
+          });
+          return Promise.resolve({ data: null, error: null });
+        },
+        select: () => makeQuery('select'),
+        update: (patch: Partial<ChallengeRow>) => makeQuery('update', patch),
+      };
+    },
+  };
+
+  return { client, rows };
+}
+
+const USER = 'user-1';
+
+describe('email 2FA challenges', () => {
+  let db: ReturnType<typeof createFakeDb>;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    process.env.NB_2FA_SECRET = 'test-secret';
+    db = createFakeDb();
+    dbServerMocks.getServiceRoleSupabaseClient.mockReturnValue(db.client);
+  });
+
+  it('keeps an earlier code valid after a resend', async () => {
+    // The regression: relays deliver out of order, so the code a user receives first is
+    // often the one requested first. Issuing a new code must not kill it.
+    const first = await createEmailChallenge(USER);
+    const second = await createEmailChallenge(USER);
+    expect(first).not.toBe(second);
+
+    await expect(verifyEmailChallenge(USER, first)).resolves.toBe(true);
+  });
+
+  it('accepts the newest code too', async () => {
+    await createEmailChallenge(USER);
+    const second = await createEmailChallenge(USER);
+
+    await expect(verifyEmailChallenge(USER, second)).resolves.toBe(true);
+  });
+
+  it('burns every live sibling once one code succeeds', async () => {
+    const first = await createEmailChallenge(USER);
+    const second = await createEmailChallenge(USER);
+
+    await expect(verifyEmailChallenge(USER, first)).resolves.toBe(true);
+    // The unused sibling must not stay redeemable after the factor is satisfied.
+    await expect(verifyEmailChallenge(USER, second)).resolves.toBe(false);
+  });
+
+  it('drops the fourth-oldest code out of the usable window', async () => {
+    const oldest = await createEmailChallenge(USER);
+    await createEmailChallenge(USER);
+    await createEmailChallenge(USER);
+    await createEmailChallenge(USER);
+
+    // Unreachable even though its row has not expired — the window caps the guess surface.
+    await expect(verifyEmailChallenge(USER, oldest)).resolves.toBe(false);
+  });
+
+  it('keeps all three in-window codes usable', async () => {
+    await createEmailChallenge(USER);
+    const second = await createEmailChallenge(USER);
+    await createEmailChallenge(USER);
+    await createEmailChallenge(USER);
+
+    // Second-oldest of four is the boundary of the three-code window.
+    await expect(verifyEmailChallenge(USER, second)).resolves.toBe(true);
+  });
+
+  it('rejects expired codes', async () => {
+    const code = await createEmailChallenge(USER);
+    db.rows.forEach((row) => {
+      row.expires_at = new Date(Date.now() - 1000).toISOString();
+    });
+
+    await expect(verifyEmailChallenge(USER, code)).resolves.toBe(false);
+  });
+
+  it('rejects malformed codes without touching the database', async () => {
+    await createEmailChallenge(USER);
+    const fromSpy = vi.spyOn(db.client, 'from');
+
+    await expect(verifyEmailChallenge(USER, 'abc')).resolves.toBe(false);
+    await expect(verifyEmailChallenge(USER, '12345')).resolves.toBe(false);
+    expect(fromSpy).not.toHaveBeenCalled();
+  });
+
+  it('does not leak codes across users', async () => {
+    const code = await createEmailChallenge(USER);
+
+    await expect(verifyEmailChallenge('user-2', code)).resolves.toBe(false);
+    await expect(verifyEmailChallenge(USER, code)).resolves.toBe(true);
+  });
+
+  describe('resend throttle', () => {
+    /** The fake stamps rows at a fixed epoch; move the newest one to a chosen age. */
+    const ageNewestBy = (ms: number) => {
+      const newest = [...db.rows].sort((a, b) => b.created_at.localeCompare(a.created_at))[0];
+      newest.created_at = new Date(Date.now() - ms).toISOString();
+    };
+
+    it('allows the first send', async () => {
+      await expect(getEmailResendCooldownSeconds(USER)).resolves.toBe(0);
+    });
+
+    it('blocks a send immediately after one', async () => {
+      await createEmailChallenge(USER);
+      ageNewestBy(0);
+
+      const wait = await getEmailResendCooldownSeconds(USER);
+      expect(wait).toBeGreaterThan(0);
+      expect(wait).toBeLessThanOrEqual(20);
+    });
+
+    it('allows another send once the window passes', async () => {
+      await createEmailChallenge(USER);
+      ageNewestBy(25_000);
+
+      await expect(getEmailResendCooldownSeconds(USER)).resolves.toBe(0);
+    });
+
+    it('measures time since the last send, not the last live code', async () => {
+      const code = await createEmailChallenge(USER);
+      await verifyEmailChallenge(USER, code); // consumes it
+      ageNewestBy(0);
+
+      // A consumed row still represents an email that just went out.
+      await expect(getEmailResendCooldownSeconds(USER)).resolves.toBeGreaterThan(0);
+    });
+
+    it('throttles per user', async () => {
+      await createEmailChallenge(USER);
+      ageNewestBy(0);
+
+      await expect(getEmailResendCooldownSeconds('user-2')).resolves.toBe(0);
+    });
+  });
+
+  it('reports a pending challenge only while one is live', async () => {
+    await expect(hasPendingEmailChallenge(USER)).resolves.toBe(false);
+
+    const code = await createEmailChallenge(USER);
+    await expect(hasPendingEmailChallenge(USER)).resolves.toBe(true);
+
+    await verifyEmailChallenge(USER, code);
+    await expect(hasPendingEmailChallenge(USER)).resolves.toBe(false);
+  });
+});

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

@@ -16,20 +16,32 @@ const EMAIL_CODE_TTL_MS = 5 * 60 * 1000; // 5 minutes
 const TWO_FACTOR_SESSION_TTL_SECONDS = 12 * 60 * 60; // 12 hours
 
 /**
- * Create and persist a hashed 6-digit email code and return the RAW code so the
- * caller can email it. Prior unconsumed codes for the user are invalidated.
+ * How many of a user's most recent codes stay usable at once.
+ *
+ * Relays (SMTP2GO, SES, …) do not preserve send order and can take minutes to deliver, so
+ * a user who clicks "resend" often receives the ORIGINAL code first. Hard-invalidating on
+ * every request made that first-arriving code fail — the classic "the code you emailed me
+ * doesn't work" loop. Keeping a short window of concurrently valid codes removes the race;
+ * the guess surface stays bounded because only this many are ever checked and all of them
+ * die on first successful use (and after EMAIL_CODE_TTL_MS regardless).
+ */
+const MAX_LIVE_EMAIL_CODES = 3;
+
+/**
+ * Minimum gap between user-requested codes. Deliberately shorter than the UI countdown so a
+ * normal user never sees the server refusal — the client timer is a courtesy that a crafted
+ * request ignores, and this is what actually bounds how fast one session can drive the mailer.
+ */
+const RESEND_COOLDOWN_MS = 20_000;
+
+/**
+ * Create and persist a hashed 6-digit email code and return the RAW code so the caller can
+ * email it. Earlier codes are deliberately left alive — see MAX_LIVE_EMAIL_CODES. Kept to a
+ * single round trip: this sits directly in front of the SMTP handoff on a click path.
  */
 export async function createEmailChallenge(userId: string): Promise<string> {
   const code = generateNumericCode(6);
   const svc = getServiceRoleSupabaseClient();
-  const nowIso = new Date().toISOString();
-
-  // Invalidate any earlier pending codes so only the newest one works.
-  await svc
-    .from('email_2fa_challenges')
-    .update({ consumed_at: nowIso })
-    .eq('user_id', userId)
-    .is('consumed_at', null);
 
   await svc.from('email_2fa_challenges').insert({
     user_id: userId,
@@ -40,6 +52,27 @@ export async function createEmailChallenge(userId: string): Promise<string> {
   return code;
 }
 
+/**
+ * Seconds the caller must wait before another code may be requested, or 0 when a send is
+ * allowed. Considers consumed rows too — this measures time since the last SEND, not since
+ * the last still-usable code.
+ */
+export async function getEmailResendCooldownSeconds(userId: string): Promise<number> {
+  const svc = getServiceRoleSupabaseClient();
+  const { data } = await svc
+    .from('email_2fa_challenges')
+    .select('created_at')
+    .eq('user_id', userId)
+    .order('created_at', { ascending: false })
+    .limit(1);
+
+  const latest = data?.[0]?.created_at;
+  if (!latest) return 0;
+  const elapsed = Date.now() - new Date(latest).getTime();
+  if (!Number.isFinite(elapsed) || elapsed >= RESEND_COOLDOWN_MS) return 0;
+  return Math.ceil((RESEND_COOLDOWN_MS - elapsed) / 1000);
+}
+
 /** True when the user has an unconsumed, unexpired email code awaiting entry. */
 export async function hasPendingEmailChallenge(userId: string): Promise<boolean> {
   const svc = getServiceRoleSupabaseClient();
@@ -53,7 +86,11 @@ export async function hasPendingEmailChallenge(userId: string): Promise<boolean>
   return Boolean(data && data.length > 0);
 }
 
-/** Verify a submitted email code against the newest live challenge. */
+/**
+ * Verify a submitted email code against the user's live challenges. Any of the newest
+ * MAX_LIVE_EMAIL_CODES is accepted, so a code that arrives out of order still works;
+ * anything older than that window is unreachable even though its row lingers until expiry.
+ */
 export async function verifyEmailChallenge(userId: string, code: string): Promise<boolean> {
   const trimmed = (code || '').trim();
   if (!/^\d{6}$/.test(trimmed)) return false;
@@ -67,14 +104,20 @@ export async function verifyEmailChallenge(userId: string, code: string): Promis
     .is('consumed_at', null)
     .gt('expires_at', nowIso)
     .order('created_at', { ascending: false })
-    .limit(5);
+    .limit(MAX_LIVE_EMAIL_CODES);
 
   if (!data || data.length === 0) return false;
   const candidateHash = sha256Hex(trimmed);
   const match = data.find((row) => safeEqual(row.token_hash, candidateHash));
   if (!match) return false;
 
-  await svc.from('email_2fa_challenges').update({ consumed_at: nowIso }).eq('id', match.id);
+  // Burn every live code for this user, not just the matched row: the siblings from a
+  // resend have served their purpose and must not stay redeemable after a success.
+  await svc
+    .from('email_2fa_challenges')
+    .update({ consumed_at: nowIso })
+    .eq('user_id', userId)
+    .is('consumed_at', null);
   return true;
 }
 

package/templates/nextblock-template/lib/cms/action-result.ts

@@ -0,0 +1,12 @@
+/**
+ * Standard result shape for CMS settings server actions.
+ *
+ * Next replaces the message of an uncaught Server Action error with a generic string in
+ * production builds, so anything the operator has to be able to read — a permission
+ * refusal, a relay's rejection, a validation complaint — must come back as data rather
+ * than as a throw. Actions that only ever fail in ways nobody needs to read (pure data
+ * readers rendered by a Server Component) can still throw and hit the error boundary.
+ */
+export type SettingsActionResult =
+  | { ok: true; message: string }
+  | { ok: false; error: string };

package/templates/nextblock-template/lib/config/email-settings.ts

@@ -170,14 +170,46 @@ export async function saveEmailSettings(input: SaveEmailSettingsInput): Promise<
       throw new Error('Failed to save email credentials.');
     }
   }
+
+  // The mailer memoizes the resolved transport config; make the new values live now.
+  invalidateEmailConfigCache();
+}
+
+// Resolving SMTP costs two service-role reads plus an AES decrypt of each secret, and
+// transactional email (2FA codes especially) is latency-sensitive. The values only change
+// when an admin saves the form, so memoize briefly and bust the cache on save.
+const CONFIG_CACHE_TTL_MS = 60_000;
+let configCache: { value: ResolvedEmailConfig | null; expiresAt: number } | null = null;
+
+/** Drop the memoized SMTP config so the next resolve re-reads the DB. */
+export function invalidateEmailConfigCache(): void {
+  configCache = null;
+}
+
+/**
+ * Cheap "can this instance actually send mail right now?" check for UI gating. Never
+ * logs — an unconfigured instance is an expected state here, not an error condition.
+ */
+export async function isEmailConfigured(): Promise<boolean> {
+  return (await resolveEmailServerConfig({ silent: true })) !== null;
 }
 
 /**
  * Resolve the full SMTP transport config, DB-first with an env fallback. Uses the
  * service-role client so it works from any context (the secret row is ADMIN-only under
  * RLS). Returns null when host/user/pass/from cannot be resolved from either source.
+ *
+ * Memoized for CONFIG_CACHE_TTL_MS; pass `silent` when "not configured" is an expected
+ * answer (UI gating) rather than a misconfiguration worth warning about.
  */
-export async function resolveEmailServerConfig(): Promise<ResolvedEmailConfig | null> {
+export async function resolveEmailServerConfig(
+  options: { silent?: boolean } = {},
+): Promise<ResolvedEmailConfig | null> {
+  const cached = configCache;
+  if (cached && cached.expiresAt > Date.now()) {
+    return cached.value;
+  }
+
   let pub: EmailPublicSettings = DEFAULT_EMAIL_PUBLIC_SETTINGS;
   let secret: Record<string, unknown> = {};
 
@@ -201,12 +233,15 @@ export async function resolveEmailServerConfig(): Promise<ResolvedEmailConfig |
   const pass = resolveConfigValue(tryDecryptWithEnvKey(secret['pass']), 'SMTP_PASS');
 
   if (!host || !port || !user || !pass || !fromEmail) {
-    console.warn('Email is not configured (CMS or SMTP_* env). Outbound email will not be sent.');
+    if (!options.silent) {
+      console.warn('Email is not configured (CMS or SMTP_* env). Outbound email will not be sent.');
+    }
+    configCache = { value: null, expiresAt: Date.now() + CONFIG_CACHE_TTL_MS };
     return null;
   }
 
   const portNumber = Number(port);
-  return {
+  const resolved: ResolvedEmailConfig = {
     host,
     port: portNumber,
     // Honor the CMS toggle; fall back to the SMTPS convention (465 ⇒ implicit TLS).
@@ -214,4 +249,6 @@ export async function resolveEmailServerConfig(): Promise<ResolvedEmailConfig |
     auth: { user, pass },
     from: fromName ? `"${fromName}" <${fromEmail}>` : fromEmail,
   };
+  configCache = { value: resolved, expiresAt: Date.now() + CONFIG_CACHE_TTL_MS };
+  return resolved;
 }

package/templates/nextblock-template/next-env.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
-import "./.next/dev/types/routes.d.ts";
+import "./.next/types/routes.d.ts";
 
 // NOTE: This file should not be edited
 // see https://nextjs.org/docs/app/api-reference/config/typescript for more information.