@softure-ai/mailing 0.0.0-stage → 0.1.5

package/src/server/suppressions.ts

@@ -0,0 +1,77 @@
+// The suppression list: who unsubscribed from list mail. Rows hold the recipient key, never the
+// address. Writes are idempotent (a second opt-out keeps the first row), so a mail client that
+// retries its one-click POST, or a person who clicks twice, changes nothing. A verified unsubscribe
+// also runs the app's `onUnsubscribed` hook in the same transaction; a new explicit consent lifts
+// the recipient's own opt-out (`liftSuppression`).
+import { err, ok, type ModuleContext, type Result } from "@softure-ai/core";
+import type { Queryable } from "@softure-ai/db";
+import { and, eq, inArray } from "drizzle-orm";
+import type { SuppressionSource, UnsubscribeErrorCode } from "../contract.js";
+import { suppressions } from "../schema.js";
+import { getMailingOptions } from "./options.js";
+import { getRecipientKey, readUnsubscribeSecrets, verifyUnsubscribeToken, type Env, type UnsubscribeToken } from "./unsubscribe-link.js";
+
+export type SuppressionContext = ModuleContext<Queryable>;
+
+/** Whether `address` unsubscribed. Throws on a database failure: callers decide how to fail. */
+export async function isSuppressed(ctx: Pick<SuppressionContext, "db">, address: string): Promise<boolean> {
+  const rows = await ctx.db
+    .select({ recipientKey: suppressions.recipientKey })
+    .from(suppressions)
+    .where(eq(suppressions.recipientKey, getRecipientKey(address)))
+    .limit(1);
+  return rows.length > 0;
+}
+
+/** Records an opt-out by recipient key. Throws on a database failure. */
+async function recordSuppression(ctx: SuppressionContext, recipientKey: string, source: SuppressionSource): Promise<void> {
+  await ctx.db.insert(suppressions).values({ recipientKey, source, createdAt: ctx.clock.now() }).onConflictDoNothing();
+}
+
+/**
+ * Unsubscribes `address` from list mail, for an operator's script or another module (a bounce or
+ * complaint handler). Throws on a database failure.
+ */
+export async function suppressRecipient(ctx: SuppressionContext, address: string, source: SuppressionSource = "operator"): Promise<void> {
+  await recordSuppression(ctx, getRecipientKey(address), source);
+}
+
+/** The opt-outs a recipient made themselves; only these can be lifted by a new consent. */
+const OWN_SOURCES: readonly SuppressionSource[] = ["one-click", "page"];
+
+/**
+ * Lifts the opt-out of `address` when the recipient made it themselves (`page`, `one-click`), for a
+ * module that just recorded their new explicit consent, in that consent's transaction. An
+ * `operator` row (a bounce, a complaint, a script) stays. Returns whether a row was lifted.
+ * Throws on a database failure.
+ */
+export async function liftSuppression(ctx: Pick<SuppressionContext, "db">, address: string): Promise<boolean> {
+  const lifted = await ctx.db
+    .delete(suppressions)
+    .where(and(eq(suppressions.recipientKey, getRecipientKey(address)), inArray(suppressions.source, [...OWN_SOURCES])))
+    .returning();
+  return lifted.length > 0;
+}
+
+/**
+ * Unsubscribes the recipient of a signed link and runs `onUnsubscribed` in the same transaction,
+ * also when the recipient had already unsubscribed (a retried one-click heals a missed hook). The
+ * signature is checked before the database is touched; a link that does not verify is
+ * `mailing.invalid_link`. Throws on a database failure or when the hook throws (nothing is stored).
+ */
+export async function unsubscribe(
+  ctx: SuppressionContext,
+  token: UnsubscribeToken | null,
+  source: Exclude<SuppressionSource, "operator">,
+  env: Env = process.env,
+): Promise<Result<undefined, UnsubscribeErrorCode>> {
+  if (token === null || !verifyUnsubscribeToken(token, readUnsubscribeSecrets(env))) return err("mailing.invalid_link");
+  const { onUnsubscribed } = getMailingOptions(ctx.config);
+  const { recipientKey } = token;
+  await ctx.db.transaction(async (tx) => {
+    const txCtx: SuppressionContext = { ...ctx, db: tx };
+    await recordSuppression(txCtx, recipientKey, source);
+    await onUnsubscribed?.({ recipientKey, source }, txCtx);
+  });
+  return ok();
+}

package/src/server/unsubscribe-link.ts

@@ -0,0 +1,109 @@
+// Signed unsubscribe links. Ported from FIRE_TRACKER `src/lib/unsubscribe-link.ts`, with two
+// changes: the link carries a hash of the address instead of a waitlist row id (the module has no
+// recipient table, and the address never appears in a URL), and a previous secret keeps verifying
+// during a rotation. The whole link is a credential: whoever has it can unsubscribe that address,
+// so it never reaches a log, an error or a result.
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+import type { SoftureConfig } from "@softure-ai/core";
+import { getMailingRoutes } from "./options.js";
+
+/** Signs every new link and verifies. */
+export const UNSUBSCRIBE_SECRET_ENV = "MAILING_UNSUBSCRIBE_SECRET";
+/** Optional: verifies links signed before a rotation, never signs. */
+export const UNSUBSCRIBE_PREVIOUS_SECRET_ENV = "MAILING_UNSUBSCRIBE_SECRET_PREVIOUS";
+/** A shorter secret counts as missing: a guessable key lets anyone mint links. */
+export const MIN_UNSUBSCRIBE_SECRET_LENGTH = 32;
+
+/** The query parameters of both links. */
+export const RECIPIENT_PARAM = "r";
+export const SIGNATURE_PARAM = "t";
+
+/**
+ * Domain separation: the same key signing anything else can never produce a valid unsubscribe
+ * signature. Changing it voids every link already sent, exactly like changing the key.
+ */
+const SIGNED_PREFIX = "softure.mailing.unsubscribe.v1:";
+
+/** 32 bytes in unpadded base64url. */
+const TOKEN_PATTERN = /^[A-Za-z0-9_-]{43}$/;
+
+export type Env = Readonly<Record<string, string | undefined>>;
+
+/** The key pair a link carries: the recipient key and its signature. */
+export interface UnsubscribeToken {
+  readonly recipientKey: string;
+  readonly signature: string;
+}
+
+/** Both links of one mail: the same token, two targets. */
+export interface UnsubscribeLinks {
+  /** The page with a button, for the mail's footer (opening it changes nothing). */
+  readonly page: string;
+  /** The RFC 8058 one-click target, for the `List-Unsubscribe` header. */
+  readonly oneClick: string;
+}
+
+/** The secrets in use: `current` signs, both verify. `current` is null when it is not set. */
+export interface UnsubscribeSecrets {
+  readonly current: string | null;
+  readonly previous: string | null;
+}
+
+/**
+ * The stored and linked identity of an address: base64url SHA-256 of the trimmed, lowercased
+ * address. Lowercasing the local part merges `Ada@` and `ada@`, which errs on the side of not
+ * mailing someone who opted out.
+ */
+export function getRecipientKey(address: string): string {
+  return createHash("sha256").update(address.trim().toLowerCase()).digest("base64url");
+}
+
+/** The signature of a recipient key. */
+export function signRecipientKey(recipientKey: string, secret: string): string {
+  return createHmac("sha256", secret).update(`${SIGNED_PREFIX}${recipientKey}`).digest("base64url");
+}
+
+/** The secrets from the environment; one shorter than 32 characters reads as not set. */
+export function readUnsubscribeSecrets(env: Env = process.env): UnsubscribeSecrets {
+  return { current: readSecret(env[UNSUBSCRIBE_SECRET_ENV]), previous: readSecret(env[UNSUBSCRIBE_PREVIOUS_SECRET_ENV]) };
+}
+
+function readSecret(value: string | undefined): string | null {
+  return value !== undefined && value.length >= MIN_UNSUBSCRIBE_SECRET_LENGTH ? value : null;
+}
+
+/**
+ * Whether the token was signed by the current or the previous secret. Never throws: the shape is
+ * checked first (`timingSafeEqual` throws on buffers of different lengths, and a throw would be a
+ * second, faster answer), then every secret is compared in constant time.
+ */
+export function verifyUnsubscribeToken(token: UnsubscribeToken, secrets: UnsubscribeSecrets): boolean {
+  if (!TOKEN_PATTERN.test(token.recipientKey) || !TOKEN_PATTERN.test(token.signature)) return false;
+  const candidate = Buffer.from(token.signature, "base64url");
+  let isValid = false;
+  for (const secret of [secrets.current, secrets.previous]) {
+    if (secret === null) continue;
+    const expected = Buffer.from(signRecipientKey(token.recipientKey, secret), "base64url");
+    // No early exit: both comparisons run whichever matches.
+    isValid = timingSafeEqual(candidate, expected) || isValid;
+  }
+  return isValid;
+}
+
+/** The two links for `address`, on the app's origin and the module's routes. */
+export function buildUnsubscribeLinks(config: SoftureConfig, address: string, secret: string): UnsubscribeLinks {
+  const recipientKey = getRecipientKey(address);
+  const query = new URLSearchParams({ [RECIPIENT_PARAM]: recipientKey, [SIGNATURE_PARAM]: signRecipientKey(recipientKey, secret) });
+  const routes = getMailingRoutes(config);
+  return {
+    page: `${config.appOrigin}${routes.unsubscribe}?${query.toString()}`,
+    oneClick: `${config.appOrigin}${routes.oneClick}?${query.toString()}`,
+  };
+}
+
+/** The token in a link's query (or a form), when both parameters are present once. */
+export function readUnsubscribeToken(params: { get(name: string): unknown }): UnsubscribeToken | null {
+  const recipientKey = params.get(RECIPIENT_PARAM);
+  const signature = params.get(SIGNATURE_PARAM);
+  return typeof recipientKey === "string" && typeof signature === "string" ? { recipientKey, signature } : null;
+}

package/src/server/validate-mail.ts

@@ -0,0 +1,68 @@
+// The boundary check of `sendMail`: a mail and its options are parsed before anything leaves the
+// process. Failures name the fields, never their values (an address is personal data).
+import { z } from "zod";
+import { hasLineBreak, isHeaderName, isIdempotencyKey, isListMailHeader, isMailKind, isReservedHeader, isSingleAddress, MAX_SUBJECT_LENGTH } from "../address.js";
+import { TRANSACTIONAL_KIND } from "../contract.js";
+
+const headersSchema = z.record(z.string(), z.string()).superRefine((headers, context) => {
+  for (const [name, value] of Object.entries(headers)) {
+    if (!isHeaderName(name) || isReservedHeader(name) || hasLineBreak(value)) {
+      context.addIssue({ code: "custom", message: "invalid or reserved header" });
+    }
+  }
+});
+
+const mailSchema = z.object({
+  to: z.string().trim().refine(isSingleAddress),
+  subject: z
+    .string()
+    .refine((subject) => subject.trim() !== "" && subject.length <= MAX_SUBJECT_LENGTH && !hasLineBreak(subject)),
+  text: z.string().refine((text) => text.trim() !== ""),
+  html: z
+    .string()
+    .refine((html) => html.trim() !== "")
+    .optional(),
+  headers: headersSchema.optional(),
+  kind: z.string().refine(isMailKind).default(TRANSACTIONAL_KIND),
+}).superRefine((mail, context) => {
+  // The module writes these two on list mail; a second, unsigned copy would confuse clients.
+  if (mail.kind !== TRANSACTIONAL_KIND && Object.keys(mail.headers ?? {}).some(isListMailHeader)) {
+    context.addIssue({ code: "custom", path: ["headers"], message: "list mail gets its unsubscribe headers from the module" });
+  }
+});
+
+const optionsSchema = z.object({
+  idempotencyKey: z.string().refine(isIdempotencyKey).optional(),
+});
+
+export interface ValidMail {
+  readonly to: string;
+  readonly subject: string;
+  readonly text: string;
+  readonly html: string | null;
+  readonly headers: Readonly<Record<string, string>>;
+  /** `transactional` or a list kind. */
+  readonly kind: string;
+  readonly idempotencyKey: string | null;
+}
+
+export type MailValidation = { readonly ok: true; readonly value: ValidMail } | { readonly ok: false; readonly fields: readonly string[] };
+
+/**
+ * Checks one mail and its send options. `fields` lists what failed (`to`, `subject`, `text`,
+ * `html`, `headers`, `kind`, `idempotencyKey`, or `mail` when the input is not an object).
+ */
+export function validateMail(mail: unknown, options: unknown = {}): MailValidation {
+  const parsedMail = mailSchema.safeParse(mail);
+  const parsedOptions = optionsSchema.safeParse(options ?? {});
+  if (!parsedMail.success || !parsedOptions.success) {
+    const issues = [...(parsedMail.error?.issues ?? []), ...(parsedOptions.error?.issues ?? [])];
+    const fields = new Set(issues.map((issue) => (issue.path.length === 0 ? "mail" : String(issue.path[0]))));
+    return { ok: false, fields: [...fields] };
+  }
+  const { to, subject, text, html, headers, kind } = parsedMail.data;
+  return {
+    ok: true,
+    value: { to, subject, text, html: html ?? null, headers: headers ?? {}, kind, idempotencyKey: parsedOptions.data.idempotencyKey ?? null },
+  };
+}

package/src/testing/fake-provider.ts

@@ -0,0 +1,66 @@
+// A provider that sends nothing: it captures mail in memory (`provider.sent`) and, with an outbox
+// file, appends each mail as one JSON line for a test in another process (an e2e against
+// `next start`). It honours idempotency keys like a real provider: a repeated key answers the
+// first id and captures nothing new.
+import { appendFile } from "node:fs/promises";
+import type { MailProvider, ProviderMessage, ProviderOutcome } from "../contract.js";
+
+/** A captured mail: what the provider received, with the id it answered. */
+export interface CapturedMail extends ProviderMessage {
+  readonly id: string;
+}
+
+export interface FakeMailProviderOptions {
+  /** A file to append each captured mail to, as one JSON line (`readMailOutbox` reads it). */
+  readonly outboxFile?: string;
+  /**
+   * Decides the outcome per mail, to test failure handling. Return `undefined` (or omit the
+   * option) to accept the mail.
+   */
+  readonly respond?: (message: ProviderMessage) => Exclude<ProviderOutcome, { status: "sent" }> | undefined;
+}
+
+export interface FakeMailProvider extends MailProvider {
+  /** Every mail accepted so far, oldest first. */
+  readonly sent: readonly CapturedMail[];
+  /** Forgets the captured mail and the idempotency keys. */
+  clear(): void;
+}
+
+export function fakeMailProvider(options: FakeMailProviderOptions = {}): FakeMailProvider {
+  const sent: CapturedMail[] = [];
+  const idsByKey = new Map<string, string>();
+  let counter = 0;
+
+  return {
+    name: "fake",
+    get sent() {
+      return [...sent];
+    },
+    clear() {
+      sent.length = 0;
+      idsByKey.clear();
+    },
+    async send(message) {
+      if (options.outboxFile === undefined && process.env.NODE_ENV === "production") {
+        // In memory, production mail would vanish without a trace.
+        console.error("mailing: fakeMailProvider() refuses to run in production without an outboxFile; configure a real provider");
+        return { status: "unavailable" };
+      }
+      const refusal = options.respond?.(message);
+      if (refusal !== undefined) return refusal;
+
+      const knownId = message.idempotencyKey === null ? undefined : idsByKey.get(message.idempotencyKey);
+      if (knownId !== undefined) return { status: "sent", id: knownId };
+
+      counter += 1;
+      const captured: CapturedMail = { ...message, headers: { ...message.headers }, id: `fake-${String(counter)}-${crypto.randomUUID()}` };
+      if (options.outboxFile !== undefined) {
+        await appendFile(options.outboxFile, `${JSON.stringify(captured)}\n`, "utf8");
+      }
+      sent.push(captured);
+      if (message.idempotencyKey !== null) idsByKey.set(message.idempotencyKey, captured.id);
+      return { status: "sent", id: captured.id };
+    },
+  };
+}

package/src/testing/index.ts

@@ -0,0 +1,4 @@
+// Test helpers of @softure-ai/mailing: a provider that captures mail instead of sending it, and a
+// reader for its outbox file. Server-only (it writes files).
+export { fakeMailProvider, type CapturedMail, type FakeMailProvider, type FakeMailProviderOptions } from "./fake-provider.js";
+export { readMailOutbox } from "./outbox.js";

package/src/testing/outbox.ts

@@ -0,0 +1,32 @@
+// Reads the outbox file of `fakeMailProvider({ outboxFile })`, e.g. from a Playwright test.
+import { readFile } from "node:fs/promises";
+import { z } from "zod";
+import type { CapturedMail } from "./fake-provider.js";
+
+const capturedMailSchema = z.object({
+  id: z.string(),
+  from: z.string(),
+  to: z.string(),
+  replyTo: z.string().nullable(),
+  subject: z.string(),
+  text: z.string(),
+  html: z.string().nullable(),
+  headers: z.record(z.string(), z.string()),
+  idempotencyKey: z.string().nullable(),
+});
+
+/** Every mail in the outbox, oldest first, optionally only those to `to`. A missing file is an empty outbox. */
+export async function readMailOutbox(file: string, filter: { readonly to?: string } = {}): Promise<CapturedMail[]> {
+  let text: string;
+  try {
+    text = await readFile(file, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw error;
+  }
+  return text
+    .split("\n")
+    .filter((line) => line !== "")
+    .map((line) => capturedMailSchema.parse(JSON.parse(line)))
+    .filter((mail) => filter.to === undefined || mail.to === filter.to);
+}