@anthusai/papyrus 2.0.0-next.41 → 2.0.0-next.43

package/lib/newsletter-api.ts

@@ -0,0 +1,391 @@
+import { isIP } from "node:net";
+import { NextResponse, type NextRequest } from "next/server";
+import { readAmplifyOutputsFile } from "./amplify-outputs-path";
+import {
+  PREFERENCES_PATH,
+  confirmPromptPage,
+  confirmedPage,
+  deleteConfirmPage,
+  deletedPage,
+  expiredPage,
+  invalidManagePage,
+  pageResponse,
+  pageTheme,
+  preferencesHref,
+  preferencesPage,
+  unavailablePage,
+  unsubscribePromptPage,
+  unsubscribedPage,
+  type PageContent,
+  type PreferenceList,
+} from "./newsletter-pages";
+import { PROSPECTUS_SESSION_COOKIE, loadProspectusSessionSealingSecret } from "./prospectus-session";
+import { signedInProspectusSession } from "./prospectus-sign-in-routes";
+import { readerSubject } from "./reader-subject";
+import { SiteOriginNotConfiguredError, publicSiteOrigin, publicSiteUrl, siteOriginNotConfiguredResponse } from "./site-origin";
+
+export const NEWSLETTER_FUNCTION_ENV = "PAPYRUS_NEWSLETTER_FUNCTION";
+export const NEWSLETTER_SUBSCRIBE_MAXIMUM_BODY_BYTES = 8192;
+export const NEWSLETTER_CONFIRM_MAXIMUM_BODY_BYTES = 4096;
+export const NEWSLETTER_USER_AGENT_CHARACTERS = 300;
+export const NEWSLETTER_TOKEN = /^[A-Za-z0-9._-]{1,2048}$/;
+const MAXIMUM_LISTS = 20;
+const LIST_ID = /^[a-z][a-z0-9-]{0,39}$/;
+
+export type NewsletterEvent = { action: string } & Record<string, unknown>;
+export interface NewsletterResult {
+  statusCode: number;
+  body: Record<string, unknown>;
+}
+export type NewsletterInvoker = (functionName: string, event: NewsletterEvent) => Promise<NewsletterResult>;
+
+export interface NewsletterApiOptions {
+  environment?: Record<string, string | undefined>;
+  invoke?: NewsletterInvoker;
+  /** The parsed `amplify_outputs.json`; read from disk when absent. */
+  outputs?: Record<string, unknown> | null;
+  loadSealingSecret?: () => Promise<string | null>;
+  nowInSeconds?: number;
+}
+
+const NO_STORE = { "cache-control": "no-store" };
+
+function failure(status: number, error: string, message: string): NextResponse {
+  return NextResponse.json({ error, message }, { status, headers: NO_STORE });
+}
+
+export async function invokeNewsletterLambda(functionName: string, event: NewsletterEvent): Promise<NewsletterResult> {
+  const { InvokeCommand, LambdaClient } = await import("@aws-sdk/client-lambda");
+  const response = await new LambdaClient({}).send(
+    new InvokeCommand({ FunctionName: functionName, InvocationType: "RequestResponse", Payload: Buffer.from(JSON.stringify(event)) }),
+  );
+  if (response.FunctionError || !response.Payload) throw new Error("newsletter failed");
+  const result = JSON.parse(Buffer.from(response.Payload).toString("utf8")) as Partial<NewsletterResult>;
+  if (typeof result.statusCode !== "number" || typeof result.body !== "object" || result.body === null) {
+    throw new Error("newsletter returned an unexpected shape");
+  }
+  return { statusCode: result.statusCode, body: result.body as Record<string, unknown> };
+}
+
+type Enabled = { settings: Record<string, unknown>; functionName: string | null };
+
+function enabledPlugin(options: NewsletterApiOptions, environment: Record<string, string | undefined>): Enabled | null {
+  let outputs: Record<string, unknown> | null;
+  try {
+    outputs = options.outputs !== undefined ? options.outputs : readAmplifyOutputsFile();
+  } catch {
+    return null;
+  }
+  const custom = (outputs as { custom?: { papyrusPlugins?: Record<string, unknown>; newsletter?: { actionsFunction?: unknown } } } | null)?.custom;
+  const settings = custom?.papyrusPlugins?.newsletter;
+  if (typeof settings !== "object" || settings === null) return null;
+  const fromEnvironment = (environment[NEWSLETTER_FUNCTION_ENV] ?? "").trim();
+  const fromOutputs = custom?.newsletter?.actionsFunction;
+  const functionName = fromEnvironment || (typeof fromOutputs === "string" && fromOutputs.trim() ? fromOutputs.trim() : null);
+  return { settings: settings as Record<string, unknown>, functionName };
+}
+
+function notFoundJson(): NextResponse {
+  return failure(404, "not_found", "Not found.");
+}
+
+function notFoundPage(): NextResponse {
+  return new NextResponse("Not found", { status: 404, headers: { ...NO_STORE, "content-type": "text/plain; charset=utf-8" } });
+}
+
+/** The visitor's address from CloudFront's `ip:port` header (IPv6 may be bracketed), else the first x-forwarded-for entry. */
+export function clientAddress(headers: Pick<Headers, "get">): string {
+  const viewer = (headers.get("cloudfront-viewer-address") ?? "").trim();
+  if (viewer) {
+    let candidate: string;
+    if (viewer.startsWith("[")) candidate = viewer.slice(1, Math.max(viewer.indexOf("]"), 1));
+    else if (isIP(viewer) === 4) candidate = viewer;
+    else candidate = viewer.slice(0, Math.max(viewer.lastIndexOf(":"), 0));
+    if (isIP(candidate)) return candidate;
+  }
+  const forwarded = (headers.get("x-forwarded-for") ?? "").split(",")[0]?.trim() ?? "";
+  return isIP(forwarded) ? forwarded : "unknown";
+}
+
+async function readBody(request: NextRequest, maximum: number, contentTypes: string[] | null): Promise<{ text: string } | { response: NextResponse }> {
+  const contentType = (request.headers.get("content-type") ?? "").split(";")[0].trim().toLowerCase();
+  if (contentTypes !== null && !contentTypes.includes(contentType)) return { response: failure(415, "unsupported_media_type", `Send ${(contentTypes ?? []).join(" or ")}.`) };
+  const declared = Number(request.headers.get("content-length") ?? "0");
+  if (Number.isFinite(declared) && declared > maximum) return { response: failure(413, "payload_too_large", "The request body is too large.") };
+  const text = await request.text();
+  if (Buffer.byteLength(text, "utf8") > maximum) return { response: failure(413, "payload_too_large", "The request body is too large.") };
+  return { text };
+}
+
+function listIds(raw: unknown): string[] {
+  const entries = typeof raw === "string" ? raw.slice(0, 1000).split(",") : Array.isArray(raw) ? raw : [];
+  return entries
+    .filter((entry): entry is string => typeof entry === "string")
+    .map((entry) => entry.trim())
+    .filter((entry) => LIST_ID.test(entry))
+    .slice(0, MAXIMUM_LISTS);
+}
+
+function limited(value: unknown, maximum: number): string {
+  return typeof value === "string" ? value.slice(0, maximum) : "";
+}
+
+/** The reader's pairwise site subject when they happen to be signed in; never required, never logged, never an error. */
+async function optionalSiteSubject(request: NextRequest, options: NewsletterApiOptions, environment: Record<string, string | undefined>): Promise<string | undefined> {
+  if (!request.cookies.has(PROSPECTUS_SESSION_COOKIE)) return undefined;
+  try {
+    const sealingSecret = await (options.loadSealingSecret ?? (() => loadProspectusSessionSealingSecret({ environment })))();
+    if (!sealingSecret) return undefined;
+    const session = signedInProspectusSession(request, sealingSecret, options.nowInSeconds);
+    return readerSubject(session, environment) ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function siteOriginOrResponse(request: NextRequest, environment: Record<string, string | undefined>): { origin: string } | { response: NextResponse } {
+  try {
+    return { origin: publicSiteOrigin(request, environment) };
+  } catch (error) {
+    if (error instanceof SiteOriginNotConfiguredError) return { response: siteOriginNotConfiguredResponse(error) };
+    throw error;
+  }
+}
+
+/** POST /api/newsletter/subscribe */
+export async function handleNewsletterSubscribe(request: NextRequest, options: NewsletterApiOptions = {}): Promise<NextResponse> {
+  const environment = options.environment ?? process.env;
+  const plugin = enabledPlugin(options, environment);
+  if (!plugin) return notFoundJson();
+  const site = siteOriginOrResponse(request, environment);
+  if ("response" in site) return site.response;
+  if (request.headers.get("origin") !== site.origin) return failure(403, "origin_mismatch", "This request did not come from this site.");
+  const body = await readBody(request, NEWSLETTER_SUBSCRIBE_MAXIMUM_BODY_BYTES, ["application/json"]);
+  if ("response" in body) return body.response;
+  let payload: Record<string, unknown>;
+  try {
+    const parsed = JSON.parse(body.text) as unknown;
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error("not an object");
+    payload = parsed as Record<string, unknown>;
+  } catch {
+    return failure(400, "invalid_json", "The request body is not a JSON object.");
+  }
+  if (!plugin.functionName) return failure(503, "newsletter_unavailable", "Newsletter signup is not available right now.");
+
+  const siteSubject = await optionalSiteSubject(request, options, environment);
+  const event: NewsletterEvent = {
+    action: "subscribe",
+    email: limited(payload.email, 320),
+    lists: listIds(payload.lists),
+    page: limited(payload.page, 500),
+    consent: limited(payload.consent, 500),
+    formId: limited(payload.formId, 100),
+    honeypot: limited(payload.website, 200),
+    renderedAt: typeof payload.renderedAt === "number" || typeof payload.renderedAt === "string" ? payload.renderedAt : null,
+    ip: clientAddress(request.headers),
+    userAgent: limited(request.headers.get("user-agent"), NEWSLETTER_USER_AGENT_CHARACTERS),
+    ...(siteSubject ? { siteSubject } : {}),
+  };
+  try {
+    const result = await (options.invoke ?? invokeNewsletterLambda)(plugin.functionName, event);
+    const status = typeof result.body.status === "string" ? result.body.status : "error";
+    return NextResponse.json({ status }, { status: result.statusCode, headers: NO_STORE });
+  } catch (error) {
+    console.error(`Newsletter subscribe failed (${error instanceof Error ? error.name : "error"}).`);
+    return failure(502, "newsletter_unavailable", "Newsletter signup could not be reached.");
+  }
+}
+
+function pageBase(plugin: Enabled): Pick<PageContent, "siteName" | "theme"> {
+  const fromName = plugin.settings.fromName;
+  return { siteName: typeof fromName === "string" && fromName ? fromName : "this site", theme: pageTheme(plugin.settings.theme) };
+}
+
+function configuredListNames(plugin: Enabled, ids: string[]): string[] {
+  const known = Array.isArray(plugin.settings.lists) ? (plugin.settings.lists as Array<{ id?: unknown; name?: unknown }>) : [];
+  return ids.flatMap((id) => {
+    const match = known.find((entry) => entry.id === id);
+    return typeof match?.name === "string" ? [match.name] : [];
+  });
+}
+
+/** GET /api/newsletter/confirm?t=... shows the confirm button and never changes state; ?done=1&l=... shows the result. */
+export async function handleNewsletterConfirmPage(request: NextRequest, options: NewsletterApiOptions = {}): Promise<NextResponse> {
+  const environment = options.environment ?? process.env;
+  const plugin = enabledPlugin(options, environment);
+  if (!plugin) return notFoundPage();
+  const base = pageBase(plugin);
+  const params = request.nextUrl.searchParams;
+  if (params.get("done") === "1") {
+    const manage = params.get("m") ?? "";
+    return pageResponse(
+      confirmedPage(base, configuredListNames(plugin, listIds(params.get("l") ?? "")), NEWSLETTER_TOKEN.test(manage) ? preferencesHref(manage) : undefined),
+    );
+  }
+  const token = params.get("t") ?? "";
+  if (!NEWSLETTER_TOKEN.test(token)) return pageResponse(expiredPage(base), 410);
+  if (!plugin.functionName) return pageResponse(unavailablePage(base), 503);
+  try {
+    const result = await (options.invoke ?? invokeNewsletterLambda)(plugin.functionName, { action: "confirm_page_state", token });
+    if (result.body.status !== "ready") return pageResponse(expiredPage(base), 410);
+    const lists = Array.isArray(result.body.lists) ? (result.body.lists as Array<{ name?: unknown }>) : [];
+    const names = lists.flatMap((entry) => (typeof entry.name === "string" ? [entry.name] : []));
+    return pageResponse(confirmPromptPage(base, names, token));
+  } catch (error) {
+    console.error(`Newsletter confirm page failed (${error instanceof Error ? error.name : "error"}).`);
+    return pageResponse(unavailablePage(base), 502);
+  }
+}
+
+/** POST /api/newsletter/confirm (form field `t`) confirms, then redirects with 303 to the result page. */
+export async function handleNewsletterConfirmPost(request: NextRequest, options: NewsletterApiOptions = {}): Promise<NextResponse> {
+  const environment = options.environment ?? process.env;
+  const plugin = enabledPlugin(options, environment);
+  if (!plugin) return notFoundPage();
+  const base = pageBase(plugin);
+  const site = siteOriginOrResponse(request, environment);
+  if ("response" in site) return site.response;
+  if (request.headers.get("origin") !== site.origin) return failure(403, "origin_mismatch", "This request did not come from this site.");
+  const body = await readBody(request, NEWSLETTER_CONFIRM_MAXIMUM_BODY_BYTES, ["application/x-www-form-urlencoded"]);
+  if ("response" in body) return body.response;
+  const token = new URLSearchParams(body.text).get("t") ?? "";
+  if (!NEWSLETTER_TOKEN.test(token)) return pageResponse(expiredPage(base), 410);
+  if (!plugin.functionName) return pageResponse(unavailablePage(base), 503);
+  try {
+    const result = await (options.invoke ?? invokeNewsletterLambda)(plugin.functionName, {
+      action: "confirm",
+      token,
+      ip: clientAddress(request.headers),
+      userAgent: limited(request.headers.get("user-agent"), NEWSLETTER_USER_AGENT_CHARACTERS),
+    });
+    if (result.body.status !== "confirmed") return pageResponse(expiredPage(base), 410);
+    const lists = Array.isArray(result.body.lists) ? (result.body.lists as Array<{ id?: unknown }>) : [];
+    const ids = lists.flatMap((entry) => (typeof entry.id === "string" && LIST_ID.test(entry.id) ? [entry.id] : []));
+    const manage = typeof result.body.manageToken === "string" && NEWSLETTER_TOKEN.test(result.body.manageToken) ? result.body.manageToken : "";
+    const target = publicSiteUrl(
+      `/api/newsletter/confirm?done=1&l=${encodeURIComponent(ids.join(","))}${manage ? `&m=${encodeURIComponent(manage)}` : ""}`,
+      request,
+      environment,
+    );
+    return NextResponse.redirect(target, { status: 303, headers: { ...NO_STORE, "referrer-policy": "no-referrer" } });
+  } catch (error) {
+    console.error(`Newsletter confirm failed (${error instanceof Error ? error.name : "error"}).`);
+    return pageResponse(unavailablePage(base), 502);
+  }
+}
+
+function call(options: NewsletterApiOptions, functionName: string, event: NewsletterEvent): Promise<NewsletterResult> {
+  return (options.invoke ?? invokeNewsletterLambda)(functionName, event);
+}
+
+function textResponse(body: string, status: number): NextResponse {
+  return new NextResponse(body, { status, headers: { ...NO_STORE, "content-type": "text/plain; charset=utf-8" } });
+}
+
+function manageTokenFrom(...values: Array<string | null>): string {
+  const found = values.find((value) => value !== null && value !== "") ?? "";
+  return NEWSLETTER_TOKEN.test(found) ? found : "";
+}
+
+function listParameter(value: string | null): string {
+  return value !== null && LIST_ID.test(value) ? value : "";
+}
+
+/**
+ * /api/newsletter/unsubscribe. GET shows a page with a button and changes nothing. POST unsubscribes and is idempotent.
+ * RFC 8058 one-click: mail providers POST `List-Unsubscribe=One-Click` to the link in the message from their own
+ * servers, with no Origin, so this route has no same-origin check. A POST must carry that marker or `page=1` from our own page.
+ */
+export async function handleNewsletterUnsubscribe(request: NextRequest, options: NewsletterApiOptions = {}): Promise<NextResponse> {
+  const environment = options.environment ?? process.env;
+  const plugin = enabledPlugin(options, environment);
+  if (!plugin) return notFoundPage();
+  const base = pageBase(plugin);
+  const query = request.nextUrl.searchParams;
+  if (request.method === "GET") {
+    const token = manageTokenFrom(query.get("t"));
+    if (!token) return pageResponse(invalidManagePage(base), 400);
+    const listId = listParameter(query.get("l"));
+    const listName = listId ? configuredListNames(plugin, [listId])[0] ?? null : null;
+    return pageResponse(unsubscribePromptPage(base, token, listName ? listId : null, listName));
+  }
+  const body = await readBody(request, NEWSLETTER_CONFIRM_MAXIMUM_BODY_BYTES, null);
+  if ("response" in body) return body.response;
+  const form = new URLSearchParams(body.text);
+  const oneClick = form.get("List-Unsubscribe") === "One-Click";
+  const fromPage = form.get("page") === "1";
+  if (!oneClick && !fromPage) return textResponse("Send List-Unsubscribe=One-Click.", 400);
+  const token = manageTokenFrom(query.get("t"), form.get("t"));
+  const listId = listParameter(query.get("l") ?? form.get("l"));
+  const rejected = () => (fromPage ? pageResponse(invalidManagePage(base), 400) : textResponse("Invalid link.", 400));
+  if (!token) return rejected();
+  if (!plugin.functionName) return fromPage ? pageResponse(unavailablePage(base), 503) : textResponse("Unavailable.", 503);
+  try {
+    const result = await call(options, plugin.functionName, { action: "unsubscribe", token, ...(listId ? { list: listId } : {}) });
+    if (result.body.status !== "unsubscribed") return rejected();
+    if (!fromPage) return textResponse("Unsubscribed.", 200);
+    const lists = Array.isArray(result.body.lists) ? (result.body.lists as Array<{ name?: unknown }>) : [];
+    const names = lists.flatMap((entry) => (typeof entry.name === "string" ? [entry.name] : []));
+    return pageResponse(unsubscribedPage(base, names, token));
+  } catch (error) {
+    console.error(`Newsletter unsubscribe failed (${error instanceof Error ? error.name : "error"}).`);
+    return fromPage ? pageResponse(unavailablePage(base), 502) : textResponse("Try again later.", 502);
+  }
+}
+
+const PREFERENCE_NOTICES: Record<string, string> = { saved: "Your preferences are saved.", unsubscribed: "You are unsubscribed from everything." };
+
+/** /api/newsletter/preferences: GET shows the lists; POST (same-origin form) saves, unsubscribes from everything, or deletes after a confirm step. */
+export async function handleNewsletterPreferences(request: NextRequest, options: NewsletterApiOptions = {}): Promise<NextResponse> {
+  const environment = options.environment ?? process.env;
+  const plugin = enabledPlugin(options, environment);
+  if (!plugin) return notFoundPage();
+  const base = pageBase(plugin);
+  if (request.method === "GET") {
+    const token = manageTokenFrom(request.nextUrl.searchParams.get("t"));
+    if (!token) return pageResponse(invalidManagePage(base), 400);
+    if (!plugin.functionName) return pageResponse(unavailablePage(base), 503);
+    try {
+      const result = await call(options, plugin.functionName, { action: "preferences_state", token });
+      if (result.body.status !== "ready") return pageResponse(invalidManagePage(base), 400);
+      const lists = (Array.isArray(result.body.lists) ? result.body.lists : []) as PreferenceList[];
+      const email = typeof result.body.email === "string" ? result.body.email : "";
+      const notice = PREFERENCE_NOTICES[request.nextUrl.searchParams.get("msg") ?? ""];
+      return pageResponse(preferencesPage(base, { token, email, notice, lists: lists.map(({ id, name, description, subscribed }) => ({ id, name, description, subscribed })) }));
+    } catch (error) {
+      console.error(`Newsletter preferences failed (${error instanceof Error ? error.name : "error"}).`);
+      return pageResponse(unavailablePage(base), 502);
+    }
+  }
+  const site = siteOriginOrResponse(request, environment);
+  if ("response" in site) return site.response;
+  if (request.headers.get("origin") !== site.origin) return failure(403, "origin_mismatch", "This request did not come from this site.");
+  const body = await readBody(request, NEWSLETTER_CONFIRM_MAXIMUM_BODY_BYTES, ["application/x-www-form-urlencoded"]);
+  if ("response" in body) return body.response;
+  const form = new URLSearchParams(body.text);
+  const token = manageTokenFrom(form.get("t"));
+  if (!token) return pageResponse(invalidManagePage(base), 400);
+  if (!plugin.functionName) return pageResponse(unavailablePage(base), 503);
+  const action = form.get("action");
+  if (action === "delete" && form.get("confirm") !== "1") return pageResponse(deleteConfirmPage(base, token));
+  const operation =
+    action === "save"
+      ? { action: "update_preferences", token, lists: form.getAll("l").slice(0, MAXIMUM_LISTS).filter((id) => LIST_ID.test(id)) }
+      : action === "unsubscribe_all"
+        ? { action: "unsubscribe", token }
+        : action === "delete"
+          ? { action: "delete_subscriber", token }
+          : null;
+  if (!operation) return failure(400, "invalid_action", "Choose save, unsubscribe from everything, or delete.");
+  try {
+    const result = await call(options, plugin.functionName, operation);
+    const status = result.body.status;
+    if (status === "deleted") return pageResponse(deletedPage(base));
+    if (status !== "saved" && status !== "unsubscribed") return pageResponse(invalidManagePage(base), 400);
+    const target = publicSiteUrl(`${PREFERENCES_PATH}?t=${encodeURIComponent(token)}&msg=${status}`, request, environment);
+    return NextResponse.redirect(target, { status: 303, headers: { ...NO_STORE, "referrer-policy": "no-referrer" } });
+  } catch (error) {
+    console.error(`Newsletter preferences save failed (${error instanceof Error ? error.name : "error"}).`);
+    return pageResponse(unavailablePage(base), 502);
+  }
+}

package/lib/newsletter-pages.ts

@@ -0,0 +1,264 @@
+import { NextResponse } from "next/server";
+
+/**
+ * The small server-rendered pages of the newsletter plugin (confirm prompt, confirmed, expired).
+ * Plain HTML, no scripts, themed from the plugin's public settings. Every dynamic value is escaped, the token never
+ * reaches a link, and the pages are never cached or indexed.
+ */
+export type NewsletterPageTheme = { accent: string; text: string; background: string; surface: string; muted: string; fontFamily: string };
+
+export const DEFAULT_PAGE_THEME: NewsletterPageTheme = {
+  accent: "#1a4d8f",
+  text: "#1b1b1b",
+  background: "#ffffff",
+  surface: "#f4f4f4",
+  muted: "#555555",
+  fontFamily: "Georgia, 'Times New Roman', serif",
+};
+
+const UNSAFE_CSS = /[<>{};"\\`]|url\(|expression\(|@import/i;
+const MAXIMUM_LISTS_SHOWN = 20;
+
+export function escapeHtml(value: string): string {
+  return value.replace(/[&<>"']/g, (character) => `&#${character.charCodeAt(0)};`);
+}
+
+/** Theme tokens from `custom.papyrusPlugins.newsletter.theme`; a missing or unsafe value falls back to the default. */
+export function pageTheme(raw: unknown): NewsletterPageTheme {
+  const theme: NewsletterPageTheme = { ...DEFAULT_PAGE_THEME };
+  if (typeof raw !== "object" || raw === null) return theme;
+  for (const key of Object.keys(theme) as Array<keyof NewsletterPageTheme>) {
+    const value = (raw as Record<string, unknown>)[key];
+    if (typeof value === "string" && value.length > 0 && value.length <= 200 && !UNSAFE_CSS.test(value)) theme[key] = value;
+  }
+  return theme;
+}
+
+export type FormSpec = {
+  action: string;
+  /** Hidden fields, such as the token. */
+  hidden: Record<string, string>;
+  checkboxes?: Array<{ name: string; value: string; label: string; checked: boolean }>;
+  /** Every button says what it does in words. `secondary` only changes how it looks. */
+  buttons: Array<{ label: string; name?: string; value?: string; secondary?: boolean }>;
+};
+
+export type PageContent = {
+  siteName: string;
+  theme: NewsletterPageTheme;
+  heading: string;
+  /** A short status line shown above the text (for example "Saved"), as words. */
+  notice?: string;
+  paragraphs: string[];
+  lists?: string[];
+  forms?: FormSpec[];
+  links?: Array<{ href: string; label: string }>;
+};
+
+function renderForm(form: FormSpec): string {
+  const hidden = Object.entries(form.hidden)
+    .map(([name, value]) => `<input type="hidden" name="${escapeHtml(name)}" value="${escapeHtml(value)}">`)
+    .join("");
+  const boxes = (form.checkboxes ?? [])
+    .map(
+      (box, index) =>
+        `<p class="box"><input type="checkbox" id="c${index}" name="${escapeHtml(box.name)}" value="${escapeHtml(box.value)}"${box.checked ? " checked" : ""}> <label for="c${index}">${escapeHtml(box.label)}</label></p>`,
+    )
+    .join("");
+  const buttons = form.buttons
+    .map(
+      (button) =>
+        `<button type="submit"${button.name ? ` name="${escapeHtml(button.name)}" value="${escapeHtml(button.value ?? "")}"` : ""}${button.secondary ? ' class="secondary"' : ""}>${escapeHtml(button.label)}</button>`,
+    )
+    .join(" ");
+  return `<form method="post" action="${escapeHtml(form.action)}">${hidden}${boxes}<p class="actions">${buttons}</p></form>`;
+}
+
+export function renderPage(page: PageContent): string {
+  const { theme } = page;
+  const lists = (page.lists ?? []).slice(0, MAXIMUM_LISTS_SHOWN);
+  const links = (page.links ?? []).map((link) => `<p><a href="${escapeHtml(link.href)}">${escapeHtml(link.label)}</a></p>`).join("\n");
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex"><meta name="referrer" content="no-referrer">
+<title>${escapeHtml(page.heading)} - ${escapeHtml(page.siteName)}</title>
+<style>
+body{margin:0;background:${theme.background};color:${theme.text};font-family:${theme.fontFamily};line-height:1.5}
+main{max-width:34rem;margin:0 auto;padding:3rem 1.25rem}
+.site{color:${theme.muted};font-size:.95rem;margin:0 0 1.5rem}
+h1{font-size:1.6rem;line-height:1.2;margin:0 0 1rem}
+.notice{background:${theme.surface};border-left:4px solid ${theme.accent};padding:.5rem .75rem;font-weight:bold}
+ul{background:${theme.surface};margin:1rem 0;padding:.75rem 1.25rem 1rem 2rem}
+.box{margin:.6rem 0}
+input[type=checkbox]{width:1.1rem;height:1.1rem;vertical-align:middle}
+.actions{margin:1.25rem 0}
+button{background:${theme.accent};color:#fff;border:2px solid ${theme.accent};font:inherit;font-weight:bold;padding:.7rem 1.4rem;cursor:pointer;border-radius:4px;margin:0 .5rem .5rem 0}
+button.secondary{background:${theme.background};color:${theme.accent}}
+button:focus-visible,a:focus-visible,input:focus-visible{outline:3px solid ${theme.text};outline-offset:2px}
+a{color:${theme.accent}}
+</style></head><body><main>
+<p class="site">${escapeHtml(page.siteName)}</p>
+<h1>${escapeHtml(page.heading)}</h1>
+${page.notice ? `<p class="notice" role="status">${escapeHtml(page.notice)}</p>` : ""}
+${page.paragraphs.map((paragraph) => `<p>${escapeHtml(paragraph)}</p>`).join("\n")}
+${lists.length > 0 ? `<ul>${lists.map((name) => `<li>${escapeHtml(name)}</li>`).join("")}</ul>` : ""}
+${(page.forms ?? []).map(renderForm).join("\n")}
+${links}
+</main></body></html>`;
+}
+
+export const PAGE_HEADERS = {
+  "content-type": "text/html; charset=utf-8",
+  "cache-control": "no-store",
+  "referrer-policy": "no-referrer",
+  "x-content-type-options": "nosniff",
+  "content-security-policy": "default-src 'none'; style-src 'unsafe-inline'; form-action 'self'; base-uri 'none'; frame-ancestors 'none'",
+} as const;
+
+export function pageResponse(page: PageContent, status = 200): NextResponse {
+  return new NextResponse(renderPage(page), { status, headers: PAGE_HEADERS });
+}
+
+export const CONFIRM_PATH = "/api/newsletter/confirm";
+
+type Base = Pick<PageContent, "siteName" | "theme">;
+const home = (base: Base) => ({ href: "/", label: `Back to ${base.siteName}` });
+
+export function confirmPromptPage(base: Base, lists: string[], token: string): PageContent {
+  return {
+    ...base,
+    heading: "Confirm your subscription",
+    paragraphs: [`Press the button to start getting email from ${base.siteName}.${lists.length > 0 ? " You are signing up for:" : ""}`],
+    lists,
+    forms: [{ action: CONFIRM_PATH, hidden: { t: token }, buttons: [{ label: "Confirm subscription" }] }],
+  };
+}
+
+export function confirmedPage(base: Base, lists: string[], preferencesHref?: string): PageContent {
+  return {
+    ...base,
+    heading: "You are subscribed",
+    paragraphs: [lists.length > 0 ? "Thank you. You will get:" : "Thank you. Your subscription is confirmed."],
+    lists,
+    links: [...(preferencesHref ? [{ href: preferencesHref, label: "Manage your subscriptions" }] : []), home(base)],
+  };
+}
+
+export function expiredPage(base: Base): PageContent {
+  return {
+    ...base,
+    heading: "This link has expired",
+    paragraphs: [
+      "This confirmation link has expired or was already used. If you already confirmed, you are all set.",
+      "If you did not finish signing up, go back to the site and sign up again to get a new link.",
+    ],
+    links: [home(base)],
+  };
+}
+
+export function unavailablePage(base: Base): PageContent {
+  return {
+    ...base,
+    heading: "Something went wrong",
+    paragraphs: ["We could not complete this just now. Open the link in your email again in a minute."],
+    links: [home(base)],
+  };
+}
+
+export const UNSUBSCRIBE_PATH = "/api/newsletter/unsubscribe";
+export const PREFERENCES_PATH = "/api/newsletter/preferences";
+
+export function preferencesHref(token: string): string {
+  return `${PREFERENCES_PATH}?t=${encodeURIComponent(token)}`;
+}
+
+export function invalidManagePage(base: Base): PageContent {
+  return {
+    ...base,
+    heading: "This link is not valid",
+    paragraphs: ["This link is not valid, or the subscription it belongs to has been deleted. Use the link in a recent email from us."],
+    links: [home(base)],
+  };
+}
+
+export function unsubscribePromptPage(base: Base, token: string, listId: string | null, listName: string | null): PageContent {
+  return {
+    ...base,
+    heading: "Unsubscribe",
+    paragraphs: [listName ? `Stop getting "${listName}" from ${base.siteName}?` : `Stop getting all email from ${base.siteName}?`],
+    forms: [
+      {
+        action: UNSUBSCRIBE_PATH,
+        hidden: { t: token, ...(listId ? { l: listId } : {}), page: "1" },
+        buttons: [{ label: listName ? "Unsubscribe from this list" : "Unsubscribe from everything" }],
+      },
+    ],
+    links: [{ href: preferencesHref(token), label: "Choose which lists you get instead" }],
+  };
+}
+
+export function unsubscribedPage(base: Base, names: string[], token: string | null): PageContent {
+  return {
+    ...base,
+    heading: "You are unsubscribed",
+    paragraphs: [names.length > 0 ? `You will no longer get these from ${base.siteName}:` : `You will no longer get this email from ${base.siteName}.`],
+    lists: names,
+    links: [...(token ? [{ href: preferencesHref(token), label: "Change your mind? Manage your subscriptions" }] : []), home(base)],
+  };
+}
+
+export type PreferenceList = { id: string; name: string; description: string; subscribed: boolean };
+
+export function preferencesPage(base: Base, input: { token: string; email: string; lists: PreferenceList[]; notice?: string }): PageContent {
+  return {
+    ...base,
+    heading: "Your subscriptions",
+    notice: input.notice,
+    paragraphs: [`Email preferences for ${input.email}. Tick the lists you want.`],
+    forms: [
+      {
+        action: PREFERENCES_PATH,
+        hidden: { t: input.token },
+        checkboxes: input.lists.map((list) => ({
+          name: "l",
+          value: list.id,
+          label: list.description ? `${list.name}: ${list.description}` : list.name,
+          checked: list.subscribed,
+        })),
+        buttons: [
+          { label: "Save preferences", name: "action", value: "save" },
+          { label: "Unsubscribe from everything", name: "action", value: "unsubscribe_all", secondary: true },
+          { label: "Delete my data", name: "action", value: "delete", secondary: true },
+        ],
+      },
+    ],
+    links: [home(base)],
+  };
+}
+
+export function deleteConfirmPage(base: Base, token: string): PageContent {
+  return {
+    ...base,
+    heading: "Delete your data?",
+    paragraphs: [
+      `This erases your address and everything ${base.siteName} holds about your subscriptions. You will not get any more email. This cannot be undone.`,
+    ],
+    forms: [
+      {
+        action: PREFERENCES_PATH,
+        hidden: { t: token, action: "delete", confirm: "1" },
+        buttons: [{ label: "Yes, delete my data" }],
+      },
+    ],
+    links: [{ href: preferencesHref(token), label: "No, go back" }],
+  };
+}
+
+export function deletedPage(base: Base): PageContent {
+  return {
+    ...base,
+    heading: "Your data is deleted",
+    paragraphs: ["Your address and subscriptions have been erased. You will not get any more email from us."],
+    links: [home(base)],
+  };
+}