create-nextblock 0.11.3 → 0.12.0

package/templates/nextblock-template/components/auth/AuthBotProtection.tsx

@@ -0,0 +1,182 @@
+"use client";
+
+import React, { useEffect, useRef, useState } from 'react';
+import Script from 'next/script';
+
+// Field names must match the server verifier in lib/botProtection/verify.ts.
+const HONEYPOT_FIELD = 'verification_secondary_email';
+const TURNSTILE_TOKEN_FIELD = 'cf-turnstile-response';
+const RECAPTCHA_TOKEN_FIELD = 'g-recaptcha-response';
+
+type BotProtectionProvider = 'none' | 'turnstile' | 'recaptcha';
+
+interface AuthBotProtectionProps {
+  provider: BotProtectionProvider;
+  siteKey: string;
+  scriptNonce?: string;
+}
+
+/**
+ * Drop-in bot protection for auth forms. Renders inside a <form> and contributes:
+ *  - an always-on honeypot field (catches naive bots with zero UX cost), and
+ *  - the site-configured Turnstile / reCAPTCHA widget, writing its token into a
+ *    hidden input so it submits with the surrounding form.
+ *
+ * It never intercepts submit: auth actions redirect on every outcome, so a failed
+ * attempt reloads the page and remounts a fresh widget — no stale single-use tokens.
+ */
+export function AuthBotProtection({ provider, siteKey, scriptNonce }: AuthBotProtectionProps) {
+  const turnstileRef = useRef<HTMLDivElement>(null);
+  const turnstileWidgetIdRef = useRef<string | null>(null);
+  const [turnstileToken, setTurnstileToken] = useState('');
+  const [recaptchaToken, setRecaptchaToken] = useState('');
+
+  const showTurnstile = provider === 'turnstile' && !!siteKey;
+  const showRecaptcha = provider === 'recaptcha' && !!siteKey;
+
+  // Turnstile: explicit managed render. The callback fires once the challenge is
+  // solved (usually automatically) and we stash the token in a hidden input.
+  useEffect(() => {
+    if (!showTurnstile || typeof window === 'undefined') return;
+
+    let widgetId: string | null = null;
+
+    const renderWidget = () => {
+      const turnstile = (window as any).turnstile;
+      if (!turnstile || !turnstileRef.current) return;
+      turnstileRef.current.innerHTML = '';
+      try {
+        widgetId = turnstile.render(turnstileRef.current, {
+          sitekey: siteKey,
+          theme: 'auto',
+          'response-field': false,
+          callback: (token: string) => setTurnstileToken(token),
+          'expired-callback': () => setTurnstileToken(''),
+          'error-callback': () => setTurnstileToken(''),
+          'timeout-callback': () => setTurnstileToken(''),
+        });
+        turnstileWidgetIdRef.current = widgetId;
+      } catch (err) {
+        console.error('Turnstile render error:', err);
+      }
+    };
+
+    if ((window as any).turnstile) {
+      renderWidget();
+    } else {
+      const interval = setInterval(() => {
+        if ((window as any).turnstile) {
+          clearInterval(interval);
+          renderWidget();
+        }
+      }, 100);
+      return () => clearInterval(interval);
+    }
+
+    return () => {
+      const turnstile = (window as any).turnstile;
+      if (widgetId && turnstile) {
+        try {
+          turnstile.remove(widgetId);
+        } catch {
+          // ignore
+        }
+      }
+      turnstileWidgetIdRef.current = null;
+    };
+  }, [showTurnstile, siteKey]);
+
+  // reCAPTCHA v3: invisible + score-based. Fetch a token on load and refresh it
+  // before the ~2min expiry so a token is always waiting when the user submits.
+  useEffect(() => {
+    if (!showRecaptcha || typeof window === 'undefined') return;
+
+    let cancelled = false;
+
+    const execute = () => {
+      const grecaptcha = (window as any).grecaptcha;
+      if (!grecaptcha?.execute) return;
+      grecaptcha.ready(() => {
+        grecaptcha
+          .execute(siteKey, { action: 'signup' })
+          .then((token: string) => {
+            if (!cancelled) setRecaptchaToken(token);
+          })
+          .catch(() => {
+            /* transient; the next refresh retries */
+          });
+      });
+    };
+
+    let readyPoll: ReturnType<typeof setInterval> | null = null;
+    if ((window as any).grecaptcha?.execute) {
+      execute();
+    } else {
+      readyPoll = setInterval(() => {
+        if ((window as any).grecaptcha?.execute) {
+          if (readyPoll) clearInterval(readyPoll);
+          readyPoll = null;
+          execute();
+        }
+      }, 200);
+    }
+
+    const refresh = setInterval(execute, 100_000);
+
+    return () => {
+      cancelled = true;
+      if (readyPoll) clearInterval(readyPoll);
+      clearInterval(refresh);
+    };
+  }, [showRecaptcha, siteKey]);
+
+  return (
+    <>
+      {showRecaptcha && (
+        <Script
+          strategy="lazyOnload"
+          src={`https://www.google.com/recaptcha/api.js?render=${siteKey}`}
+          nonce={scriptNonce}
+        />
+      )}
+      {showTurnstile && (
+        <Script
+          strategy="afterInteractive"
+          src="https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit"
+          nonce={scriptNonce}
+        />
+      )}
+
+      {/* Invisible honeypot: a real user never sees or fills this; bots do. */}
+      <div
+        aria-hidden="true"
+        className="absolute w-0 h-0 overflow-hidden"
+        style={{ position: 'absolute', width: 0, height: 0, overflow: 'hidden', opacity: 0, zIndex: -1 }}
+      >
+        <label htmlFor={HONEYPOT_FIELD} className="sr-only">
+          Do not fill this field
+        </label>
+        <input
+          id={HONEYPOT_FIELD}
+          type="text"
+          name={HONEYPOT_FIELD}
+          tabIndex={-1}
+          autoComplete="off"
+        />
+      </div>
+
+      {showTurnstile && (
+        <div className="my-2 flex justify-start">
+          <input type="hidden" name={TURNSTILE_TOKEN_FIELD} value={turnstileToken} readOnly />
+          <div ref={turnstileRef} />
+        </div>
+      )}
+
+      {showRecaptcha && (
+        <input type="hidden" name={RECAPTCHA_TOKEN_FIELD} value={recaptchaToken} readOnly />
+      )}
+    </>
+  );
+}
+
+export default AuthBotProtection;

package/templates/nextblock-template/docs/04-DATABASE-AND-AUTH.md

@@ -161,19 +161,26 @@ Commerce-specific policy highlights include:
 
 ### Current reality
 
-The current padded migration sequence in
-`libs/db/src/supabase/migrations` runs from:
-
-- `00000000000000`
-- through `00000000000024`
-
-The first files (`00000000000000` through `00000000000016`) are squashed,
-grouped baseline domains. Everything from `00000000000017` onward is an
-append-only forward migration added after the baseline.
-
-These files are already squashed and grouped. Several of them preserve older
-logical migration boundaries through embedded comment headers, so you will see
-historical section numbers inside a smaller set of physical files.
+The folder was **re-baselined in 2026-07**: the previous 45 migrations
+(`00000000000000`–`00000000000044`) were squashed into a four-file idempotent
+baseline, generated from a fresh-apply `pg_dump` by
+`tools/scripts/rebaseline-transform.mjs` and verified byte-identical to the old
+tree. The current sequence is:
+
+- `00000000000000_baseline_schema.sql` — enums, functions, tables, sequences
+  (all `IF NOT EXISTS` / `CREATE OR REPLACE`) plus the re-attached `auth.users`
+  → `handle_new_user` trigger.
+- `00000000000001_baseline_constraints_and_indexes.sql` — primary/unique/check
+  and foreign-key constraints (guarded) plus all indexes.
+- `00000000000002_baseline_security_and_grants.sql` — RLS enablement, policies
+  (`DROP … IF EXISTS` first), triggers, and grants.
+- `00000000000003_baseline_seed.sql` — canonical demo content, `ON CONFLICT DO
+  NOTHING` (no users, no secrets).
+
+Every file is fully idempotent. Existing databases already have versions
+`000`–`003` recorded, so both appliers skip the baseline — it only runs on a
+fresh/empty database. **The next new migration is `00000000000004`**, appended
+forward-only.
 
 ### Production migration policy
 
@@ -188,41 +195,28 @@ production or shared database change.
   that may include orders, users, payments, or customer records.
 - Run `npm run db:migrate:check` before `npm run db:migrate`.
 - If an existing database lists old baseline files such as
-  `00000000000000_setup_foundation_and_enums.sql` as pending, do not replay
-  them. Use `npm run db:migrate:repair-history:check`, then
-  `npm run db:migrate:repair-history`, then rerun
-  `npm run db:migrate:check`.
+  `00000000000000_baseline_schema.sql` as pending, do not replay them. Use
+  `npm run db:migrate:repair-history:check`, then
+  `npm run db:migrate:repair-history --through=00000000000003` (the baseline's
+  top file creates no tables, so auto-detection otherwise stops at `000`), then
+  rerun `npm run db:migrate:check`.
 - Use `npm run db:migrate:fresh` only for a brand-new empty database.
 
 ### Category map
 
 | Migration file | Domain | What it covers |
 | :-- | :-- | :-- |
-| `00000000000000_setup_foundation_and_enums.sql` | Core | Shared enums and schema-level foundation |
-| `00000000000001_setup_cms_core.sql` | Core, CMS | settings, profiles, languages, media, translations, logos |
-| `00000000000002_setup_content_tables.sql` | CMS | pages, posts, blocks, navigation, revisions |
-| `00000000000003_setup_catalog_and_licensing.sql` | Commerce | catalog, variants, inventory cache tables, package activations, Freemius sync tables |
-| `00000000000004_setup_fulfillment_shipping_taxes_and_currencies.sql` | Fulfillment, Commerce | orders, shipping, taxes, currencies, price-map sync functions |
-| `00000000000005_setup_functions_and_triggers.sql` | Core, CMS, Fulfillment | auth/profile bootstrap, timestamps, invoice functions, inventory deduction, product upsert helpers |
-| `00000000000006_setup_rls_and_grants.sql` | Security | grants, RLS enablement, policies |
-| `00000000000007_setup_indexes.sql` | Core, CMS, Commerce | performance indexes across authoring and commerce tables |
-| `00000000000008_seed_platform_defaults.sql` | Seeds | baseline site settings, default languages, default currencies |
-| `00000000000009_seed_translations.sql` | Seeds | translation catalog |
-| `00000000000010_seed_content_scaffold.sql` | Seeds, CMS | starter content, scaffold pages, seeded copy |
-| `00000000000011_setup_cortex_ai_settings.sql` | AI, Settings | Cortex AI settings and provider defaults |
-| `00000000000012_setup_commerce_coupons.sql` | Commerce | coupon tables and related commerce constraints |
-| `00000000000013_setup_cortex_ai_db_mutation_audit.sql` | AI, Audit | Cortex AI database mutation audit support |
-| `00000000000014_setup_content_drafts.sql` | CMS, Editor | visual-editing content draft tables |
-| `00000000000015_setup_product_drafts.sql` | Commerce, Editor | product draft workflow support |
-| `00000000000016_add_feature_image_to_pages.sql` | CMS | optional page feature image media relationship |
-| `00000000000017_add_product_blocks.sql` | Commerce, Editor | block-based product descriptions (`blocks` JSONB column and `product_id` link) |
-| `00000000000018_setup_bot_protection_settings.sql` | CMS, Security | Turnstile/reCAPTCHA bot-protection settings for forms; sensitive site-settings key protection |
-| `00000000000019_add_product_categories.sql` | Commerce | `categories` and `product_categories` junction tables |
-| `00000000000020_add_category_translations.sql` | Commerce, i18n | `name_translations` / `description_translations` on categories |
-| `00000000000021_migrate_hero_blocks_to_sections.sql` | CMS, Editor | data migration converting legacy `hero` blocks into `section` blocks (`is_hero`) |
-| `00000000000022_seed_cortex_ai_guide_post.sql` | Seeds, AI | seeds the Cortex AI guide post |
-| `00000000000023_setup_custom_block_definitions.sql` | CMS, Editor | `custom_block_definitions` registry, validation functions, `duplicate_block_definition` RPC, and RLS (see [10-CUSTOM-BLOCKS.md](./10-CUSTOM-BLOCKS.md)) |
-| `00000000000024_setup_ucp_cart_sessions.sql` | Commerce | `ucp_cart_sessions` table and update trigger for persisted carts |
+| `00000000000000_baseline_schema.sql` | Core, CMS, Commerce | all enums, 40 functions, 49 tables + sequences (idempotent), and the `auth.users` → `handle_new_user` bootstrap trigger |
+| `00000000000001_baseline_constraints_and_indexes.sql` | Core, CMS, Commerce | all primary/unique/check + foreign-key constraints (guarded) and every index |
+| `00000000000002_baseline_security_and_grants.sql` | Security | RLS enablement on every table, all policies, timestamp/business triggers, grants |
+| `00000000000003_baseline_seed.sql` | Seeds | canonical demo content — languages, currencies, site settings, translations, media, pages/posts/blocks, navigation, shipping defaults — all `ON CONFLICT DO NOTHING` |
+
+The pre-2026-07 history (foundation/enums, cms_core, content_tables, catalog,
+fulfillment, functions_and_triggers, rls_and_grants, indexes, the seed files, and
+later additions like custom block definitions, product blocks, categories, cart
+sessions, drafts, privacy/MFA, system alerts, interactions) is all folded into the
+four files above; the earlier per-file boundaries survive only as comment headers
+inside the generated SQL.
 
 ### How to read the folder
 

package/templates/nextblock-template/lib/botProtection/verify.ts

@@ -0,0 +1,134 @@
+// lib/botProtection/verify.ts
+//
+// Shared server-side bot-protection verification: the honeypot check plus
+// Cloudflare Turnstile / Google reCAPTCHA token verification. This is the single
+// source of truth used by BOTH the page contact-form handler
+// (app/actions/formActions.ts) and the account-signup action (app/actions.ts).
+//
+// Server-only: it reads the RLS-bypassing service-role client, which throws if
+// imported into a Client Component.
+
+import { getServiceRoleSupabaseClient } from '@nextblock-cms/db/server';
+
+export type BotProtectionProvider = 'none' | 'turnstile' | 'recaptcha';
+
+// Shared field names — the client widgets emit these, the verifier reads them.
+export const HONEYPOT_FIELD = 'verification_secondary_email';
+export const TURNSTILE_TOKEN_FIELD = 'cf-turnstile-response';
+export const RECAPTCHA_TOKEN_FIELD = 'g-recaptcha-response';
+
+export type BotProtectionResult =
+  // Passed (or nothing configured beyond the honeypot).
+  | { ok: true }
+  // The honeypot was filled — almost certainly a bot. Callers should silently
+  // discard the submission and fake a success so the bot learns nothing.
+  | { ok: false; reason: 'honeypot' }
+  // The captcha was missing, failed, or could not be checked. `message` is a
+  // human-readable explanation safe to surface to the user.
+  | { ok: false; reason: 'captcha'; message: string };
+
+type VerifyOptions = {
+  // A block/form may pin a specific provider; otherwise the site-wide setting
+  // (site_settings.bot_protection_public.provider) is used.
+  botProtectionProvider?: BotProtectionProvider;
+};
+
+/**
+ * Verify a submitted FormData against the configured bot protection.
+ *
+ * Phase 1 (honeypot) needs no network/DB and always runs — it is the always-on
+ * baseline. Phase 2 (captcha) reads the global provider + secret from
+ * `site_settings` and calls the provider's siteverify endpoint.
+ */
+export async function verifyBotProtection(
+  formData: FormData,
+  options?: VerifyOptions
+): Promise<BotProtectionResult> {
+  // Phase 1: Honeypot validation
+  const honeypot = formData.get(HONEYPOT_FIELD);
+  if (honeypot && typeof honeypot === 'string' && honeypot.length > 0) {
+    console.warn('[Bot Protection] Honeypot triggered. Discarding submission from bot.');
+    return { ok: false, reason: 'honeypot' };
+  }
+
+  // Phase 2: Advanced captcha verification
+  try {
+    const supabase = getServiceRoleSupabaseClient();
+
+    const { data: publicSetting } = await supabase
+      .from('site_settings')
+      .select('value')
+      .eq('key', 'bot_protection_public')
+      .maybeSingle();
+
+    const { data: secretSetting } = await supabase
+      .from('site_settings')
+      .select('value')
+      .eq('key', 'bot_protection_secret')
+      .maybeSingle();
+
+    const publicVal = (publicSetting?.value || {}) as Record<string, any>;
+    const secretVal = (secretSetting?.value || {}) as Record<string, any>;
+
+    const pinnedProvider =
+      options?.botProtectionProvider === 'turnstile' || options?.botProtectionProvider === 'recaptcha'
+        ? options.botProtectionProvider
+        : undefined;
+    const provider: BotProtectionProvider = pinnedProvider || publicVal.provider || 'none';
+    const secretKey =
+      secretVal.secretKey ||
+      (provider === 'turnstile'
+        ? process.env.TURNSTILE_SECRET_KEY
+        : process.env.RECAPTCHA_SECRET_KEY) ||
+      '';
+
+    if (provider === 'turnstile') {
+      const token = formData.get(TURNSTILE_TOKEN_FIELD) as string;
+      if (!token) {
+        return { ok: false, reason: 'captcha', message: 'Security verification token is missing. Please try again.' };
+      }
+      if (!secretKey) {
+        console.error('[Bot Protection] Turnstile secret key is not configured.');
+        return { ok: false, reason: 'captcha', message: 'Bot protection is misconfigured. Please contact support.' };
+      }
+
+      const res = await fetch('https://challenges.cloudflare.com/turnstile/v0/siteverify', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: `secret=${encodeURIComponent(secretKey)}&response=${encodeURIComponent(token)}`,
+      });
+
+      const outcome = await res.json();
+      if (!outcome.success) {
+        console.warn('[Bot Protection] Turnstile verification failed:', outcome);
+        return { ok: false, reason: 'captcha', message: 'Security verification failed. Please try again.' };
+      }
+    } else if (provider === 'recaptcha') {
+      const token = formData.get(RECAPTCHA_TOKEN_FIELD) as string;
+      if (!token) {
+        return { ok: false, reason: 'captcha', message: 'Security verification token is missing. Please try again.' };
+      }
+      if (!secretKey) {
+        console.error('[Bot Protection] reCAPTCHA secret key is not configured.');
+        return { ok: false, reason: 'captcha', message: 'Bot protection is misconfigured. Please contact support.' };
+      }
+
+      const res = await fetch('https://www.google.com/recaptcha/api/siteverify', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: `secret=${encodeURIComponent(secretKey)}&response=${encodeURIComponent(token)}`,
+      });
+
+      const outcome = await res.json();
+      if (!outcome.success || outcome.score < 0.5) {
+        console.warn('[Bot Protection] reCAPTCHA verification failed:', outcome);
+        return { ok: false, reason: 'captcha', message: 'Security verification failed. Please try again.' };
+      }
+    }
+  } catch (error) {
+    console.error('[Bot Protection] Error during validation:', error);
+    return { ok: false, reason: 'captcha', message: 'Sorry, security verification could not be completed at this time.' };
+  }
+
+  return { ok: true };
+}

package/templates/nextblock-template/lib/email/branding-format.test.ts

@@ -0,0 +1,133 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  EMAIL_BRAND_HEADER_TOKEN,
+  applyEmailBranding,
+  pickEmailLogoObjectKey,
+  renderEmailBrandHeader,
+} from './branding-format';
+
+describe('renderEmailBrandHeader', () => {
+  it('renders an email-safe logo img capped at width 150 when a logo is set', () => {
+    const html = renderEmailBrandHeader({
+      logoUrl: 'https://cdn.example.com/logo.png',
+      siteName: 'Acme Co',
+    });
+    expect(html).toContain('<img');
+    expect(html).toContain('src="https://cdn.example.com/logo.png"');
+    expect(html).toContain('width="150"');
+    expect(html).toContain('alt="Acme Co"');
+    // width is also pinned in the inline style so clients that ignore the attribute obey it.
+    expect(html).toContain('width:150px');
+  });
+
+  it('falls back to a text banner with the site name and no image when logo is null', () => {
+    const html = renderEmailBrandHeader({ logoUrl: null, siteName: 'Acme Co' });
+    expect(html).not.toContain('<img');
+    expect(html).toContain('Acme Co');
+  });
+
+  it('falls back to the text banner when the logo url is an empty string', () => {
+    const html = renderEmailBrandHeader({ logoUrl: '', siteName: 'Acme Co' });
+    expect(html).not.toContain('<img');
+    expect(html).toContain('Acme Co');
+  });
+
+  it('html-escapes the site name and logo url to prevent attribute/markup breakout', () => {
+    const html = renderEmailBrandHeader({
+      logoUrl: 'https://x.test/a"onerror="alert(1)',
+      siteName: 'A & B "Co" <script>',
+    });
+    expect(html).toContain('A &amp; B &quot;Co&quot; &lt;script&gt;');
+    expect(html).not.toContain('onerror="alert(1)"');
+    expect(html).toContain('&quot;onerror=&quot;');
+  });
+});
+
+describe('applyEmailBranding', () => {
+  it('replaces the brand-header token with the rendered logo header', () => {
+    const out = applyEmailBranding(`<div>${EMAIL_BRAND_HEADER_TOKEN}<p>Hi</p></div>`, {
+      logoUrl: 'https://cdn.example.com/logo.png',
+      siteName: 'Acme Co',
+    });
+    expect(out).not.toContain(EMAIL_BRAND_HEADER_TOKEN);
+    expect(out).toContain('src="https://cdn.example.com/logo.png"');
+    expect(out).toContain('<p>Hi</p>');
+  });
+
+  it('replaces every occurrence of the token', () => {
+    const out = applyEmailBranding(
+      `${EMAIL_BRAND_HEADER_TOKEN}|${EMAIL_BRAND_HEADER_TOKEN}`,
+      { logoUrl: null, siteName: 'Acme Co' },
+    );
+    expect(out).not.toContain(EMAIL_BRAND_HEADER_TOKEN);
+    expect(out.match(/Acme Co/g)?.length).toBe(2);
+  });
+
+  it('defensively swaps a stray hardcoded legacy NextBlock logo img for the tenant header', () => {
+    const legacy =
+      '<img src="https://nextblock.dev/images/nextblock-logo-small.webp" alt="Site logo" width="88" />';
+    const out = applyEmailBranding(`<td>${legacy}</td>`, {
+      logoUrl: 'https://cdn.example.com/logo.png',
+      siteName: 'Acme Co',
+    });
+    expect(out).not.toContain('nextblock-logo-small.webp');
+    expect(out).toContain('src="https://cdn.example.com/logo.png"');
+  });
+
+  it('swaps a stray legacy logo for the text banner when no tenant logo is set', () => {
+    const legacy =
+      '<img src="https://nextblock.dev/images/nextblock-logo-small.webp" alt="Site logo" width="88" />';
+    const out = applyEmailBranding(legacy, { logoUrl: null, siteName: 'Acme Co' });
+    expect(out).not.toContain('<img');
+    expect(out).toContain('Acme Co');
+  });
+
+  it('leaves an unrelated body untouched', () => {
+    const body = '<h2>New Form Submission</h2>';
+    expect(applyEmailBranding(body, { logoUrl: null, siteName: 'Acme Co' })).toBe(body);
+  });
+});
+
+describe('pickEmailLogoObjectKey', () => {
+  it('prefers the original_uploaded variant over the AVIF object_key', () => {
+    const media = {
+      object_key: 'uploads/logo_original.avif',
+      file_path: 'uploads/logo_original.avif',
+      variants: [
+        { objectKey: 'uploads/logo_large.avif', variantLabel: 'large_avif', fileType: 'image/avif' },
+        { objectKey: 'uploads/logo.png', variantLabel: 'original_uploaded', fileType: 'image/png' },
+        { objectKey: 'uploads/logo_original.avif', variantLabel: 'original_avif', fileType: 'image/avif' },
+      ],
+    };
+    expect(pickEmailLogoObjectKey(media)).toBe('uploads/logo.png');
+  });
+
+  it('falls back to object_key when there is no original_uploaded variant (seeded default)', () => {
+    const media = {
+      object_key: 'images/nextblock-logo-small.webp',
+      file_path: null,
+      variants: null,
+    };
+    expect(pickEmailLogoObjectKey(media)).toBe('images/nextblock-logo-small.webp');
+  });
+
+  it('falls back to file_path when object_key is missing', () => {
+    expect(
+      pickEmailLogoObjectKey({ object_key: null, file_path: 'uploads/legacy.png', variants: [] }),
+    ).toBe('uploads/legacy.png');
+  });
+
+  it('ignores an original_uploaded entry with a blank key and falls back', () => {
+    const media = {
+      object_key: 'uploads/logo_original.avif',
+      variants: [{ objectKey: '', variantLabel: 'original_uploaded' }],
+    };
+    expect(pickEmailLogoObjectKey(media)).toBe('uploads/logo_original.avif');
+  });
+
+  it('returns null when there is no media', () => {
+    expect(pickEmailLogoObjectKey(null)).toBeNull();
+    expect(pickEmailLogoObjectKey(undefined)).toBeNull();
+  });
+});

package/templates/nextblock-template/lib/email/branding-format.ts

@@ -0,0 +1,123 @@
+// Pure, dependency-free rendering of the transactional-email brand header. Kept separate
+// from branding.ts (which is `server-only` and hits the DB) so this string logic — the
+// part worth unit-testing — imports nothing server-side and runs anywhere.
+
+// Tenant branding used to white-label every transactional email.
+//   - logoUrl  — an ABSOLUTE, email-safe logo URL, or `null` when none is configured.
+//   - siteName — the site name, used as the logo `alt` text and the no-logo text banner.
+export interface EmailBranding {
+  logoUrl: string | null;
+  siteName: string;
+}
+
+/**
+ * Marker an app-rendered email template drops where the brand header belongs.
+ * `applyEmailBranding` swaps it for the resolved logo (or text banner). This is a plain
+ * literal — NOT a Supabase/GoTrue `{{ .Var }}` merge tag — because it is substituted by
+ * our own nodemailer pipeline, never by Supabase.
+ */
+export const EMAIL_BRAND_HEADER_TOKEN = '{{brand_header}}';
+
+/** Hard width cap so an oversized custom logo can't blow out Gmail/Outlook layouts. */
+export const EMAIL_LOGO_MAX_WIDTH = 150;
+
+// The pre-white-label hardcoded logo. The app templates no longer embed it, but any stray
+// occurrence in an outbound email is swapped for the tenant header defensively.
+const LEGACY_LOGO_IMG_RE =
+  /<img\b[^>]*\bsrc=["'][^"']*nextblock-logo-small\.webp["'][^>]*>/gi;
+
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+/**
+ * Render the branded header block: an email-safe logo `<img>` (hard-capped at 150px so a
+ * large custom logo can't break the layout) when a logo exists, otherwise a clean, styled
+ * text banner showing the site name.
+ */
+export function renderEmailBrandHeader(branding: EmailBranding): string {
+  const name = escapeHtml(branding.siteName);
+
+  if (branding.logoUrl) {
+    const src = escapeHtml(branding.logoUrl);
+    return (
+      '<div style="text-align:center;padding:0 0 24px;">' +
+      `<img src="${src}" alt="${name}" width="${EMAIL_LOGO_MAX_WIDTH}" ` +
+      `style="display:block;margin:0 auto;width:${EMAIL_LOGO_MAX_WIDTH}px;` +
+      'max-width:100%;height:auto;border:0;outline:none;text-decoration:none;" />' +
+      '</div>'
+    );
+  }
+
+  // No logo → strip the image entirely and fall back to a text banner with the site name.
+  return (
+    '<div style="text-align:center;padding:0 0 24px;">' +
+    '<span style="display:inline-block;font-family:-apple-system,BlinkMacSystemFont,' +
+    "'Segoe UI',Roboto,Helvetica,Arial,sans-serif;font-size:22px;line-height:1.2;" +
+    `font-weight:700;color:#0f172a;letter-spacing:-0.01em;">${name}</span>` +
+    '</div>'
+  );
+}
+
+/**
+ * Intercept a fully-rendered email body and apply tenant branding:
+ *   1. Replace the `{{brand_header}}` token (used by our app-rendered templates).
+ *   2. Defensively swap any stray hardcoded legacy NextBlock logo `<img>` for the header.
+ * Purely a string transform so it is trivially unit-testable and side-effect free.
+ */
+export function applyEmailBranding(html: string, branding: EmailBranding): string {
+  const header = renderEmailBrandHeader(branding);
+  let out = html;
+  if (out.includes(EMAIL_BRAND_HEADER_TOKEN)) {
+    out = out.split(EMAIL_BRAND_HEADER_TOKEN).join(header);
+  }
+  out = out.replace(LEGACY_LOGO_IMG_RE, header);
+  return out;
+}
+
+// The `variants` JSONB the upload pipeline writes for a media row (camelCase keys).
+interface MediaVariant {
+  objectKey?: string | null;
+  variantLabel?: string | null;
+  fileType?: string | null;
+}
+
+// The subset of a media row the email logo resolver needs.
+export interface LogoMediaLike {
+  object_key?: string | null;
+  file_path?: string | null;
+  variants?: unknown;
+}
+
+/** Label the upload pipeline gives the untouched original file among a media row's variants. */
+export const ORIGINAL_UPLOAD_VARIANT_LABEL = 'original_uploaded';
+
+/**
+ * Pick the storage key to use for a logo IN EMAIL.
+ *
+ * The image pipeline stores the AVIF derivative as `object_key` — that's what the website
+ * (navbar, blocks) renders for performance — and keeps the ORIGINAL uploaded file among
+ * `variants` under the label `original_uploaded`. Email clients, Outlook especially, can't
+ * render AVIF (or WebP), so for email we prefer that untouched original. Fall back to
+ * `object_key`/`file_path` only when no original variant was kept (e.g. the seeded default
+ * logo, which has no variants). This keeps the site on AVIF while email uses the original.
+ */
+export function pickEmailLogoObjectKey(media: LogoMediaLike | null | undefined): string | null {
+  if (!media) return null;
+  const variants = Array.isArray(media.variants) ? (media.variants as MediaVariant[]) : [];
+  const original = variants.find(
+    (v) =>
+      v &&
+      typeof v === 'object' &&
+      v.variantLabel === ORIGINAL_UPLOAD_VARIANT_LABEL &&
+      typeof v.objectKey === 'string' &&
+      v.objectKey.length > 0,
+  );
+  if (original?.objectKey) return original.objectKey;
+  return media.object_key ?? media.file_path ?? null;
+}