@marktiderman/genesis-notifications 0.0.0-stage → 0.1.1

package/src/react/index.tsx

@@ -0,0 +1,226 @@
+/**
+ * `@marktiderman/genesis-notifications/react`: the hooks every screen uses,
+ * on web and native alike. `NotificationsProvider` holds the client, the
+ * registry and the signed-in user, and listens on the person's private
+ * realtime channel: any change refetches (the broadcast carries ids only).
+ *
+ *   useNotifications()   the feed, each row rendered by the registry, plus mark read / archive
+ *   useUnreadCount()     the unread count, for a bell or a tab badge
+ *   usePreferences()     the category × channel matrix and its switches
+ *
+ * Built on TanStack Query (a peer): the app's QueryClientProvider must be above.
+ *
+ * @packageDocumentation
+ */
+import { createContext, useContext, useEffect, useMemo, type ReactNode } from "react";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import type { Channel, ChannelChoices, MatrixRow, NotificationRegistry, NotificationRow } from "../core/index";
+import { notificationsClient, type FeedFilter, type NotificationsClient, type NotificationsSupabaseLike } from "../supabase/index";
+
+interface Context {
+  client: NotificationsClient;
+  registry: NotificationRegistry;
+  userId: string | null;
+}
+
+const NotificationsContext = createContext<Context | null>(null);
+
+export interface NotificationsProviderProps {
+  /** A Supabase client signed in as the person (or a `notificationsClient`). */
+  client: NotificationsSupabaseLike | NotificationsClient;
+  registry: NotificationRegistry;
+  /** The signed-in user; null while signed out (nothing is read). */
+  userId: string | null;
+  /** Listen on `user:<id>` and refetch on a change. Default true. */
+  realtime?: boolean;
+  children?: ReactNode;
+}
+
+const isClient = (c: NotificationsSupabaseLike | NotificationsClient): c is NotificationsClient => typeof (c as NotificationsClient).feed === "function";
+
+/** The query keys, for an app that invalidates them itself. */
+export const notificationKeys = {
+  all: (userId: string | null) => ["genesis-notifications", userId] as const,
+  feed: (userId: string | null, filter: FeedFilter, limit: number) => ["genesis-notifications", userId, "feed", filter, limit] as const,
+  unread: (userId: string | null) => ["genesis-notifications", userId, "unread"] as const,
+  choices: (userId: string | null) => ["genesis-notifications", userId, "choices"] as const,
+};
+
+/**
+ * Provides the notifier to the hooks.
+ *
+ * @stability Beta
+ */
+export function NotificationsProvider({ client, registry, userId, realtime = true, children }: NotificationsProviderProps) {
+  const resolved = useMemo(() => (isClient(client) ? client : notificationsClient(client)), [client]);
+  const queryClient = useQueryClient();
+  useEffect(() => {
+    if (!realtime || !userId) return;
+    try {
+      return resolved.subscribe(userId, () => {
+        void queryClient.invalidateQueries({ queryKey: notificationKeys.all(userId) });
+      });
+    } catch (error) {
+      console.warn(`[genesis-notifications] couldn't listen for feed changes: ${error instanceof Error ? error.message : "unknown error"}`);
+      return undefined;
+    }
+  }, [resolved, userId, realtime, queryClient]);
+  const value = useMemo(() => ({ client: resolved, registry, userId }), [resolved, registry, userId]);
+  return <NotificationsContext.Provider value={value}>{children}</NotificationsContext.Provider>;
+}
+
+/** The provider's client, registry and user. Throws outside one. */
+export function useNotificationsContext(): Context {
+  const ctx = useContext(NotificationsContext);
+  if (!ctx) throw new Error("useNotifications: wrap the screen in <NotificationsProvider>.");
+  return ctx;
+}
+
+/** A feed row with what the registry says about it. */
+export interface FeedItem extends NotificationRow {
+  title: string;
+  body?: string;
+  url?: string;
+  unread: boolean;
+}
+
+export interface UseNotificationsResult {
+  items: FeedItem[];
+  isLoading: boolean;
+  isRefetching: boolean;
+  error: Error | null;
+  refetch: () => Promise<unknown>;
+  markRead: (ids: string | readonly string[]) => Promise<void>;
+  markUnread: (ids: string | readonly string[]) => Promise<void>;
+  markAllRead: () => Promise<void>;
+  archive: (ids: string | readonly string[]) => Promise<void>;
+  /** Mark everything shown as seen (opening the feed); the unread count is about read, not seen. */
+  markAllSeen: () => Promise<void>;
+}
+
+/**
+ * The person's feed.
+ *
+ * @stability Beta
+ */
+export function useNotifications(options: { filter?: FeedFilter; limit?: number } = {}): UseNotificationsResult {
+  const { client, registry, userId } = useNotificationsContext();
+  const filter = options.filter ?? "all";
+  const limit = options.limit ?? 50;
+  const queryClient = useQueryClient();
+  const query = useQuery({
+    queryKey: notificationKeys.feed(userId, filter, limit),
+    queryFn: () => client.feed({ filter, limit }),
+    enabled: userId !== null,
+  });
+  const items = useMemo<FeedItem[]>(
+    () =>
+      (query.data ?? []).map((row) => {
+        const text = registry.render(row.type, row.data ?? {});
+        return { ...row, ...text, unread: row.read_at === null };
+      }),
+    [query.data, registry],
+  );
+  const changed = () => queryClient.invalidateQueries({ queryKey: notificationKeys.all(userId) });
+  const mark = useMutation({
+    mutationFn: ({ ids, state }: { ids: readonly string[]; state: "seen" | "read" | "unread" | "archived" }) => client.mark(ids, state),
+    onSettled: changed,
+  });
+  const all = useMutation({ mutationFn: (state: "seen" | "read") => client.markAll(state), onSettled: changed });
+  const list = (ids: string | readonly string[]) => (typeof ids === "string" ? [ids] : ids);
+  return {
+    items,
+    isLoading: query.isLoading,
+    isRefetching: query.isRefetching,
+    error: (query.error as Error | null) ?? null,
+    refetch: () => query.refetch(),
+    markRead: async (ids) => void (await mark.mutateAsync({ ids: list(ids), state: "read" })),
+    markUnread: async (ids) => void (await mark.mutateAsync({ ids: list(ids), state: "unread" })),
+    archive: async (ids) => void (await mark.mutateAsync({ ids: list(ids), state: "archived" })),
+    markAllRead: async () => void (await all.mutateAsync("read")),
+    markAllSeen: async () => void (await all.mutateAsync("seen")),
+  };
+}
+
+/**
+ * The unread count (0 while signed out).
+ *
+ * @stability Beta
+ */
+export function useUnreadCount(): number {
+  const { client, userId } = useNotificationsContext();
+  const query = useQuery({ queryKey: notificationKeys.unread(userId), queryFn: () => client.unreadCount(), enabled: userId !== null });
+  return query.data ?? 0;
+}
+
+/** One category's row in the matrix. */
+export interface PreferenceRow extends MatrixRow {
+  /** What each offered channel is now: the person's choice, else the default. */
+  values: Partial<Record<Channel, boolean>>;
+  /** Which values the person chose (the rest are defaults). */
+  chosen: Partial<Record<Channel, boolean>>;
+}
+
+export interface UsePreferencesResult {
+  rows: PreferenceRow[];
+  status: "loading" | "ready" | "error";
+  error: Error | null;
+  saving: boolean;
+  /** Turn one category's channel on or off; `null` goes back to the default. Critical rows can't be turned off. */
+  set: (category: string, channel: Channel, on: boolean | null) => Promise<void>;
+}
+
+/** The matrix with the person's choices applied. Exported for tests and custom screens. */
+export function preferenceRows(registry: NotificationRegistry, choices: ChannelChoices): PreferenceRow[] {
+  return registry.matrix().map((row) => {
+    const chosen = choices[row.id] ?? {};
+    const values: Partial<Record<Channel, boolean>> = {};
+    for (const ch of row.channels) values[ch] = row.critical ? Boolean(row.defaults[ch]) : (chosen[ch] ?? Boolean(row.defaults[ch]));
+    return { ...row, values, chosen: row.critical ? {} : chosen };
+  });
+}
+
+/**
+ * The person's preferences by category and channel. A tenant's default
+ * isn't shown here (the server applies it); what shows for a channel the
+ * person never chose is the type's default.
+ *
+ * @stability Beta
+ */
+export function usePreferences(): UsePreferencesResult {
+  const { client, registry, userId } = useNotificationsContext();
+  const queryClient = useQueryClient();
+  const key = notificationKeys.choices(userId);
+  const query = useQuery({ queryKey: key, queryFn: () => client.choices(userId!), enabled: userId !== null });
+  const save = useMutation({
+    mutationFn: ({ category, channel, on }: { category: string; channel: Channel; on: boolean | null }) => client.setChoice(category, channel, on),
+    onMutate: async ({ category, channel, on }) => {
+      await queryClient.cancelQueries({ queryKey: key });
+      const before = queryClient.getQueryData<ChannelChoices>(key);
+      const next: ChannelChoices = { ...(before ?? {}) };
+      const row = { ...(next[category] ?? {}) };
+      if (on === null) delete row[channel];
+      else row[channel] = on;
+      next[category] = row;
+      queryClient.setQueryData(key, next);
+      return { before };
+    },
+    onError: (_e, _v, context) => queryClient.setQueryData(key, context?.before),
+    // Read back through `choices()` (which folds in 0005's category switches), never the raw row the save returns.
+    onSettled: () => queryClient.invalidateQueries({ queryKey: key }),
+  });
+  const rows = useMemo(() => preferenceRows(registry, query.data ?? {}), [registry, query.data]);
+  return {
+    rows,
+    status: query.isError ? "error" : query.isSuccess ? "ready" : "loading",
+    error: ((query.error ?? save.error) as Error | null) ?? null,
+    saving: save.isPending,
+    set: async (category, channel, on) => {
+      const row = rows.find((r) => r.id === category);
+      if (!row || !row.channels.includes(channel) || (row.critical && on === false)) return;
+      await save.mutateAsync({ category, channel, on });
+    },
+  };
+}
+
+export { notificationsClient, type NotificationsClient } from "../supabase/index";

package/src/runner/index.ts

@@ -0,0 +1,299 @@
+/**
+ * `@marktiderman/genesis-notifications/runner`: the one outbox runner. Claim a
+ * batch of due jobs, send them (grouped, so a destination that takes many at
+ * once gets one request), and record what happened. No dependencies.
+ *
+ * The store is the caller's (a SQL outbox claimed with SKIP LOCKED, a
+ * queue): `claim` hands over leased jobs and `record` takes back outcomes.
+ * The runner owns the rest: turning each send result into an outcome with a
+ * retry time, jittered backoff, the deferral cap, and never throwing for one
+ * job's failure. The notifier's push and email channels run on it, and so do
+ * genesis-forms' destinations (Sheets, webhooks), each with its own claim.
+ *
+ * Outcomes:
+ * - `sent`: delivered (or already there, on a redelivery: `alreadyThere`).
+ * - `filtered`: the sender decided it doesn't apply; nothing sent, nothing to retry.
+ * - `skipped`: deliberately not sent (`notSent`: a reason safe to store); never retried.
+ * - `retry`: a retryable failure. With the service's own Retry-After it is
+ *   deferred without counting an attempt (`counted: false`), until
+ *   `maxDeferrals`; otherwise it backs off by attempt (`counted: true`), until
+ *   `maxAttempts`.
+ * - `failed`: permanent, or out of attempts. With `disable: true` the receiver
+ *   asked to be switched off (a 410 Gone): stop sending to it.
+ *
+ * It never logs content, addresses or secrets: only what `label` gives and
+ * the senders' safe error messages.
+ *
+ * @packageDocumentation
+ */
+
+/** One claimed job. Extend it with what your sender needs. */
+export interface RunnerJob {
+  /** Stable across retries (an idempotency key is made from it). */
+  id: string;
+  /** This attempt's number, from 1. */
+  attempt: number;
+  /** Deferrals so far (outcomes with `counted: false`); pass it back so `maxDeferrals` holds. Default 0. */
+  deferrals?: number | undefined;
+  /** An earlier attempt may have gone through (its lease ran out): senders that can look first do. */
+  redelivery?: boolean | undefined;
+}
+
+/** What a sender says about one job. */
+export type JobResult =
+  | {
+      ok: true;
+      /** Deliberately sent nothing; the reason, safe to store. Recorded as `skipped`. */
+      notSent?: string | undefined;
+      /** It was already there (a redelivery), so nothing was sent this time. */
+      alreadyThere?: boolean | undefined;
+    }
+  | JobFailure;
+
+export interface JobFailure {
+  ok: false;
+  /** The same request may succeed later (rate limited, the service down, a timeout). */
+  retryable: boolean;
+  /** The service said when to come back: retry after this many seconds, without counting an attempt. */
+  retryAfterSeconds?: number | undefined;
+  status?: number | undefined;
+  /** The receiver asked to be switched off. Always with `retryable: false`. */
+  disable?: true | undefined;
+  /** Safe to store and log: never secrets, content or addresses. */
+  error: string;
+}
+
+export type JobOutcome =
+  | { status: "sent"; alreadyThere?: boolean }
+  | { status: "filtered" }
+  | { status: "skipped"; reason: string }
+  | {
+      status: "retry";
+      error: string;
+      retryAt: Date;
+      retryAfterSeconds: number;
+      /** Whether this attempt counts toward `maxAttempts`. False when the service said when to come back. */
+      counted: boolean;
+      httpStatus?: number;
+    }
+  | { status: "failed"; error: string; httpStatus?: number; disable?: true };
+
+export interface RunReport {
+  claimed: number;
+  sent: number;
+  filtered: number;
+  skipped: number;
+  /** Retryable failures, backed off by attempt. */
+  retrying: number;
+  /** Retryable failures the service said when to retry; no attempt used. */
+  deferred: number;
+  failed: number;
+  /** Recorded after the claim was lost (`record` resolved false). */
+  stale: number;
+  /** `record` threw. */
+  unrecorded: number;
+}
+
+export interface ClaimRequest<Filter> {
+  limit: number;
+  filter?: Filter | undefined;
+}
+
+export interface SendContext {
+  signal?: AbortSignal | undefined;
+}
+
+export interface RunnerOptions<J extends RunnerJob, Filter = undefined> {
+  /** Claims up to `limit` due jobs, each leased so no other runner sends it meanwhile. */
+  claim(request: ClaimRequest<Filter>): Promise<readonly J[]>;
+  /**
+   * Sends one group of jobs (those with the same `group` key) and resolves one
+   * result per job, in order, or `"filtered"`. A throw fails the whole group
+   * with a retryable error.
+   */
+  send(group: readonly J[], context: SendContext): Promise<readonly (JobResult | "filtered")[]>;
+  /** Jobs with the same key are sent together. Default: each job alone. */
+  group?: ((job: J) => string) | undefined;
+  /**
+   * Records an outcome. Resolve `false` when the claim was no longer held: it
+   * is counted as stale. A rejection is counted as unrecorded; the lease runs
+   * out and the job comes back on its own.
+   */
+  record(job: J, outcome: JobOutcome): Promise<void | boolean>;
+  now?: (() => number) | undefined;
+  /** Safe lines (ids, kinds, short reasons). Default: nothing is logged. */
+  log?: ((message: string) => void) | undefined;
+  /** How a job is named in a log line, capitalised ("Delivery d1 (email)"). Default `Job <id>`. */
+  label?: ((job: J) => string) | undefined;
+  /** How a job is named when recording it failed ("delivery d1"). Default `job <id>`. */
+  recordLabel?: ((job: J) => string) | undefined;
+  /** Jobs claimed per run. Default 25. */
+  batchSize?: number | undefined;
+  /** Counted attempts before a retryable failure is given up. Default 8. */
+  maxAttempts?: number | undefined;
+  /** Deferrals allowed before a further one counts as an attempt. Default 24. */
+  maxDeferrals?: number | undefined;
+  /** Seconds to wait after a counted failed attempt. Default `defaultBackoff`. */
+  backoff?: ((attempt: number) => number) | undefined;
+}
+
+export interface RunOptions<Filter> {
+  filter?: Filter | undefined;
+  /** Overrides `batchSize` for this run. */
+  limit?: number | undefined;
+  /** Aborts the sends in flight. */
+  signal?: AbortSignal | undefined;
+}
+
+export interface Runner<Filter = undefined> {
+  /** One claim, its sends and their records. Never rejects for a job's failure; a failing `claim` rejects. */
+  run(options?: RunOptions<Filter>): Promise<RunReport>;
+}
+
+export const DEFAULT_MAX_ATTEMPTS = 8;
+export const DEFAULT_MAX_DEFERRALS = 24;
+export const DEFAULT_BATCH_SIZE = 25;
+
+/**
+ * 5 minutes, quadrupling each attempt, at most 24 hours: 5m, 20m, 80m, 5h20m,
+ * 21h20m, then 24h; about 3 days across 8 attempts. Each wait is jittered by
+ * up to ±20%, so jobs that failed together don't all come back at once.
+ */
+export function defaultBackoff(attempt: number, random?: () => number): number {
+  const nominal = Math.min(24 * 3600, 300 * 4 ** Math.max(0, attempt - 1));
+  // A function only: `[1, 2].map(defaultBackoff)` passes an index here.
+  const r = typeof random === "function" ? random() : Math.random();
+  return Math.round(nominal * (0.8 + 0.4 * Math.min(1, Math.max(0, r))));
+}
+
+/** Turns a send result into an outcome for a job on its `attempt`. */
+export function jobOutcome(
+  result: JobResult,
+  attempt: number,
+  options: {
+    now?: number | undefined;
+    maxAttempts?: number | undefined;
+    backoff?: ((attempt: number) => number) | undefined;
+    deferrals?: number | undefined;
+    maxDeferrals?: number | undefined;
+  } = {},
+): JobOutcome {
+  if (result.ok) {
+    if (result.notSent) return { status: "skipped", reason: result.notSent.slice(0, 500) };
+    return result.alreadyThere ? { status: "sent", alreadyThere: true } : { status: "sent" };
+  }
+  const http = result.status !== undefined ? { httpStatus: result.status } : {};
+  if (result.disable) return { status: "failed", error: result.error, ...http, disable: true };
+  if (!result.retryable) return { status: "failed", error: result.error, ...http };
+  const now = options.now ?? Date.now();
+  if (result.retryAfterSeconds !== undefined && (options.deferrals ?? 0) < (options.maxDeferrals ?? DEFAULT_MAX_DEFERRALS)) {
+    const seconds = Math.max(1, Math.ceil(result.retryAfterSeconds));
+    return { status: "retry", error: result.error, retryAt: new Date(now + seconds * 1000), retryAfterSeconds: seconds, counted: false, ...http };
+  }
+  const max = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+  if (attempt >= max) return { status: "failed", error: `${result.error} (gave up after ${attempt} attempts)`.slice(0, 500), ...http };
+  const seconds = Math.max(1, Math.ceil((options.backoff ?? defaultBackoff)(attempt)));
+  return { status: "retry", error: result.error, retryAt: new Date(now + seconds * 1000), retryAfterSeconds: seconds, counted: true, ...http };
+}
+
+/** A thrown error as a retryable failure with a safe message. */
+export function failureOf(error: unknown): JobFailure {
+  const e = error as { name?: unknown; message?: unknown; retryable?: unknown; retryAfterSeconds?: unknown; status?: unknown; disable?: unknown } | null;
+  if (e && typeof e === "object" && typeof e.retryable === "boolean" && typeof e.message === "string") {
+    return {
+      ok: false,
+      retryable: e.disable === true ? false : e.retryable,
+      error: e.message.slice(0, 500),
+      ...(typeof e.retryAfterSeconds === "number" ? { retryAfterSeconds: e.retryAfterSeconds } : {}),
+      ...(typeof e.status === "number" ? { status: e.status } : {}),
+      ...(e.disable === true ? { disable: true as const } : {}),
+    };
+  }
+  const timeout = e && typeof e === "object" && (e.name === "TimeoutError" || e.name === "AbortError");
+  return { ok: false, retryable: true, error: timeout ? "Timed out" : "Unexpected error" };
+}
+
+/**
+ * The runner.
+ *
+ * @stability Beta
+ */
+export function createRunner<J extends RunnerJob, Filter = undefined>(options: RunnerOptions<J, Filter>): Runner<Filter> {
+  const log = (message: string): void => {
+    try {
+      options.log?.(message);
+    } catch {
+      // A logger that throws never stops an outcome being recorded.
+    }
+  };
+  const label = (job: J) => options.label?.(job) ?? `Job ${job.id}`;
+  const recordLabel = (job: J) => options.recordLabel?.(job) ?? `job ${job.id}`;
+  const now = () => options.now?.() ?? Date.now();
+
+  return {
+    async run(runOptions: RunOptions<Filter> = {}): Promise<RunReport> {
+      const report: RunReport = { claimed: 0, sent: 0, filtered: 0, skipped: 0, retrying: 0, deferred: 0, failed: 0, stale: 0, unrecorded: 0 };
+      const limit = runOptions.limit ?? options.batchSize ?? DEFAULT_BATCH_SIZE;
+      const claimed = await options.claim({ limit, filter: runOptions.filter });
+      report.claimed = claimed.length;
+
+      const groups = new Map<string, J[]>();
+      claimed.forEach((job, i) => {
+        const key = options.group ? options.group(job) : `\u0000${i}`;
+        const list = groups.get(key) ?? [];
+        list.push(job);
+        groups.set(key, list);
+      });
+
+      await Promise.all(
+        [...groups.values()].map(async (group) => {
+          let results: readonly (JobResult | "filtered")[];
+          try {
+            results = await options.send(group, { signal: runOptions.signal });
+            if (results.length !== group.length) throw new Error("send answered the wrong number of results");
+          } catch (error) {
+            const failure = failureOf(error);
+            results = group.map(() => failure);
+          }
+          const at = now();
+          await Promise.all(
+            group.map(async (job, i) => {
+              const result = results[i]!;
+              const outcome: JobOutcome =
+                result === "filtered"
+                  ? { status: "filtered" }
+                  : jobOutcome(result, job.attempt, {
+                      now: at,
+                      maxAttempts: options.maxAttempts,
+                      backoff: options.backoff,
+                      deferrals: job.deferrals,
+                      maxDeferrals: options.maxDeferrals,
+                    });
+              if (outcome.status === "failed" || outcome.status === "retry") {
+                log(`${label(job)} ${outcome.status === "failed" ? "failed" : "will be retried"}: ${outcome.error}`);
+              } else if (outcome.status === "skipped") {
+                log(`${label(job)} skipped: ${outcome.reason}`);
+              }
+              let recorded: void | boolean;
+              try {
+                recorded = await options.record(job, outcome);
+              } catch {
+                report.unrecorded++;
+                log(`Recording ${recordLabel(job)} failed`);
+                return;
+              }
+              if (recorded === false) report.stale++;
+              else if (outcome.status === "sent") report.sent++;
+              else if (outcome.status === "filtered") report.filtered++;
+              else if (outcome.status === "skipped") report.skipped++;
+              else if (outcome.status === "failed") report.failed++;
+              else if (outcome.counted) report.retrying++;
+              else report.deferred++;
+            }),
+          );
+        }),
+      );
+      return report;
+    },
+  };
+}

package/src/server/crypto.ts

@@ -0,0 +1,44 @@
+/** Small WebCrypto helpers (Node 20+, Deno, browsers, workers). */
+const encoder = new TextEncoder();
+
+export function base64url(bytes: Uint8Array): string {
+  let s = "";
+  for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+export function fromBase64url(text: string): Uint8Array {
+  const s = text.replace(/-/g, "+").replace(/_/g, "/");
+  const bin = atob(s + "=".repeat((4 - (s.length % 4)) % 4));
+  return Uint8Array.from(bin, (c) => c.charCodeAt(0));
+}
+
+export function fromBase64(text: string): Uint8Array {
+  const bin = atob(text);
+  return Uint8Array.from(bin, (c) => c.charCodeAt(0));
+}
+
+export function toBase64(bytes: Uint8Array): string {
+  let s = "";
+  for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s);
+}
+
+export async function hmacSha256(key: Uint8Array | string, message: string): Promise<Uint8Array> {
+  const raw = typeof key === "string" ? encoder.encode(key) : key;
+  const k = await crypto.subtle.importKey("raw", raw as BufferSource, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  return new Uint8Array(await crypto.subtle.sign("HMAC", k, encoder.encode(message)));
+}
+
+export async function sha256Hex(text: string): Promise<string> {
+  const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", encoder.encode(text)));
+  return [...digest].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+/** Equal bytes, in time that doesn't depend on where they differ. */
+export function timingSafeEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a[i]! ^ b[i]!;
+  return diff === 0;
+}

package/src/server/dns.ts

@@ -0,0 +1,106 @@
+/**
+ * Is a sender domain the tenant's, and ready to send from? An ownership TXT
+ * record holding the tenant's own token (so one tenant can't verify another's
+ * domain), SPF on Resend's return-path host, DKIM at Resend's selector, and a
+ * DMARC record, read through DNS over HTTPS so it runs anywhere `fetch` does.
+ * The app's own shared sending domains (and anything under them) are never a
+ * tenant's.
+ */
+import { timedFetch, type HttpDeps } from "./errors";
+
+export interface DomainCheck {
+  /** `_genesis-notifications.<domain>` holds `genesis-notifications-verify=<token>`. */
+  ownership: boolean;
+  spf: boolean;
+  dkim: boolean;
+  dmarc: boolean;
+  /** The domain is (or is under) one of the app's own shared domains: never a tenant's. */
+  reserved: boolean;
+  /** Owned, all three records, and not reserved. */
+  ok: boolean;
+}
+
+export interface DomainCheckOptions extends HttpDeps {
+  /** The sender's `domain_token` (from `notification_senders`; made when the domain was set). */
+  token: string;
+  /** The app's shared sending domains (`email.domains`): a tenant may never verify one, or one under it. */
+  reservedDomains: readonly string[];
+  /** Default Cloudflare's JSON resolver. */
+  resolver?: string;
+  /** Resend's DKIM selector. Default `resend`. */
+  dkimSelector?: string;
+  /** Where the SPF record lives. Default `send.<domain>` (Resend's return path). */
+  spfHost?: string;
+  /** What the SPF record includes. Default `amazonses.com` (Resend's). */
+  spfInclude?: string;
+}
+
+const DOMAIN = /^([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/;
+
+/** The ownership record's host. */
+export const SENDER_OWNERSHIP_HOST = "_genesis-notifications";
+
+/**
+ * The TXT record a tenant adds to prove `domain` is theirs: show it beside
+ * Resend's SPF and DKIM records in your sender settings.
+ *
+ * @stability Beta
+ */
+export function senderOwnershipRecord(domain: string, token: string): { type: "TXT"; name: string; value: string } {
+  return { type: "TXT", name: `${SENDER_OWNERSHIP_HOST}.${domain}`, value: `genesis-notifications-verify=${token}` };
+}
+
+/** Whether `domain` is one of `reserved`, or under one. */
+export function isReservedDomain(domain: string, reserved: readonly (string | undefined | null)[]): boolean {
+  const d = domain.toLowerCase().replace(/\.$/, "");
+  return reserved.some((r) => {
+    const x = r?.toLowerCase().replace(/\.$/, "");
+    return !!x && (d === x || d.endsWith(`.${x}`));
+  });
+}
+
+async function txt(options: DomainCheckOptions, name: string): Promise<string[]> {
+  const url = new URL(options.resolver ?? "https://cloudflare-dns.com/dns-query");
+  url.searchParams.set("name", name);
+  url.searchParams.set("type", "TXT");
+  const response = await timedFetch(options, url.toString(), { headers: { accept: "application/dns-json" } });
+  if (!response.ok) return [];
+  const json = (await response.json()) as { Answer?: { type?: number; data?: string }[] };
+  return (json.Answer ?? [])
+    .filter((a) => a.type === 16 && typeof a.data === "string")
+    // A TXT answer comes quoted, maybe in several strings: "v=spf1 " "include:…"
+    .map((a) => a.data!.replace(/"\s*"/g, "").replace(/^"|"$/g, ""));
+}
+
+/**
+ * Checks ownership, SPF, DKIM and DMARC for `domain`. Record the result with
+ * `genesis_notifications_set_sender_dns(tenant, domain, token, ok ? 'verified' : 'failed', result)`
+ * with the same token, so a check made before the tenant changed its domain changes nothing.
+ *
+ * @stability Beta
+ */
+export async function checkSenderDomain(domain: string, options: DomainCheckOptions): Promise<DomainCheck> {
+  if (!DOMAIN.test(domain)) throw new Error("checkSenderDomain: not a domain name");
+  if (typeof options?.token !== "string" || !/^[0-9a-f]{32}$/.test(options.token)) throw new Error("checkSenderDomain: token is the sender's domain_token");
+  if (!Array.isArray(options.reservedDomains) || options.reservedDomains.length === 0) {
+    throw new Error("checkSenderDomain: reservedDomains (the app's shared sending domains) is required");
+  }
+  const reserved = isReservedDomain(domain, options.reservedDomains);
+  if (reserved) return { ownership: false, spf: false, dkim: false, dmarc: false, reserved: true, ok: false };
+  const include = options.spfInclude ?? "amazonses.com";
+  const proof = senderOwnershipRecord(domain, options.token);
+  const [owner, spf, dkim, dmarc] = await Promise.all([
+    txt(options, proof.name),
+    txt(options, options.spfHost ?? `send.${domain}`),
+    txt(options, `${options.dkimSelector ?? "resend"}._domainkey.${domain}`),
+    txt(options, `_dmarc.${domain}`),
+  ]);
+  const result = {
+    ownership: owner.some((r) => r.trim() === proof.value),
+    spf: spf.some((r) => /^v=spf1\b/i.test(r) && r.toLowerCase().includes(`include:${include}`)),
+    dkim: dkim.some((r) => /(^|;)\s*p=[A-Za-z0-9+/=]{20,}/.test(r)),
+    dmarc: dmarc.some((r) => /^v=DMARC1\b/i.test(r)),
+    reserved: false,
+  };
+  return { ...result, ok: result.ownership && result.spf && result.dkim && result.dmarc };
+}