create-nextblock 0.16.1 → 0.16.3

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

@@ -1,70 +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);
-  });
-});
+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

@@ -1,93 +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);
-  });
-});
+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

@@ -1,157 +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 */
-  }
-}
+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 */
+  }
+}