create-nextblock 0.15.8 → 0.15.9

package/templates/nextblock-template/lib/email/placeholder-address.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest';
+
+import { isPlaceholderEmail, usableEmail } from './placeholder-address';
+
+/**
+ * The starter content ships a contact page addressed to `contact@example.com`, and an
+ * install ran that way without knowing: the visitor was thanked, the relay accepted the
+ * message, and it went to a domain RFC 2606 reserves so it can never exist. No error
+ * anywhere. Treating these as unset is what lets the recipient ladder reach something
+ * real — and lets the CMS say so.
+ */
+
+describe('isPlaceholderEmail', () => {
+  it.each([
+    'contact@example.com',
+    'CONTACT@EXAMPLE.COM',
+    '  hello@example.com  ',
+    'privacy@example.org',
+    'support@example.net',
+    'someone@example.edu',
+    'a@host.example',
+    'a@something.invalid',
+    'a@my.test',
+    'a@dev.localhost',
+    'a@printer.local',
+  ])('treats %s as a placeholder', (email) => {
+    expect(isPlaceholderEmail(email)).toBe(true);
+    expect(usableEmail(email)).toBeNull();
+  });
+
+  it.each([
+    'hosts@newrootsherbal.com',
+    'sales@nextblock.dev',
+    // A real domain that merely contains the word, and a real TLD lookalike.
+    'hi@example-company.com',
+    'hi@myexample.com',
+    'hi@shop.exampleshop.co.uk',
+  ])('leaves the real address %s alone', (email) => {
+    expect(isPlaceholderEmail(email)).toBe(false);
+    expect(usableEmail(email)).toBe(email);
+  });
+
+  it('does not treat an empty or malformed value as a placeholder', () => {
+    // Empty means "unset", which callers already handle; malformed is not our call.
+    for (const value of ['', '   ', null, undefined, 'not-an-email']) {
+      expect(isPlaceholderEmail(value)).toBe(false);
+    }
+  });
+
+  it('reports an empty value as unusable without calling it a placeholder', () => {
+    expect(usableEmail('')).toBeNull();
+    expect(usableEmail(null)).toBeNull();
+    expect(usableEmail('  ')).toBeNull();
+  });
+
+  it('trims a usable address rather than returning it padded', () => {
+    expect(usableEmail('  sales@nextblock.dev ')).toBe('sales@nextblock.dev');
+  });
+});

package/templates/nextblock-template/lib/email/placeholder-address.ts

@@ -0,0 +1,39 @@
+/**
+ * Addresses that look configured but can never receive mail.
+ *
+ * Seed data has to put *something* in a contact field, and `contact@example.com` is the
+ * conventional choice. The trouble is that it is indistinguishable from a real setting to
+ * every code path downstream: the form reports success, the transport accepts the
+ * message, and it is delivered nowhere. An operator can run that way for months without
+ * a single error to notice.
+ *
+ * The domains here are reserved by RFC 2606 and RFC 6761 precisely so they can never be
+ * registered, which is what makes this a safe judgement rather than a guess: nothing at
+ * `example.com` is ever a real inbox. Treating them as unset lets the recipient ladder
+ * fall through to something that works, and lets the CMS say so out loud.
+ *
+ * Deliberately dependency-free so both server modules and the CMS can use it.
+ */
+
+const RESERVED_DOMAINS = new Set(['example.com', 'example.org', 'example.net', 'example.edu']);
+const RESERVED_TLDS = ['.example', '.invalid', '.test', '.localhost', '.local'];
+
+export function isPlaceholderEmail(value: string | null | undefined): boolean {
+  const email = value?.trim().toLowerCase() ?? '';
+  if (!email) return false;
+
+  const at = email.lastIndexOf('@');
+  if (at === -1) return false;
+
+  const domain = email.slice(at + 1);
+  if (!domain) return false;
+
+  return RESERVED_DOMAINS.has(domain) || RESERVED_TLDS.some((tld) => domain.endsWith(tld));
+}
+
+/** The address if it could actually receive mail, otherwise null. */
+export function usableEmail(value: string | null | undefined): string | null {
+  const email = value?.trim() ?? '';
+  if (!email || isPlaceholderEmail(email)) return null;
+  return email;
+}

package/templates/nextblock-template/lib/messages/thread-reference.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'vitest';
+
+import { threadReference } from './threads';
+
+/**
+ * A real install stopped receiving replies and nothing reported a fault: SMTP accepted
+ * every message, Outlook accepted every message, and they went straight to Deleted Items.
+ * The cause was the subject. Every conversation from one form produced a byte-identical
+ * "Re: Contact form"; Exchange derives its ConversationTopic from the subject rather than
+ * from References, so an Ignore Conversation applied once applied to every enquiry the
+ * site would ever receive.
+ *
+ * A per-conversation reference is what stops one filtering decision swallowing the lot.
+ */
+
+const THREAD_A = 'f4c00aff-a458-40cb-8f6b-7ec66e98779c';
+const THREAD_B = '34b62e11-8209-4beb-98e9-10b364bd2807';
+
+describe('threadReference', () => {
+  it('is stable for a given thread', () => {
+    expect(threadReference(THREAD_A, 'New Roots Herbal')).toBe(
+      threadReference(THREAD_A, 'New Roots Herbal')
+    );
+  });
+
+  it('differs between threads, which is the entire point', () => {
+    expect(threadReference(THREAD_A, 'New Roots Herbal')).not.toBe(
+      threadReference(THREAD_B, 'New Roots Herbal')
+    );
+  });
+
+  it('reads as a ticket number rather than a hex dump', () => {
+    expect(threadReference(THREAD_A, 'New Roots Herbal')).toBe('NRH-VWQOLB');
+    expect(threadReference(THREAD_A, 'New Roots Herbal')).toMatch(/^[A-Z]{2,4}-[0-9A-Z]{6}$/);
+  });
+
+  it('builds initials from a multi-word site name', () => {
+    expect(threadReference(THREAD_A, 'New Roots Herbal')).toMatch(/^NRH-/);
+    expect(threadReference(THREAD_A, 'The Corner  Shop')).toMatch(/^TCS-/);
+  });
+
+  it('falls back to the first three letters of a one-word name', () => {
+    expect(threadReference(THREAD_A, 'NextBlock')).toMatch(/^NEX-/);
+  });
+
+  it('drops the prefix entirely when there is no usable site name', () => {
+    expect(threadReference(THREAD_A, '')).toBe('VWQOLB');
+    expect(threadReference(THREAD_A, '   ')).toBe('VWQOLB');
+    expect(threadReference(THREAD_A)).toBe('VWQOLB');
+  });
+
+  it('ignores punctuation in the site name rather than emitting it', () => {
+    expect(threadReference(THREAD_A, "Bob's Bikes & Co.")).toMatch(/^BBC-/);
+  });
+
+  it('survives a malformed id instead of throwing', () => {
+    expect(threadReference('', 'New Roots Herbal')).toBe('NRH-000000');
+    expect(threadReference('zzzzzzzz', 'New Roots Herbal')).toBe('NRH-000000');
+  });
+
+  it('keeps distinct conversations apart across a large sample', () => {
+    const seen = new Set<string>();
+    for (let i = 0; i < 2000; i += 1) {
+      seen.add(threadReference(crypto.randomUUID(), 'New Roots Herbal'));
+    }
+    // 2.2 billion references; a handful of collisions in 2000 draws would signal a bug
+    // in the fold, not birthday-paradox noise.
+    expect(seen.size).toBe(2000);
+  });
+});

package/templates/nextblock-template/lib/messages/thread-token.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  THREAD_TOKEN_PREFIX,
+  mintThreadToken,
+  hashThreadToken,
+  parseThreadToken,
+  secondsUntilExpiry,
+  nextExpiry,
+} from './thread-token';
+
+/**
+ * The pure half of the token module — the half that decides whether a value is worth a
+ * database probe at all. Mirrors lib/visual-editing/draft-route.test.ts: test the parse
+ * and normalise logic directly, leave the route handler alone.
+ */
+
+describe('parseThreadToken', () => {
+  it('accepts a freshly minted token', () => {
+    const { token } = mintThreadToken();
+    expect(parseThreadToken(token)).toBe(token);
+  });
+
+  it('trims surrounding whitespace, which a mail client can introduce', () => {
+    const { token } = mintThreadToken();
+    expect(parseThreadToken(`  ${token}\n`)).toBe(token);
+  });
+
+  it.each([
+    ['null', null],
+    ['undefined', undefined],
+    ['empty', ''],
+    ['no prefix', 'abcdefghijklmnopqrstuvwxyz'],
+    ['prefix only', THREAD_TOKEN_PREFIX],
+    ['too short', `${THREAD_TOKEN_PREFIX}abc`],
+    ['wrong prefix', 'nb_abcdefghijklmnopqrstuvwxyz'],
+    ['sql-ish payload', `${THREAD_TOKEN_PREFIX}' OR 1=1 --`],
+    ['path traversal', `${THREAD_TOKEN_PREFIX}../../etc/passwd`],
+    ['non-string', 12345 as unknown as string],
+  ])('rejects %s', (_label, input) => {
+    expect(parseThreadToken(input as string)).toBeNull();
+  });
+});
+
+describe('mintThreadToken', () => {
+  it('never returns the same token twice', () => {
+    const seen = new Set(Array.from({ length: 200 }, () => mintThreadToken().token));
+    expect(seen.size).toBe(200);
+  });
+
+  it('carries enough entropy to make guessing infeasible', () => {
+    const { token } = mintThreadToken();
+    // 32 bytes base64url-encoded is 43 chars, plus the 4-char prefix.
+    expect(token.length).toBeGreaterThanOrEqual(THREAD_TOKEN_PREFIX.length + 43);
+  });
+
+  it('returns the hash of its own token, not the token', () => {
+    const { token, tokenHash } = mintThreadToken();
+    expect(tokenHash).toBe(hashThreadToken(token));
+    expect(tokenHash).not.toContain(token);
+    expect(tokenHash).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  it('expires about 90 days out', () => {
+    const now = new Date('2026-01-01T00:00:00.000Z');
+    const { expiresAt } = mintThreadToken(now);
+    const days = (new Date(expiresAt).getTime() - now.getTime()) / 86_400_000;
+    expect(days).toBeCloseTo(90, 5);
+  });
+});
+
+describe('secondsUntilExpiry', () => {
+  const now = new Date('2026-01-01T00:00:00.000Z');
+
+  it('measures the remaining window', () => {
+    expect(secondsUntilExpiry('2026-01-01T01:00:00.000Z', now)).toBe(3600);
+  });
+
+  it('clamps an already-expired token to zero rather than a negative max-age', () => {
+    expect(secondsUntilExpiry('2025-12-31T00:00:00.000Z', now)).toBe(0);
+  });
+
+  it('treats a missing expiry as expired', () => {
+    expect(secondsUntilExpiry(null, now)).toBe(0);
+  });
+});
+
+describe('nextExpiry', () => {
+  it('extends the window from the given moment', () => {
+    const now = new Date('2026-01-01T00:00:00.000Z');
+    expect(secondsUntilExpiry(nextExpiry(now), now)).toBe(90 * 24 * 60 * 60);
+  });
+});

package/templates/nextblock-template/lib/messages/thread-token.ts

@@ -0,0 +1,157 @@
+import 'server-only';
+
+import { sha256Hex, randomToken } from '../auth/crypto';
+
+/**
+ * The visitor's credential for a private conversation.
+ *
+ * A visitor who sends a product enquiry or a contact-form message has no account, so
+ * there is nothing to authenticate them with. This token is that credential — and it is
+ * the only one in the repo issued to an anonymous person, so its handling is
+ * deliberately conservative:
+ *
+ *  - 32 bytes (256 bits) of `crypto.randomBytes`. Guessing is infeasible by keyspace,
+ *    not by rate limiting, which matters because a GET has no throttle here.
+ *  - Only the SHA-256 hash is stored. The plaintext lives long enough to be placed in
+ *    one outbound email and is never written down.
+ *  - Minted on the FIRST ADMIN REPLY, never at submission. A store that receives a
+ *    hundred enquiries and answers three has three live credentials, not a hundred.
+ *  - Rolling 90-day expiry, extended by each reply, revocable from the CMS.
+ *
+ * The token reaches the site once, in a URL. `/thread/[token]` immediately exchanges it
+ * for an HttpOnly cookie and redirects to a token-less `/thread`, because this app sends
+ * `Referrer-Policy: strict-origin-when-cross-origin` — which means the FULL url travels
+ * in the Referer header on same-origin navigations. A token left in the address bar
+ * would leak to every internal link, into history, and into any shared screenshot.
+ */
+
+export const THREAD_TOKEN_PREFIX = 'nbt_';
+export const THREAD_COOKIE = 'nb_thread';
+
+const THREAD_TOKEN_BYTES = 32;
+const THREAD_TTL_DAYS = 90;
+
+/** Shortest thing worth a database probe. Mirrors the MCP token guard. */
+const MIN_TOKEN_LENGTH = 16;
+
+export interface MintedThreadToken {
+  /** Plaintext. Goes in exactly one email and is never persisted. */
+  token: string;
+  tokenHash: string;
+  expiresAt: string;
+}
+
+export function mintThreadToken(now: Date = new Date()): MintedThreadToken {
+  const token = `${THREAD_TOKEN_PREFIX}${randomToken(THREAD_TOKEN_BYTES)}`;
+  const expiresAt = new Date(now.getTime() + THREAD_TTL_DAYS * 24 * 60 * 60 * 1000);
+  return { token, tokenHash: hashThreadToken(token), expiresAt: expiresAt.toISOString() };
+}
+
+export function hashThreadToken(token: string): string {
+  return sha256Hex(token);
+}
+
+/**
+ * Normalise a token from a URL segment or a cookie. Returns null for anything that
+ * could not be one, so a malformed value never reaches the database.
+ *
+ * Pure and dependency-free on purpose — this half is what the unit tests exercise,
+ * following the draft-route convention.
+ */
+export function parseThreadToken(raw: string | null | undefined): string | null {
+  if (typeof raw !== 'string') return null;
+
+  const token = raw.trim();
+  if (!token.startsWith(THREAD_TOKEN_PREFIX)) return null;
+  if (token.length < MIN_TOKEN_LENGTH) return null;
+  // base64url alphabet plus the prefix; anything else is not one of ours.
+  if (!/^nbt_[A-Za-z0-9_-]+$/.test(token)) return null;
+
+  return token;
+}
+
+/** How long a cookie should live for a token expiring at `expiresAt`. */
+export function secondsUntilExpiry(expiresAt: string | null, now: Date = new Date()): number {
+  if (!expiresAt) return 0;
+  const seconds = Math.floor((new Date(expiresAt).getTime() - now.getTime()) / 1000);
+  return seconds > 0 ? seconds : 0;
+}
+
+/** A fresh expiry, used to extend the window each time the admin replies. */
+export function nextExpiry(now: Date = new Date()): string {
+  return new Date(now.getTime() + THREAD_TTL_DAYS * 24 * 60 * 60 * 1000).toISOString();
+}
+
+export type ThreadTokenFailure = 'malformed' | 'unknown' | 'expired' | 'revoked';
+
+export interface ThreadRow {
+  id: string;
+  source: string;
+  /** Which contact form this conversation began on, so a reply keeps its routing. */
+  form_key: string | null;
+  subject_label: string;
+  sender_name: string | null;
+  sender_email: string | null;
+  status: string;
+  token_expires_at: string | null;
+  token_revoked_at: string | null;
+  unread_for_visitor: boolean;
+}
+
+export type ThreadTokenVerification =
+  | { valid: false; reason: ThreadTokenFailure }
+  | { valid: true; thread: ThreadRow };
+
+interface SupabaseLike {
+  from: (table: string) => any;
+}
+
+/**
+ * Resolve a token to its thread. One indexed equality probe on the hash — there is no
+ * scan-and-compare and therefore no timing oracle to defend against.
+ *
+ * Every failure mode is reported to the caller but NOT to the visitor: the page renders
+ * one generic "this link is no longer valid" message either way, so a probe cannot
+ * distinguish a revoked thread from one that never existed.
+ */
+export async function verifyThreadToken(
+  supabase: SupabaseLike,
+  rawToken: string | null | undefined,
+  now: Date = new Date()
+): Promise<ThreadTokenVerification> {
+  const token = parseThreadToken(rawToken);
+  if (!token) return { valid: false, reason: 'malformed' };
+
+  const { data, error } = await supabase
+    .from('message_threads')
+    .select(
+      'id, source, form_key, subject_label, sender_name, sender_email, status, token_expires_at, token_revoked_at, unread_for_visitor'
+    )
+    .eq('token_hash', hashThreadToken(token))
+    .maybeSingle();
+
+  if (error || !data) return { valid: false, reason: 'unknown' };
+
+  const thread = data as ThreadRow;
+  if (thread.token_revoked_at) return { valid: false, reason: 'revoked' };
+  if (thread.token_expires_at && new Date(thread.token_expires_at).getTime() <= now.getTime()) {
+    return { valid: false, reason: 'expired' };
+  }
+
+  return { valid: true, thread };
+}
+
+/**
+ * Stamp `token_last_used_at`. Fire-and-forget: failed bookkeeping must never fail a
+ * request that already authenticated.
+ */
+export async function touchThreadToken(supabase: SupabaseLike, threadId: string): Promise<void> {
+  try {
+    await supabase
+      .from('message_threads')
+      .update({ token_last_used_at: new Date().toISOString() })
+      .eq('id', threadId);
+  } catch {
+    /* ignore */
+  }
+}