@pithy-sh/email 0.1.0

package/src/capability.ts

@@ -0,0 +1,385 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import { type Capability, defineCapability } from "@pithy-sh/core/src/capability/capability";
+import { InternalError } from "@pithy-sh/core/src/error/pithyError";
+import type { LocaleCatalogs } from "@pithy-sh/core/src/i18n/catalog";
+import { z } from "zod";
+import { createBounceHandler } from "./bounce/handler";
+import { emailSigningRegistry } from "./crypto/signingKey";
+import {
+  type EmailSuppressionDatabase,
+  emailDatabase,
+  emailSuppressionDatabase,
+  emailSuppressionTables,
+  emailTables,
+} from "./data/tables";
+import { registerCallbacks } from "./http/callbacks";
+import { emailAdminRoutes } from "./http/guards";
+import { registerEmailAdminRoutes } from "./http/routes";
+import { email_0001_init } from "./migrations/0001_init";
+import { email_0001_suppressions } from "./migrations/0001_suppressions";
+import { DevMailDelivery } from "./provision/devDelivery";
+import { emailHostCatalogs } from "./provision/hostCatalogs";
+import { emailSettings } from "./provision/settingsCheck";
+import { type EnqueueInput, type EnqueueResult, enqueueEmail } from "./send/enqueue";
+import { type EmailSenderEnv, emailSenderBinding } from "./send/senderBinding";
+import { EMAIL_MESSAGES, type EmailMessageLayers, kitEmailLayers } from "./templates/messages";
+import { CustomTheme, type EmailTheme, resolveTheme } from "./templates/theme";
+import { PACKAGE_VERSION } from "./version.generated";
+import { EmailScheduleParams, EmailSendParams } from "./workflows/params";
+
+/**
+ * The bindings the enqueue seam reads from the request env: the shared `DB`, the send Workflow, and the
+ * global suppression database. A consumer (e.g. `@pithy-sh/auth`) forwards its worker env; it never
+ * names these bindings itself.
+ *
+ * **`EMAIL_SUPPRESSIONS` is on this list, and that is the whole of pithy-sh/pithy#355.** The wiring is
+ * not the adopter's problem: the capability declares the binding, `pithy add email` provisions it,
+ * `enqueue` reads it off the env, and no consumer config, route option, or constant names it. What an
+ * adopter *may* do — because it is their database — is ask for it back through
+ * {@link EmailCapability.suppressions} and read or write it like any other table.
+ */
+export interface EmailEnqueueEnv extends EmailSenderEnv {
+  DB: D1Database;
+  /**
+   * The global, durable suppression list.
+   *
+   * Optional in the type for the same reason `EMAIL_SENDER` is — a hand-built env in a test harness has
+   * neither — and required in practice: it is in `requiredBindings` below, so `validateBindings` refuses
+   * the first request of a composed worker that lacks it. Absent, `enqueue` queues the job and
+   * `runSend` still refuses a blocked recipient before anything leaves.
+   */
+  EMAIL_SUPPRESSIONS?: D1Database;
+}
+
+/**
+ * Sort order of the email migrations within the app database, relative to other capabilities
+ * (core low, app high). Unique per database; the migration registry composes the key
+ * `0200_email_0001_init`.
+ */
+export const EMAIL_MIGRATION_ORDER = 200;
+
+/** Sort order of the suppression migration within the dedicated `EMAIL_SUPPRESSIONS` database. */
+export const EMAIL_SUPPRESSIONS_MIGRATION_ORDER = 100;
+
+/**
+ * Configuration for the email capability, passed in `pithy.config.ts` — the thin user-owned surface.
+ * `fromAddress` and `baseUrl` are required; branding is one `theme` preset plus an optional
+ * `customTheme` that deep-merges over it (so a project tweaks just an accent or a palette color, not a
+ * dozen fields). Body width is intentionally *not* here — it is a property of each template (newsletters
+ * render wide, transactional narrow). The resolved theme is attached to the capability and serialized
+ * into the email worker's single `EMAIL_THEME` var at provision.
+ */
+export const EmailConfig = z
+  .object({
+    fromAddress: z
+      .string()
+      .describe("The address every email is sent from. Must use a domain onboarded onto Cloudflare Email Service."),
+    fromName: z.string().default("Pithy").describe("The sender display name recipients see."),
+    baseUrl: z
+      .string()
+      .describe("The public base URL of the app worker; tracking and unsubscribe links are built against it."),
+    basePath: z
+      .string()
+      .startsWith("/")
+      .default("/email")
+      .describe(
+        "Where the management routes mount (the send log and the suppression list). Not the callback links: those keep their fixed `/_pithy/email` prefix, because a tracking URL is already minted into mail sitting in somebody's inbox and moving it would break every link ever sent.",
+      ),
+    theme: z
+      .enum(["saffron", "midnight", "forest", "rose"])
+      .default("saffron")
+      .describe("The off-the-shelf theme preset to start from: `saffron` (default), `midnight`, `forest`, or `rose`."),
+    customTheme: CustomTheme.optional().describe(
+      "A partial override deep-merged over the preset — change any theme field, inherit the rest.",
+    ),
+    // KNOWN DEFECT — this value never reaches the worker. `EmailConfigParams` carries no
+    // `schedulerEnabled`, so `resolveEmailConfig` never writes `SCHEDULER_ENABLED` and the template's
+    // hardcoded "true" always wins. Setting it false is silently ignored. Wiring it through means an
+    // eighth `resolveEmailConfig` param and a new `CloudflareEmailProvisioner` option, both of which
+    // are pinned by tests this change may not edit — so it is filed, not fixed here.
+    schedulerEnabled: z.boolean().default(true).describe("Whether the every-minute scheduler Workflow runs."),
+    devDelivery: DevMailDelivery.default("remote").describe(
+      "What the prebuilt email host does with a message when it is running on your machine under `pithy dev`. **The default, `remote`, sends real mail:** the Worker runs locally and delivers through Cloudflare Email Service, so a magic link you trigger from localhost arrives in the real inbox, with the same DKIM and the same delivery logs as production. That needs a Cloudflare login `wrangler dev` can use and a sending domain already onboarded onto Email Service. Set it to `simulator` to send nothing — `wrangler dev` logs the sender, recipient and subject and writes the rendered HTML and text bodies to disk, which is what an offline machine and CI want. It changes local development only; every deployed environment always sends for real.",
+    ),
+  })
+  .describe("Configuration for the email capability.");
+export type EmailConfig = z.output<typeof EmailConfig>;
+export type EmailConfigInput = z.input<typeof EmailConfig>;
+
+/** The resolved from identity, base URL, and theme — what the app's enqueue calls need. */
+export interface ResolvedEmailConfig {
+  fromAddress: string;
+  fromName: string;
+  baseUrl: string;
+  schedulerEnabled: boolean;
+  /**
+   * What the host's `send_email` binding does under `pithy dev` — `remote` (real mail, the default)
+   * or `simulator`. Attached here because `pithy dev` reads it off the composed capability when it
+   * resolves the host's local config; nothing inside the app worker consults it.
+   */
+  devDelivery: DevMailDelivery;
+  theme: EmailTheme;
+}
+
+/** The email capability, with its resolved config and a bound enqueue seam attached. */
+export interface EmailCapability extends Capability {
+  emailConfig: ResolvedEmailConfig;
+  /**
+   * Enqueue an email job from a request env. The capability owns the `DB`/`EMAIL_SENDER` bindings, the
+   * from-identity, and the theme — a consumer passes only its worker env and the high-level input
+   * (`to`, `template`, `payload`). This is the seam other capabilities depend on; they never assemble
+   * `EnqueueDeps` or name the email bindings themselves.
+   */
+  enqueue: (env: EmailEnqueueEnv, input: EnqueueInput) => Promise<EnqueueResult>;
+  /**
+   * The suppression list, from a request env — **it is the adopter's database, and this is how they open
+   * it** (pithy-sh/pithy#355).
+   *
+   * Nobody has to call this to be protected: `enqueue` consults the list on its own and `runSend`
+   * refuses a blocked recipient regardless. This exists for the adopter who genuinely wants to look —
+   * an operator un-suppressing an address a customer has fixed, a support screen explaining why a letter
+   * did not go, a report of who a notice could not reach. Reading and writing it is ordinary Kysely over
+   * `pithyEmailSuppressions`; `send/suppression.ts` publishes `blockingSuppression`, `suppress`,
+   * `unsuppress` and `listSuppressions` for the four things anybody actually does with it.
+   *
+   * It takes the env and no binding name, which is the point: the capability owns which binding the list
+   * lives behind, exactly as it owns `DB` and `EMAIL_SENDER`.
+   */
+  suppressions: (env: EmailEnqueueEnv) => EmailSuppressionDatabase;
+  /**
+   * The catalogs `pithy email provision` stamps into the host worker's `EMAIL_MESSAGES` var.
+   *
+   * A function rather than a field, and read after composition rather than at construction, for the
+   * reason the `compose` hook below exists at all: a capability sees only itself when it is built, and
+   * the translations belong to a capability that may be composed after this one. A snapshot taken in
+   * the returned object literal would be the pre-compose English, permanently — the same trap
+   * `@pithy-sh/i18n` names on its own `composedMessages` accessor.
+   *
+   * Empty when nothing composed an i18n capability, which is what a project serving one language wants:
+   * no var is written and the host renders the English it bundles.
+   */
+  hostCatalogs: () => LocaleCatalogs;
+}
+
+/**
+ * The email capability. It contributes the three email tables to the app `DB`, mounts the
+ * click/open/unsubscribe callback routes, and registers the inbound bounce/complaint `email()` handler.
+ * It requires the `DB` binding and the `EMAIL_SENDER` Workflow binding (to start an immediate send at
+ * enqueue). The send and scheduler Workflows and the every-minute cron live in the prebuilt email
+ * worker (`workflows/worker.ts`), deployed per environment by `pithy add email`.
+ */
+export function email(config: EmailConfigInput): EmailCapability {
+  const resolved = EmailConfig.parse(config);
+  // Build the full theme from the preset, deep-merging any customTheme override.
+  const theme = resolveTheme(resolved.theme, resolved.customTheme);
+  /**
+   * Where an enqueue finds words for a locale — this package's own English until `compose` says
+   * otherwise.
+   *
+   * Reassigned rather than resolved once at construction, because a capability sees only itself when it
+   * is built and the translations belong to a capability that may be composed after this one.
+   */
+  let layersFor: EmailMessageLayers = kitEmailLayers;
+  /**
+   * The locales the project told the i18n capability it serves — the keys `pithy email provision`
+   * flattens a catalog for.
+   *
+   * `layersFor` alone cannot answer this. It is a function of a locale, so it can say what `es` reads
+   * and never that `es` is one of the languages this project speaks; the set lives on the i18n
+   * capability's own config, and this is the only thing that knows it.
+   */
+  let supportedLocales: readonly string[] = [];
+  const capability = defineCapability({
+    name: "email",
+    // The package version this capability ships at, stamped by `scripts/stampVersions.ts` — a Worker
+    // cannot read its own package.json. Reported per capability by the control-plane manifest.
+    version: PACKAGE_VERSION,
+    // The link-signing key is read through @pithy-sh/secrets, so the secrets capability must be
+    // composed; createBackend fails fast if it isn't (rather than 500-ing each link-signing request).
+    dependsOn: ["secrets"],
+    // The slice of secrets email reads — aggregated into the shared per-invocation accessor at startup.
+    secretRegistry: emailSigningRegistry,
+    /**
+     * This capability's own copy — the seven templates whose words the kit owns, plus the shell's
+     * severity vocabulary and its opt-out link. All under `email/`, which `composeMessages` enforces.
+     *
+     * **In every language it is written in, not English alone (#442).** The send Worker is a separate
+     * deploy with no request and no config, so anything it does not bundle is stamped into it as a
+     * variable — and the kit's own translations were doing that on every provision run. Held here,
+     * they are built into the host and only an adopter's diff travels.
+     *
+     * A kit sentence still lives in exactly one place; which package that is follows how it reaches a
+     * reader. `@pithy-sh/i18n` keeps what no capability can — the error taxonomy, whose domains are
+     * not capability names, and the screens, which are copied rather than imported.
+     */
+    messages: EMAIL_MESSAGES,
+    /**
+     * Take the composed project's catalog layers, when it has any.
+     *
+     * Duck-typed, and deliberately not an import. `@pithy-sh/i18n` is optional — a project composing
+     * only `email` must not acquire it as a dependency — and CLAUDE.md's rule is that capabilities
+     * depend on core seams rather than on each other. `layersFor` is that seam's shape
+     * (`(locale) => catalogs`), declared in `@pithy-sh/core`'s i18n module and published by the i18n
+     * capability, so recognizing it structurally is the whole of the coupling.
+     *
+     * What arrives is the full stack in the right order: the adopter's overrides, the kit's
+     * translation, every composed capability's English. Absent, {@link kitEmailLayers} answers and a
+     * project sends what it always sent.
+     */
+    compose: ({ capabilities }) => {
+      for (const composed of capabilities) {
+        if (composed.name !== "i18n") continue;
+        const candidate = (composed as { layersFor?: unknown }).layersFor;
+        if (typeof candidate === "function") layersFor = candidate as EmailMessageLayers;
+        // Duck-typed on the same terms as `layersFor`: `i18nConfig.supportedLocales` is the shape the
+        // i18n capability publishes, and recognizing it structurally is the whole of the coupling.
+        const locales = (composed as { i18nConfig?: { supportedLocales?: unknown } }).i18nConfig?.supportedLocales;
+        if (Array.isArray(locales)) supportedLocales = locales.filter((tag) => typeof tag === "string");
+      }
+    },
+    // Email provisioning wires inbound bounce routing (Email Routing rules), so the CI credential that
+    // provisions email needs that scope — contributed into the one `ci-system` token.
+    ciPermissions: ["email:routing"],
+    requiredBindings: [
+      { type: "d1", name: "DB" },
+      { type: "d1", name: "EMAIL_SUPPRESSIONS" },
+      { type: "workflow", name: "EMAIL_SENDER" },
+    ],
+    databases: {
+      app: {
+        binding: "DB",
+        tables: emailTables,
+        migrationOrder: EMAIL_MIGRATION_ORDER,
+        migrations: { "0001_init": email_0001_init },
+      },
+      emailSuppressions: {
+        binding: "EMAIL_SUPPRESSIONS",
+        tables: emailSuppressionTables,
+        migrationOrder: EMAIL_SUPPRESSIONS_MIGRATION_ORDER,
+        migrations: {
+          "0001_suppressions": email_0001_suppressions,
+        },
+      },
+    },
+    /**
+     * The two durable jobs email owns. Both classes live in the prebuilt email worker
+     * (`workflows/worker.ts`), never in the app worker — the app only ever dispatches into `send`.
+     *
+     * The map keys are the wire names: `workflowScriptName("email", "send", "staging")` resolves to
+     * `pithy-email-send-staging`, which is byte-for-byte what the committed template already deploys.
+     * Declaring them here is what lets the CLI generate the host's `workflows` array and its cron from
+     * the specs instead of a hand-maintained block that can drift from this file.
+     */
+    workflows: {
+      send: {
+        binding: "EMAIL_SENDER",
+        className: "EmailSendWorkflow",
+        // The same object the host's own registry and its dispatch route validate against
+        // (`workflows/params.ts`). One schema, three readers: what the app dispatches, what the host
+        // deploys, and what a loopback dispatch is checked against at the door (#410).
+        params: EmailSendParams,
+      },
+      schedule: {
+        binding: "EMAIL_SCHEDULER",
+        className: "EmailSchedulerWorkflow",
+        params: EmailScheduleParams,
+        schedule: "* * * * *",
+        // Optional because the binding exists only on the prebuilt email worker, which self-fires it
+        // from its cron. An app worker binds EMAIL_SENDER and nothing else, so deriving a required
+        // EMAIL_SCHEDULER binding would fail every app's first request.
+        optional: true,
+      },
+    },
+    /**
+     * Two route trees, one hook.
+     *
+     * The public callbacks keep their fixed `/_pithy/email` prefix — those URLs are already minted into
+     * mail nobody can recall — and the management routes mount under the configured `basePath`. They
+     * are registered together here rather than being two capabilities, because they are one
+     * capability's surface and `adminRoutes` below has to describe what this exact composition mounted.
+     */
+    routes: (app) => {
+      registerCallbacks(app);
+      registerEmailAdminRoutes({ basePath: resolved.basePath })(app);
+    },
+    /**
+     * The management surface, advertised on `GET /control-plane/manifest`.
+     *
+     * Built from the **resolved** `basePath` — the same value `registerEmailAdminRoutes` mounts
+     * against, read once. A default here and a default there is how a manifest comes to describe a
+     * route tree nobody serves.
+     */
+    adminRoutes: emailAdminRoutes(resolved.basePath),
+    /**
+     * How `pithy doctor` checks that these settings **work**, not merely that they are written (#411).
+     *
+     * Built from the resolved config, on the instance, so discovery needs no `pithy.manifest.json` and no
+     * import of this package by the CLI. The local half runs `workflows/hostEnv.ts` — the very declaration
+     * the prebuilt host refuses to start without — so doctor and the host cannot come to two answers.
+     */
+    settings: emailSettings({ fromAddress: resolved.fromAddress, baseUrl: resolved.baseUrl, theme }),
+    email: createBounceHandler(),
+  });
+  /**
+   * The suppression list off an env, or a wiring fault naming the binding.
+   *
+   * **Fails closed, unlike the enqueue-time check.** The two are asked different questions. `enqueue`
+   * asks "is this address blocked", and where it cannot ask, the send path asks again before anything
+   * leaves — so queueing the job is right. A caller here has asked for the list itself, and the only
+   * alternatives to raising are handing back a fabricated database or an empty answer that reads as
+   * "nobody is suppressed". Both are worse than a message naming what to bind.
+   */
+  const suppressions = (env: EmailEnqueueEnv): EmailSuppressionDatabase => {
+    const binding = env.EMAIL_SUPPRESSIONS;
+    if (!binding) {
+      throw new InternalError({
+        message: "The suppression list is not available.",
+        action: "Run `pithy add email` to provision it, or bind the EMAIL_SUPPRESSIONS D1 database.",
+        detail: "email.suppressions() was called with an env carrying no `EMAIL_SUPPRESSIONS` D1 binding.",
+      });
+    }
+    return emailSuppressionDatabase(binding);
+  };
+  const enqueue = (env: EmailEnqueueEnv, input: EnqueueInput): Promise<EnqueueResult> =>
+    enqueueEmail(
+      {
+        db: emailDatabase(env.DB),
+        fromAddress: resolved.fromAddress,
+        fromName: resolved.fromName,
+        theme,
+        // Read through the closure, not captured: `compose` runs after this function is defined and
+        // before any request reaches it, so a snapshot taken here would be the pre-compose English.
+        layersFor: (locale) => layersFor(locale),
+        sender: emailSenderBinding(env),
+        // Read straight off the env the consumer forwarded. This one line is what makes suppression
+        // automatic: a consumer names nothing, and a hard-bounced address is never queued for a send.
+        suppressionDb: env.EMAIL_SUPPRESSIONS ? emailSuppressionDatabase(env.EMAIL_SUPPRESSIONS) : undefined,
+        now: new Date(),
+        newId: () => crypto.randomUUID(),
+      },
+      input,
+    );
+  return Object.assign(capability, {
+    emailConfig: {
+      fromAddress: resolved.fromAddress,
+      fromName: resolved.fromName,
+      baseUrl: resolved.baseUrl,
+      schedulerEnabled: resolved.schedulerEnabled,
+      devDelivery: resolved.devDelivery,
+      theme,
+    },
+    enqueue,
+    suppressions,
+    // Read through the closures, never captured — `compose` runs after this object is built, and both
+    // values it fills are the whole point of the call.
+    hostCatalogs: () => emailHostCatalogs(supportedLocales, (locale) => layersFor(locale)),
+  });
+}
+
+/** Whether a capability is the email capability — carries its resolved config. */
+export function isEmailCapability(capability: Capability): capability is EmailCapability {
+  return capability.name === "email" && "emailConfig" in capability;
+}

package/src/cloudflare-test.d.ts

@@ -0,0 +1,19 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/// <reference types="@cloudflare/vitest-plugin/types" />
+
+// Bindings the Workers-runtime test project provides to `*.workers.test.ts`, matching the Miniflare
+// config in `vitest.workers.config.ts`: the app `DB` database the email tables live in, and the
+// dedicated `SECRETS` database plus master key the link-signing key's row is read through.
+// `cloudflare:test` types its `env` as `Cloudflare.Env`, so test bindings are declared by augmenting
+// that interface.
+declare namespace Cloudflare {
+  interface Env {
+    DB: D1Database;
+    EMAIL_SUPPRESSIONS: D1Database;
+    SECRETS: D1Database;
+    /** The master-key config as a string (the `.dev.vars` shape), set in `vitest.workers.config.ts`. */
+    SECRETS_ENCRYPTION_KEYS: string;
+  }
+}

package/src/crypto/signingKey.ts

@@ -0,0 +1,44 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { SecretsStoreEnv } from "@pithy-sh/secrets/src/env/bindings";
+import { defineSecretRegistry } from "@pithy-sh/secrets/src/registry";
+import type { VersionedSecret } from "@pithy-sh/secrets/src/secretsStore";
+import { sharedSecretsStore } from "@pithy-sh/secrets/src/sharedSecretsStore";
+
+/**
+ * The link-signing key lives in `@pithy-sh/secrets` as a rotatable, global secret. Email resolves it
+ * by name through its own minimal registry — `secretsStore` reads the same encrypted D1 row regardless
+ * of which registry names it, so email never needs the project-wide registry to sign or verify a link.
+ */
+export const EMAIL_LINK_SIGNING_KEY = "email-link-signing-key";
+
+/** The minimal registry email uses to resolve its signing key. Rotatable so old links verify after rotation. */
+export const emailSigningRegistry = defineSecretRegistry({
+  // Mintable for dev: the key signs links this app both mints and verifies, so any random string
+  // serves. Nothing else names it, so without `devValue` the first tracked link is the first anyone
+  // hears of it — and by then the mail is in an inbox.
+  [EMAIL_LINK_SIGNING_KEY]: {
+    backend: "d1",
+    scope: "global",
+    rotatable: true,
+    valueType: "text",
+    devValue: "random",
+    // Arbitrary in production for the same reason it is arbitrary in dev: this app mints the links and
+    // this app verifies them. So it is `minted` in every environment, and `local` to replace.
+    origin: { kind: "minted", recipe: { kind: "random", bytes: 32, encoding: "base64url" } },
+    rotation: { kind: "local" },
+  },
+});
+
+/**
+ * Resolve the current signing key plus every still-valid prior version. The current version is the
+ * `kid` new tokens are signed with; the full version set is what `verifyToken` checks a token's `kid`
+ * against, so a link minted before a rotation still verifies until its version is pruned.
+ */
+export async function resolveSigningKeys(
+  env: SecretsStoreEnv,
+): Promise<VersionedSecret<(typeof emailSigningRegistry)[typeof EMAIL_LINK_SIGNING_KEY]>> {
+  const secrets = await sharedSecretsStore(env, emailSigningRegistry);
+  return secrets.getVersions(EMAIL_LINK_SIGNING_KEY);
+}

package/src/crypto/token.ts

@@ -0,0 +1,148 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { EmailInvalidTokenError } from "../error/errors";
+
+/**
+ * HMAC-signed callback tokens. Click, open, and unsubscribe links carry one of these so a callback
+ * is tamper-proof: the claims (which job, which recipient, where a click goes, which campaign) are
+ * signed, and the signature is verified constant-time via `crypto.subtle.verify` before the callback
+ * acts. The signing secret is a **rotatable** key from `@pithy-sh/secrets`; every token records the
+ * key version (`kid`) it was signed with, so a link in a months-old email still verifies against the
+ * retained version set after a rotation — and is rejected once that version is pruned.
+ */
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+export const TokenKind = z
+  .enum(["click", "open", "unsubscribe"])
+  .describe("Which callback a token authorizes: a tracked link `click`, an open-pixel `open`, or an `unsubscribe`.");
+export type TokenKind = z.output<typeof TokenKind>;
+
+/** The signed claims a callback token carries. `kid`/`exp`/`v` are set by `mintToken`; the rest are caller claims. */
+export const CallbackToken = z
+  .object({
+    v: z.literal(1).describe("Token format version, so the scheme can evolve without ambiguity."),
+    kid: z.string().describe("The signing-key version this token was signed with; selects the key to verify against."),
+    kind: TokenKind.describe("Which callback this token authorizes."),
+    jobId: z.string().describe("The `pithy_email_jobs.id` this token is bound to."),
+    recipient: z.string().describe("The recipient address the callback is recorded against."),
+    exp: z.number().int().describe("Expiry as a Unix timestamp in seconds; the callback rejects a token past it."),
+    destination: z
+      .string()
+      .optional()
+      .describe("For a `click` token, the absolute URL to 302-redirect to after recording."),
+    linkLabel: z
+      .string()
+      .optional()
+      .describe("For a `click` token, the link's identity/label, recorded for attribution."),
+    campaignId: z.string().optional().describe("The marketing campaign this token is attributed to, when applicable."),
+  })
+  .describe("The signed claims carried by an email callback token (click/open/unsubscribe).");
+export type CallbackToken = z.output<typeof CallbackToken>;
+
+/** The caller-supplied claims for a token — everything except the fields `mintToken` fills in. */
+export type TokenClaims = Omit<CallbackToken, "v" | "kid" | "exp">;
+
+function base64UrlEncode(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function base64UrlDecode(value: string): Uint8Array {
+  const padded = value.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - (value.length % 4)) % 4);
+  const binary = atob(padded);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+async function importKey(secret: string): Promise<CryptoKey> {
+  return crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, [
+    "sign",
+    "verify",
+  ]);
+}
+
+/**
+ * Mint a signed token. The claims plus `kid`/`exp`/`v` are JSON-encoded and base64url-packed, then
+ * HMAC-SHA-256 signed with `key`. The token is `<payload>.<signature>`; `kid` rides inside the signed
+ * payload so the verifier knows which key to check without trusting an unsigned header.
+ */
+export async function mintToken(
+  claims: TokenClaims,
+  options: { key: string; kid: string; expiresAt: Date },
+): Promise<string> {
+  const payload: CallbackToken = {
+    v: 1,
+    kid: options.kid,
+    exp: Math.floor(options.expiresAt.getTime() / 1000),
+    ...claims,
+  };
+  const payloadB64 = base64UrlEncode(encoder.encode(JSON.stringify(payload)));
+  const key = await importKey(options.key);
+  const signature = new Uint8Array(await crypto.subtle.sign("HMAC", key, encoder.encode(payloadB64)));
+  return `${payloadB64}.${base64UrlEncode(signature)}`;
+}
+
+/**
+ * Verify a token against the valid signing-key version set (`@pithy-sh/secrets`' `getVersions` shape)
+ * and return its claims. Rejects — as `email/invalid_token` — a malformed token, an unknown/pruned
+ * `kid`, a bad signature (constant-time via `crypto.subtle.verify`), or an expired token. The order
+ * is deliberate: structure, then signature, then expiry, so a forged token never reaches the expiry
+ * check.
+ */
+export async function verifyToken(
+  token: string,
+  keys: { versions: Record<string, string> },
+  now: Date,
+): Promise<CallbackToken> {
+  const parts = token.split(".");
+  if (parts.length !== 2 || !parts[0] || !parts[1]) {
+    throw new EmailInvalidTokenError({ detail: "token is not in <payload>.<signature> form" });
+  }
+  const [payloadB64, signatureB64] = parts;
+
+  let raw: unknown;
+  try {
+    raw = JSON.parse(decoder.decode(base64UrlDecode(payloadB64)));
+  } catch (cause) {
+    throw new EmailInvalidTokenError({ detail: "token payload is not valid base64url JSON" }, { cause });
+  }
+
+  const parsed = CallbackToken.safeParse(raw);
+  if (!parsed.success) {
+    throw new EmailInvalidTokenError({ detail: "token payload does not match the claim schema" });
+  }
+
+  // Look the key up as an OWN property only — a bracket lookup with an attacker-controlled `kid`
+  // like `__proto__`/`constructor` would otherwise resolve up the prototype chain to a truthy
+  // non-string (Object.prototype / the Object function), pass an `if (!secret)` check, and let
+  // `importKey` coerce it to a fixed, attacker-known key string — forging the signature. The
+  // own-property + string-type checks close that off.
+  const versions = keys.versions;
+  const secret = Object.hasOwn(versions, parsed.data.kid) ? versions[parsed.data.kid] : undefined;
+  if (typeof secret !== "string") {
+    throw new EmailInvalidTokenError({ detail: `token kid '${parsed.data.kid}' is not in the valid key set` });
+  }
+
+  const key = await importKey(secret);
+  let valid: boolean;
+  try {
+    valid = await crypto.subtle.verify("HMAC", key, base64UrlDecode(signatureB64), encoder.encode(payloadB64));
+  } catch (cause) {
+    throw new EmailInvalidTokenError({ detail: "token signature could not be decoded" }, { cause });
+  }
+  if (!valid) {
+    throw new EmailInvalidTokenError({ detail: "token signature did not verify" });
+  }
+
+  if (parsed.data.exp * 1000 <= now.getTime()) {
+    throw new EmailInvalidTokenError({ detail: "token has expired" });
+  }
+
+  return parsed.data;
+}

package/src/data/emailEvent.ts

@@ -0,0 +1,42 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
+import { z } from "zod";
+import { EmailEventType } from "./enums";
+
+/**
+ * One row in `pithy_email_events` — a per-recipient event for history and campaign attribution. The
+ * send path, the click/open/unsubscribe callbacks, and the inbound bounce handler all append here.
+ * `z.output` is the app shape; `z.input` is the SQLite row.
+ */
+export const EmailEvent = z
+  .object({
+    id: z.number().int().describe("Surrogate primary key, autoincremented by SQLite."),
+    jobId: z.string().describe("The `pithy_email_jobs.id` this event belongs to."),
+    recipient: z.string().describe("The recipient address the event is about."),
+    type: EmailEventType.describe(
+      "What happened: sent, open, click, bounce, complaint, unsubscribe, suppressed, or failed.",
+    ),
+    linkLabel: z
+      .string()
+      .nullish()
+      .describe("For a `click` event, the link's identity/label as declared at render; null otherwise."),
+    linkUrl: z
+      .string()
+      .nullish()
+      .describe("For a `click` event, the destination URL that was followed; null otherwise."),
+    campaignId: z
+      .string()
+      .nullish()
+      .describe("The marketing campaign this event is attributed to; null for transactional."),
+    detail: z
+      .string()
+      .nullish()
+      .describe(
+        "Free-form context — a bounce code, the user agent on an open, the suppression reason; null when not applicable.",
+      ),
+    createdAt: SQLiteDate.describe("When the event was recorded."),
+  })
+  .describe("One per-recipient email event in `pithy_email_events`.");
+export type EmailEvent = z.output<typeof EmailEvent>;