@cosmicdrift/kumiko-samples 0.369.0 → 0.371.0

package/packages/bundled-features/src/delivery/unsubscribe-page.ts

@@ -0,0 +1,226 @@
+import { createHash } from "node:crypto";
+import { mailT } from "@cosmicdrift/kumiko-framework/i18n";
+import { escapeHtml, escapeHtmlAttr } from "@cosmicdrift/kumiko-headless";
+import type { MailChrome, MailChromeLink } from "../renderer-foundation/index.ts";
+import { DELIVERY_RESUBSCRIBE_PATH, DELIVERY_UNSUBSCRIBE_PATH } from "./public-names.ts";
+import "./unsubscribe-page-strings.ts";
+
+export type UnsubscribePageState =
+  | { readonly kind: "confirm"; readonly token: string }
+  // Without a resubscribeToken the page offers no undo button.
+  | { readonly kind: "unsubscribed"; readonly resubscribeToken?: string }
+  | { readonly kind: "resubscribed" }
+  | { readonly kind: "failed" }
+  | { readonly kind: "invalid" };
+
+export type UnsubscribePageInput = {
+  readonly state: UnsubscribePageState;
+  /** A locale with registered mail translations (see resolveMailLocale). */
+  readonly locale: string;
+  /** The tenant's mail look; without it the page shows the plain card. */
+  readonly chrome?: MailChrome | null | undefined;
+};
+
+// Same values as the in-code mail layout of renderer-mail-html, so the page reads as the mail's sequel.
+const DEFAULT_ACCENT_COLOR = "#1f5468";
+const HEX_COLOR = /^#[0-9a-fA-F]{6}$/;
+const FONT_URL_PREFIX = "/assets/kumiko/fonts/ibm-plex-sans-latin-";
+
+function accentOf(chrome: MailChrome | null | undefined): string {
+  const accent = chrome?.accentColor;
+  return accent !== undefined && HEX_COLOR.test(accent) ? accent : DEFAULT_ACCENT_COLOR;
+}
+
+function httpsOrigin(url: string | undefined): string | undefined {
+  if (url === undefined) return undefined;
+  try {
+    const parsed = new URL(url);
+    return parsed.protocol === "https:" ? parsed.origin : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function webHost(url: string): string | undefined {
+  try {
+    const parsed = new URL(url);
+    return parsed.protocol === "https:" || parsed.protocol === "http:" ? parsed.host : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+const SAFE_LINK_URL = /^(https?:|mailto:)/i;
+
+function linkHtml(link: MailChromeLink): string {
+  const url = link.url.trim();
+  if (!SAFE_LINK_URL.test(url) || link.label.trim() === "") return "";
+  return `<a href="${escapeHtmlAttr(url)}">${escapeHtml(link.label)}</a>`;
+}
+
+// The style block is static apart from the validated hex accent and the markup carries
+// no style attributes, so the CSP admits exactly this block by its hash.
+function pageStyle(accent: string): string {
+  return `@font-face{font-family:"IBM Plex Sans";font-style:normal;font-weight:400;font-display:swap;src:url("${FONT_URL_PREFIX}400.woff2") format("woff2")}
+@font-face{font-family:"IBM Plex Sans";font-style:normal;font-weight:600;font-display:swap;src:url("${FONT_URL_PREFIX}600.woff2") format("woff2")}
+:root{--accent:${accent}}
+*{box-sizing:border-box}
+html,body{margin:0;padding:0}
+body{background:#ecedea;color:#2a2f3a;font-family:"IBM Plex Sans",ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,Helvetica,Arial,sans-serif;font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
+.page{max-width:560px;margin:0 auto;padding:48px 16px}
+.card{background:#fff;border:1px solid #dcdfda;border-radius:14px;overflow:hidden}
+.accent{height:4px;background:var(--accent)}
+.brand{display:flex;align-items:center;gap:10px;padding:32px 40px 0}
+.brand img{height:28px;width:auto;max-width:140px;display:block}
+.tile{width:28px;height:28px;line-height:28px;border-radius:8px;background:var(--accent);color:#fff;font-weight:600;font-size:14px;text-align:center;flex:none}
+.name{font-size:15px;font-weight:600;color:#0b0d12}
+.suffix{font-size:13px;color:#5a6170}
+.content{padding:28px 40px 36px}
+h1{margin:0 0 8px;font-size:22px;line-height:1.3;font-weight:600;color:#0b0d12}
+p{margin:0}
+form{margin:24px 0 0}
+.button{display:inline-block;font:inherit;font-weight:600;font-size:15px;line-height:1.4;padding:10px 20px;border-radius:6px;border:1px solid var(--accent);background:var(--accent);color:#fff;cursor:pointer}
+.button.secondary{background:#fff;color:var(--accent)}
+.button:focus-visible{outline:2px solid var(--accent);outline-offset:2px}
+.hint{margin-top:24px;font-size:14px;color:#5a6170}
+.hint+form{margin-top:12px}
+.band{background:#fbfbfa;border-top:1px solid #ecedea;padding:16px 40px;font-size:13px;color:#5a6170}
+.band a{color:#4a515e}
+.footer{padding:20px 24px 0;text-align:center;font-size:12px;color:#5a6170}
+.footer a{color:#5a6170}
+@media (max-width:480px){.page{padding:24px 12px}.brand{padding:24px 20px 0}.content{padding:20px 20px 28px}.band{padding:14px 20px}h1{font-size:20px}.button{width:100%}}`;
+}
+
+function brandRowHtml(chrome: MailChrome): string {
+  const name = chrome.tenantName.trim();
+  const initial = Array.from(name)[0]?.toLocaleUpperCase() ?? "";
+  const mark =
+    httpsOrigin(chrome.logoUrl) !== undefined && chrome.logoUrl !== undefined
+      ? `<img src="${escapeHtmlAttr(chrome.logoUrl)}" alt="">`
+      : initial === ""
+        ? ""
+        : `<span class="tile" aria-hidden="true">${escapeHtml(initial)}</span>`;
+  const suffix = chrome.brandSuffix.trim();
+  if (mark === "" && name === "") return "";
+  return `<div class="brand">${mark}${name === "" ? "" : `<span class="name">${escapeHtml(name)}</span>`}${suffix === "" ? "" : `<span class="suffix">${escapeHtml(suffix)}</span>`}</div>`;
+}
+
+function bandHtml(chrome: MailChrome): string {
+  const host = chrome.siteUrl === undefined ? undefined : webHost(chrome.siteUrl);
+  if (host === undefined || chrome.siteUrl === undefined) return "";
+  return `<div class="band"><a href="${escapeHtmlAttr(chrome.siteUrl)}">${escapeHtml(host)}</a></div>`;
+}
+
+function footerHtml(chrome: MailChrome): string {
+  const text = chrome.footerText?.trim() ?? "";
+  const links = [chrome.imprint, chrome.privacy]
+    .map((link) => (link === undefined ? "" : linkHtml(link)))
+    .filter((html) => html !== "");
+  const lineHtmls = [
+    ...(text === "" ? [] : [escapeHtml(text)]),
+    ...(links.length === 0 ? [] : [links.join(" · ")]),
+  ];
+  const linesHtml = lineHtmls.join("<br>");
+  return linesHtml === "" ? "" : `<footer class="footer">${linesHtml}</footer>`;
+}
+
+function tokenForm(action: string, token: string, label: string, variant: string): string {
+  return `<form method="post" action="${escapeHtmlAttr(action)}">
+<input type="hidden" name="token" value="${escapeHtmlAttr(token)}">
+<button type="submit" class="${escapeHtmlAttr(variant)}">${escapeHtml(label)}</button>
+</form>`;
+}
+
+type PageText = { readonly title: string; readonly bodyHtml: string };
+
+function pageText(state: UnsubscribePageState, lang: string): PageText {
+  const paragraph = (key: string): string => `<p>${escapeHtml(mailT(lang, key))}</p>`;
+  switch (state.kind) {
+    case "confirm":
+      return {
+        title: mailT(lang, "mail.unsubscribe.confirmTitle"),
+        bodyHtml: `${paragraph("mail.unsubscribe.confirmQuestion")}
+${tokenForm(DELIVERY_UNSUBSCRIBE_PATH, state.token, mailT(lang, "mail.unsubscribe.confirmButton"), "button")}`,
+      };
+    case "unsubscribed":
+      return {
+        title: mailT(lang, "mail.unsubscribe.doneTitle"),
+        bodyHtml:
+          state.resubscribeToken === undefined
+            ? paragraph("mail.unsubscribe.doneMessage")
+            : `${paragraph("mail.unsubscribe.doneMessage")}
+<p class="hint">${escapeHtml(mailT(lang, "mail.unsubscribe.undoHint"))}</p>
+${tokenForm(DELIVERY_RESUBSCRIBE_PATH, state.resubscribeToken, mailT(lang, "mail.unsubscribe.undoButton"), "button secondary")}`,
+      };
+    case "resubscribed":
+      return {
+        title: mailT(lang, "mail.unsubscribe.resubscribedTitle"),
+        bodyHtml: paragraph("mail.unsubscribe.resubscribedMessage"),
+      };
+    case "failed":
+      return {
+        title: mailT(lang, "mail.unsubscribe.failedTitle"),
+        bodyHtml: paragraph("mail.unsubscribe.failed"),
+      };
+    case "invalid":
+      return {
+        title: mailT(lang, "mail.unsubscribe.invalidTitle"),
+        bodyHtml: paragraph("mail.unsubscribe.invalidMessage"),
+      };
+  }
+}
+
+export type RenderedUnsubscribePage = {
+  readonly html: string;
+  readonly contentSecurityPolicy: string;
+};
+
+// The page loads nothing but its own style block, the same-origin font and, with
+// branding, the tenant's https logo. Forms only post back to the same origin.
+function contentSecurityPolicy(style: string, chrome: MailChrome | null | undefined): string {
+  const styleHash = createHash("sha256").update(style).digest("base64");
+  const logoOrigin = httpsOrigin(chrome?.logoUrl);
+  return [
+    "default-src 'none'",
+    `style-src 'sha256-${styleHash}'`,
+    "font-src 'self'",
+    `img-src 'self' data:${logoOrigin === undefined ? "" : ` ${logoOrigin}`}`,
+    "form-action 'self'",
+    "base-uri 'none'",
+    "frame-ancestors 'none'",
+  ].join("; ");
+}
+
+export function renderUnsubscribePage(input: UnsubscribePageInput): RenderedUnsubscribePage {
+  const { state, locale, chrome } = input;
+  const { title, bodyHtml } = pageText(state, locale);
+  const style = pageStyle(accentOf(chrome));
+  const branded = chrome !== null && chrome !== undefined;
+  // html-ok: static CSS whose only variable is the hex-validated accent; escaping would break its quotes and the CSP hash.
+  const styleBlockHtml = `<style>${style}</style>`;
+  const html = `<!doctype html>
+<html lang="${escapeHtmlAttr(locale)}">
+<head>
+<meta charset="utf-8">
+<meta name="robots" content="noindex">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(title)}</title>
+${styleBlockHtml}
+</head>
+<body>
+<main class="page">
+<div class="card">
+<div class="accent"></div>
+${branded ? brandRowHtml(chrome) : ""}
+<div class="content">
+<h1>${escapeHtml(title)}</h1>
+${bodyHtml}
+</div>
+${branded ? bandHtml(chrome) : ""}
+</div>
+${branded ? footerHtml(chrome) : ""}
+</main>
+</body>
+</html>`;
+  return { html, contentSecurityPolicy: contentSecurityPolicy(style, chrome) };
+}

package/packages/bundled-features/src/delivery/unsubscribe.ts

@@ -6,19 +6,22 @@ import {
   signatureRoute,
 } from "@cosmicdrift/kumiko-framework/api";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
-import { mailT, resolveMailLocale } from "@cosmicdrift/kumiko-framework/i18n";
-import { escapeHtmlAttr } from "@cosmicdrift/kumiko-headless";
+import { resolveMailLocale } from "@cosmicdrift/kumiko-framework/i18n";
+import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+import type { Context } from "hono";
 import * as jose from "jose";
 import * as z from "zod";
-import { hashUnsubscribeAddress } from "./address-opt-out.js";
+import type { MailChrome } from "../renderer-foundation/index.ts";
+import { hashUnsubscribeAddress } from "./address-opt-out.ts";
 import {
   DELIVERY_RESUBSCRIBE_PATH,
   DELIVERY_UNSUBSCRIBE_PATH,
   DeliveryErrors,
   DeliveryHandlers,
-} from "./constants.js";
-import "./unsubscribe-page-strings.js";
+  DeliveryQueries,
+} from "./constants.ts";
+import { renderUnsubscribePage, type UnsubscribePageState } from "./unsubscribe-page.ts";
 
 // The mail's locale, so the pages behind the link speak the mail's language. Optional: links
 // signed before the claim existed keep verifying and fall back to English.
@@ -109,6 +112,32 @@ const UNSUBSCRIBE_TOKEN_INVALID_BODY = {
   error: { code: "unsubscribe_token_invalid", message: "Invalid or expired token" },
 } as const;
 
+// jose checks the signature and the issuer before the expiry, so the claims of an
+// expired token are authentic: enough to dress the "link expired" page in the
+// tenant's look and language, never enough to write.
+const expiredTokenScopeSchema = z.object({
+  iss: z.literal(UNSUBSCRIBE_ISSUER),
+  tenantId: z.string().min(1),
+  locale: localeClaimSchema,
+});
+
+class ExpiredUnsubscribeTokenRejection extends ExtraRouteRejection {
+  constructor(
+    readonly tenantId: TenantId,
+    readonly locale: string | undefined,
+  ) {
+    super(400, UNSUBSCRIBE_TOKEN_INVALID_BODY, "unsubscribe token expired");
+  }
+}
+
+function expiredTokenRejection(err: unknown): ExpiredUnsubscribeTokenRejection | null {
+  if (!(err instanceof jose.errors.JWTExpired)) return null;
+  const scope = expiredTokenScopeSchema.safeParse(err.payload);
+  if (!scope.success) return null;
+  // @cast-boundary engine-bridge — string post-zod → branded TenantId
+  return new ExpiredUnsubscribeTokenRejection(scope.data.tenantId as TenantId, scope.data.locale);
+}
+
 export async function signUnsubscribeToken(
   payload: UnsubscribeTokenPayload,
   secret: string,
@@ -189,11 +218,6 @@ type VerifiedUnsubscribe =
 // one-click client POSTs.
 export const DELIVERY_UNSUBSCRIBE_ONE_CLICK_HEADER_VALUE = "List-Unsubscribe=One-Click" as const;
 
-const CONFIRMATION_PAGE_HEADERS = {
-  "Cache-Control": "no-store",
-  "Referrer-Policy": "no-referrer",
-} as const;
-
 // Undo token, handed out only in the response of a successful unsubscribe. A
 // separate audience and a short expiry keep the long-lived mailed unsubscribe
 // link from being able to undo an opt-out (and vice versa).
@@ -302,10 +326,13 @@ async function verifyUnsubscribeToken(
     };
   } catch (err) {
     if (err instanceof ExtraRouteRejection) throw err;
-    throw new ExtraRouteRejection(
-      400,
-      UNSUBSCRIBE_TOKEN_INVALID_BODY,
-      "unsubscribe token verification failed",
+    throw (
+      expiredTokenRejection(err) ??
+      new ExtraRouteRejection(
+        400,
+        UNSUBSCRIBE_TOKEN_INVALID_BODY,
+        "unsubscribe token verification failed",
+      )
     );
   }
 }
@@ -387,76 +414,144 @@ function pageLocale(locale: string | undefined): string {
   return resolveMailLocale(locale ?? "en");
 }
 
-function htmlPage(locale: string, title: string, bodyHtml: string): string {
-  return `<!doctype html>
-<html lang="${escapeHtmlAttr(locale)}">
-<head>
-<meta charset="utf-8">
-<meta name="robots" content="noindex">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<title>${escapeHtmlAttr(title)}</title>
-</head>
-<body>
-${bodyHtml}
-</body>
-</html>`;
-}
-
-function confirmationPage(token: string, locale: string | undefined): string {
-  const lang = pageLocale(locale);
-  return htmlPage(
-    lang,
-    mailT(lang, "mail.unsubscribe.confirmTitle"),
-    `<p>${escapeHtmlAttr(mailT(lang, "mail.unsubscribe.confirmQuestion"))}</p>
-<form method="post" action="${DELIVERY_UNSUBSCRIBE_PATH}">
-<input type="hidden" name="token" value="${escapeHtmlAttr(token)}">
-<button type="submit">${escapeHtmlAttr(mailT(lang, "mail.unsubscribe.confirmButton"))}</button>
-</form>`,
-  );
-}
-
 export type UnsubscribeResultPage =
   // Without a resubscribeToken the page offers no undo button.
   | { readonly kind: "unsubscribed"; readonly resubscribeToken?: string }
   | { readonly kind: "resubscribed" }
-  | { readonly kind: "failed" };
-
-/** The plain result page the unsubscribe routes answer with, for apps serving their own
- *  (e.g. legacy) unsubscribe links. Texts come from the mail translations of `locale`. */
+  | { readonly kind: "failed" }
+  | { readonly kind: "invalid" };
+
+/** The result page the unsubscribe routes answer with, for apps serving their own
+ *  (e.g. legacy) unsubscribe links. Texts come from the mail translations of `locale`;
+ *  `chrome` (the mail renderer's readMailChrome) adds the tenant's brand row and footer.
+ *  Served under runProdApp's default CSP the style block and the same-origin font pass;
+ *  an https logo additionally needs its origin, e.g.
+ *  `securityHeaders: { csp: { extend: { "img-src": [logoOrigin] } } }`. A hand-written CSP
+ *  needs `style-src 'unsafe-inline'` as well. */
 export function renderUnsubscribeResultPage(
-  page: UnsubscribeResultPage & { readonly locale?: string | undefined },
+  page: UnsubscribeResultPage & {
+    readonly locale?: string | undefined;
+    readonly chrome?: MailChrome | null | undefined;
+  },
 ): string {
-  const lang = pageLocale(page.locale);
-  switch (page.kind) {
-    case "unsubscribed": {
-      const undoForm =
-        page.resubscribeToken === undefined
-          ? ""
-          : `
-<form method="post" action="${DELIVERY_RESUBSCRIBE_PATH}">
-<input type="hidden" name="token" value="${escapeHtmlAttr(page.resubscribeToken)}">
-<button type="submit">${escapeHtmlAttr(mailT(lang, "mail.unsubscribe.undoButton"))}</button>
-</form>`;
-      return htmlPage(
-        lang,
-        mailT(lang, "mail.unsubscribe.doneTitle"),
-        `<p>${escapeHtmlAttr(mailT(lang, "mail.unsubscribe.doneMessage"))}</p>${undoForm}`,
-      );
+  const { locale, chrome, ...state } = page;
+  return renderUnsubscribePage({ state, locale: pageLocale(locale), chrome }).html;
+}
+
+const NO_STORE_HEADERS = { "Cache-Control": "no-store" } as const;
+
+const mailChromeLinkSchema = z.object({ label: z.string(), url: z.string() });
+const mailChromeSchema = z
+  .object({
+    tenantName: z.string(),
+    brandSuffix: z.string(),
+    logoUrl: z.string().optional(),
+    accentColor: z.string().optional(),
+    siteUrl: z.string().optional(),
+    footerText: z.string().optional(),
+    imprint: mailChromeLinkSchema.optional(),
+    privacy: mailChromeLinkSchema.optional(),
+  })
+  .nullable();
+
+// Branding is decoration: an opt-out that went through must never turn into an
+// error page because a footer resolver or the config read failed.
+async function readPageChrome(
+  deps: SignatureExtraRouteDeps,
+  tenantId: TenantId,
+  locale: string,
+): Promise<MailChrome | null> {
+  try {
+    const result = await deps.dispatchSystemQuery({
+      handlerQn: DeliveryQueries.unsubscribePageChrome,
+      payload: { locale },
+      tenantId,
+    });
+    const parsed = mailChromeSchema.safeParse(result);
+    return parsed.success ? parsed.data : null;
+  } catch (err) {
+    createFallbackLogger("delivery").warn("unsubscribe page shown without tenant branding", {
+      errorName: err instanceof Error ? err.name : typeof err,
+    });
+    return null;
+  }
+}
+
+type PageScope = { readonly tenantId: TenantId | undefined; readonly locale: string | undefined };
+
+// no-referrer on every page: the GET page carries the token in its URL, and the
+// tenant logo and site link would otherwise receive it in the Referer header.
+const PAGE_HEADERS = {
+  "Cache-Control": "no-store",
+  "Referrer-Policy": "no-referrer",
+} as const;
+
+async function pageResponse(
+  // biome-ignore lint/suspicious/noExplicitAny: Hono context generics are invisible at the framework boundary
+  c: Context<any, any>,
+  deps: SignatureExtraRouteDeps,
+  state: UnsubscribePageState,
+  scope: PageScope,
+  status: 200 | 400 | 409 | 500,
+): Promise<Response> {
+  const locale = pageLocale(scope.locale);
+  const chrome =
+    scope.tenantId === undefined ? null : await readPageChrome(deps, scope.tenantId, locale);
+  const page = renderUnsubscribePage({ state, locale, chrome });
+  return c.html(page.html, status, {
+    ...PAGE_HEADERS,
+    "Content-Security-Policy": page.contentSecurityPolicy,
+  });
+}
+
+type RejectedForPage = { readonly kind: "rejected" } & PageScope;
+
+function localeFromAcceptLanguage(header: string | undefined): string | undefined {
+  const first = header?.split(",")[0]?.split(";")[0]?.trim();
+  return first !== undefined && first !== "" && localeClaimSchema.safeParse(first).success
+    ? first
+    : undefined;
+}
+
+// A browser lands on a page even for a dead link; API callers keep the JSON 400 from
+// verifyUnsubscribeToken. The rejected result never reaches a write.
+async function verifyForPage(
+  token: string | undefined,
+  encodedSecret: Uint8Array,
+  purpose: TokenPurpose,
+  headers: SignatureExtraRouteVerifyRequest["headers"],
+): Promise<VerifiedUnsubscribe | RejectedForPage> {
+  try {
+    return await verifyUnsubscribeToken(token, encodedSecret, purpose);
+  } catch (err) {
+    if (err instanceof ExpiredUnsubscribeTokenRejection) {
+      return {
+        kind: "rejected",
+        tenantId: err.tenantId,
+        locale: err.locale ?? localeFromAcceptLanguage(headers["accept-language"]),
+      };
     }
-    case "resubscribed":
-      return htmlPage(
-        lang,
-        mailT(lang, "mail.unsubscribe.resubscribedTitle"),
-        `<p>${escapeHtmlAttr(mailT(lang, "mail.unsubscribe.resubscribedMessage"))}</p>`,
-      );
-    case "failed": {
-      const message = mailT(lang, "mail.unsubscribe.failed");
-      return htmlPage(lang, message, `<p>${escapeHtmlAttr(message)}</p>`);
+    if (err instanceof ExtraRouteRejection) {
+      return {
+        kind: "rejected",
+        tenantId: undefined,
+        locale: localeFromAcceptLanguage(headers["accept-language"]),
+      };
     }
+    throw err;
   }
 }
 
-const NO_STORE_HEADERS = { "Cache-Control": "no-store" } as const;
+async function verifyPost(
+  request: SignatureExtraRouteVerifyRequest,
+  token: string | undefined,
+  encodedSecret: Uint8Array,
+  purpose: TokenPurpose,
+): Promise<VerifiedUnsubscribe | RejectedForPage> {
+  return isFormRequest(request.headers["content-type"])
+    ? verifyForPage(token, encodedSecret, purpose, request.headers)
+    : verifyUnsubscribeToken(token, encodedSecret, purpose);
+}
 
 function isFormRequest(contentType: string | undefined): boolean {
   return contentType?.includes("application/x-www-form-urlencoded") === true;
@@ -499,52 +594,52 @@ export function createUnsubscribeRoutes(
   assertUnsubscribeSecret(options.secret, "createUnsubscribeRoutes");
   const encodedSecret = new TextEncoder().encode(options.secret);
 
-  const confirmRoute = signatureRoute<{ token: string; locale: string | undefined }>({
+  const confirmRoute = signatureRoute<
+    ({ readonly kind: "confirm"; readonly token: string } & PageScope) | RejectedForPage
+  >({
     method: "GET",
     path: DELIVERY_UNSUBSCRIBE_PATH,
     entry: "signature",
-    verify: async ({ query }) => {
+    verify: async ({ query, headers }) => {
       const token = query["token"];
-      if (!token) {
-        throw new ExtraRouteRejection(
-          400,
-          UNSUBSCRIBE_TOKEN_INVALID_BODY,
-          "missing unsubscribe token",
-        );
-      }
-      const verified = await verifyUnsubscribeToken(token, encodedSecret, "unsubscribe");
-      return { token, locale: verified.locale };
+      const verified = await verifyForPage(token, encodedSecret, "unsubscribe", headers);
+      if (verified.kind === "rejected") return verified;
+      // verifyForPage only accepts a present token, the check is for the type.
+      if (token === undefined) return { kind: "rejected", tenantId: undefined, locale: undefined };
+      return { kind: "confirm", token, tenantId: verified.tenantId, locale: verified.locale };
     },
-    handler: async (c, { token, locale }) =>
-      c.html(confirmationPage(token, locale), 200, CONFIRMATION_PAGE_HEADERS),
+    handler: async (c, verified, deps) =>
+      verified.kind === "rejected"
+        ? pageResponse(c, deps, { kind: "invalid" }, verified, 400)
+        : pageResponse(c, deps, { kind: "confirm", token: verified.token }, verified, 200),
   });
 
-  const writeRoute = signatureRoute<VerifiedUnsubscribe>({
+  const writeRoute = signatureRoute<VerifiedUnsubscribe | RejectedForPage>({
     method: "POST",
     path: DELIVERY_UNSUBSCRIBE_PATH,
     entry: "signature",
     verify: async (request) =>
-      verifyUnsubscribeToken(tokenFromPostRequest(request), encodedSecret, "unsubscribe"),
+      verifyPost(request, tokenFromPostRequest(request), encodedSecret, "unsubscribe"),
     handler: async (c, verified, deps) => {
+      if (verified.kind === "rejected") {
+        return pageResponse(c, deps, { kind: "invalid" }, verified, 400);
+      }
       // Token-verify passed — everything below is a legitimate write. Don't
       // swallow write-errors as "invalid token", that would mask real bugs
       // (e.g. events-table missing, DB down) behind a misleading 400.
       const succeeded = await dispatchUnsubscribeWrite(verified, deps);
       if (!succeeded) {
-        return c.html(
-          renderUnsubscribeResultPage({ kind: "failed", locale: verified.locale }),
-          500,
-          NO_STORE_HEADERS,
-        );
+        return pageResponse(c, deps, { kind: "failed" }, verified, 500);
       }
-      return c.html(
-        renderUnsubscribeResultPage({
+      return pageResponse(
+        c,
+        deps,
+        {
           kind: "unsubscribed",
           resubscribeToken: await signResubscribeToken(verified, encodedSecret),
-          locale: verified.locale,
-        }),
+        },
+        verified,
         200,
-        NO_STORE_HEADERS,
       );
     },
   });
@@ -552,26 +647,27 @@ export function createUnsubscribeRoutes(
   // Undo direction: token only from the JSON/form body, never the query
   // (see tokenFromRequestBody) — no GET confirmation-page variant,
   // this is a one-shot POST from the unsubscribe-page's "Undo" button.
-  const resubscribeRoute = signatureRoute<VerifiedUnsubscribe>({
+  const resubscribeRoute = signatureRoute<VerifiedUnsubscribe | RejectedForPage>({
     method: "POST",
     path: DELIVERY_RESUBSCRIBE_PATH,
     entry: "signature",
     verify: async (request) =>
-      verifyUnsubscribeToken(tokenFromRequestBody(request), encodedSecret, "resubscribe"),
+      verifyPost(request, tokenFromRequestBody(request), encodedSecret, "resubscribe"),
     handler: async (c, verified, deps) => {
+      if (verified.kind === "rejected") {
+        return pageResponse(c, deps, { kind: "invalid" }, verified, 400);
+      }
       const outcome = await dispatchResubscribeWrite(verified, deps);
       // The undo button on the unsubscribed page posts a form; a browser should land on a page.
       if (isFormRequest(c.req.header("content-type"))) {
         return outcome === "success"
-          ? c.html(
-              renderUnsubscribeResultPage({ kind: "resubscribed", locale: verified.locale }),
-              200,
-              NO_STORE_HEADERS,
-            )
-          : c.html(
-              renderUnsubscribeResultPage({ kind: "failed", locale: verified.locale }),
+          ? pageResponse(c, deps, { kind: "resubscribed" }, verified, 200)
+          : pageResponse(
+              c,
+              deps,
+              { kind: "failed" },
+              verified,
               outcome === "limit_reached" ? 409 : 500,
-              NO_STORE_HEADERS,
             );
       }
       if (outcome === "limit_reached") {

package/packages/bundled-features/src/delivery/upsert-preference.ts

@@ -20,7 +20,7 @@ import {
 } from "@cosmicdrift/kumiko-framework/db";
 import type { SessionUser, TenantId, WriteResult } from "@cosmicdrift/kumiko-framework/engine";
 import { generateDeterministicId } from "@cosmicdrift/kumiko-framework/utils";
-import { notificationPreferenceEntity, notificationPreferencesTable } from "./tables.js";
+import { notificationPreferenceEntity, notificationPreferencesTable } from "./tables.ts";
 
 const executor = createEventStoreExecutor(
   notificationPreferencesTable,

package/packages/bundled-features/src/delivery/web/client-plugin.tsx

@@ -8,12 +8,12 @@ import {
   DELIVERY_STATUS_CELL_COMPONENT,
   DELIVERY_TIME_CELL_COMPONENT,
   DELIVERY_TYPE_CELL_COMPONENT,
-} from "../public-names.js";
-import { DeliveryChannelCell } from "./delivery-channel-cell.js";
-import { DeliveryErrorCell } from "./delivery-error-cell.js";
-import { DeliveryStatusCell } from "./delivery-status-cell.js";
-import { DeliveryTimeCell } from "./delivery-time-cell.js";
-import { DeliveryTypeCell } from "./delivery-type-cell.js";
+} from "../public-names.ts";
+import { DeliveryChannelCell } from "./delivery-channel-cell.tsx";
+import { DeliveryErrorCell } from "./delivery-error-cell.tsx";
+import { DeliveryStatusCell } from "./delivery-status-cell.tsx";
+import { DeliveryTimeCell } from "./delivery-time-cell.tsx";
+import { DeliveryTypeCell } from "./delivery-type-cell.tsx";
 
 export type DeliveryClientOptions = {
   readonly translations?: TranslationsByLocale;