create-ailk 0.1.1 → 0.3.0

package/templates/apps/api/src/services/project-listing-resume-email.ts

@@ -0,0 +1,326 @@
+/**
+ * @file project-listing-resume-email.ts
+ * @description The founder's resume-link email, sent the moment a listing
+ * draft is created (#5406) — the API side of `sendListingResumeEmail`.
+ *
+ * It is the `onDraftStarted` email every consuming site needs and every
+ * consuming site was building for itself: salessmyth/samhenry shipped a
+ * plain-text one with its sender hardcoded in `apps/web/src/lib/resend.ts` and
+ * its wording in `messages/en.json`, so every reword needed a rebuild. Here
+ * there is nothing to rebuild — every site-facing value is read from the
+ * site's `SiteListingConfig` row on each send.
+ *
+ * OPT-IN. A site whose config carries no `resumeEmail.fromAddress` (or no
+ * `resumeEmail.baseUrl`) gets NO email. Both are deliberate rather than
+ * defaulted: Resend only sends from a domain the site has verified, and the
+ * platform does not know where a site mounted its application. Together they
+ * mean a site already sending its own resume email does not start sending two
+ * merely because it upgraded.
+ *
+ * TENANT ISOLATION. The `siteId` this reads config for comes off the DRAFT
+ * ROW, never from the request body and never from a caller argument — so the
+ * email a founder receives is always addressed and worded by the site their
+ * application was actually filed against. `start` already resolves the site
+ * server-side from a public key (#5048 D2); reading it back off the row is the
+ * belt to that braces, and is why this function takes only a listing id.
+ *
+ * RATE-BOUNDED PER RECIPIENT (PR #5411 security review, finding 1). `start` is
+ * anonymous and its IP limiter is evadable (`trustProxy` is on — see the note
+ * beside the route registration in `server.ts`), so before this change the
+ * cost of an unbounded call was one row and no outbound anything. Sending mail
+ * from the site's own verified domain to an address the CALLER typed changes
+ * that: looped, it is a mail bomb aimed at a named victim and a deliverability
+ * attack on the site's sending domain. `RESUME_EMAILS_PER_RECIPIENT_PER_WINDOW`
+ * bounds it.
+ *
+ * The cap is keyed on an UNVERIFIED identifier, which lesson 14
+ * (`docs/lessons/project-listings/14-…`) warns is a lockout weapon. Two things
+ * make it a proportionate one here, and both are deliberate: the window is one
+ * HOUR rather than forever, so any lockout clears itself; and what a
+ * suppressed send denies is only the EMAIL — `start` still returns the resume
+ * token in its 201 body, so the founder in front of the form loses nothing and
+ * completes their application as normal.
+ *
+ * RATE-BOUNDED PER SITE TOO (#5414). The bound above is per RECIPIENT, which
+ * stops a loop aimed at one victim's inbox and does nothing about a loop over a
+ * thousand strangers — each of whom receives one message from the site's own
+ * verified domain. That is the send pattern a mailbox provider reads as a list
+ * blast, and the cost lands on the site rather than on the caller: a flagged
+ * sending domain and a Resend account that can be suspended, which stops EVERY
+ * email the site sends and not only this one.
+ * `SITE_RESUME_EMAILS_PER_WINDOW` bounds the site's total over the same hour,
+ * and a site raises it for itself with `resumeEmail.maxSendsPerHour`.
+ *
+ * WHAT THE SITE BUDGET COUNTS, and its one honest cost: the DRAFTS created for
+ * the site inside the window, the same shape the per-recipient bound counts and
+ * for the same reason — this function runs exactly once per created draft, so
+ * drafts are one-to-one with emails ATTEMPTED. No new table, no migration, and
+ * the count holds across server instances because it is a database read rather
+ * than process memory.
+ *
+ * Its cost, stated at full strength because the weak form of it is misleading:
+ * a flood of drafts spends the budget even though those drafts sent no mail, so
+ * at the cap a GENUINE founder's email is suppressed too — and the cheapest way
+ * to cause that is not a mail flood at all. The per-recipient bound above
+ * returns BEFORE this count is reached, so one caller using ONE address can
+ * open cap+1 drafts, have three messages actually delivered (to their own
+ * inbox), and silence the site's resume email for the rest of the hour. The
+ * denial is cheaper than the abuse it prevents.
+ *
+ * It is accepted rather than overlooked, for the reasons lesson 14 already
+ * accepted for the per-recipient bound: the window is an hour rather than
+ * forever, so it clears itself; and what a suppressed send denies is only the
+ * EMAIL — the draft is created and the 201 still carries the resume token, so
+ * the founder in front of the form completes their application as normal. What
+ * it denies is the founder who closes the tab, for at most an hour. Narrowing
+ * it means counting SENDS rather than drafts, which needs somewhere to record a
+ * send — a schema change this issue deliberately stops short of (see the PR).
+ *
+ * PII boundary (the rule `routes/project-listings/start.ts` states in its own
+ * header): this module logs `siteId`, `listingId`, a reason, an error KIND, and
+ * the link's HOST. Never the founder's address or name, never the resume
+ * token, never the #5407 verification NONCE, and never the assembled link —
+ * which carries both. The nonce is the stricter of the two: the resume token
+ * also went out in `start`'s 201 body, but this message is the ONLY place the
+ * nonce ever leaves the server, so a log line quoting the link would not just
+ * disclose a credential, it would destroy the property the nonce exists to
+ * establish. Resend's own `error.message` is untrusted (it can quote an
+ * address), so only `error.kind` is logged.
+ */
+
+import { sendListingResumeEmail } from "@working-theory/email";
+import { logger } from "@working-theory/observability";
+
+import { prisma } from "../lib/prisma.js";
+
+import { listingConfigFor } from "./listing-config.js";
+
+/**
+ * How many resume emails one address may receive from one site within
+ * `RESUME_EMAIL_WINDOW_MS`.
+ *
+ * Three, not one: a founder who closes the tab and starts again has genuinely
+ * begun a second draft and genuinely needs a second link. Three of those in an
+ * hour is generous for a person and useless for a flood.
+ */
+const RESUME_EMAILS_PER_RECIPIENT_PER_WINDOW = 3;
+
+/**
+ * How many resume emails ONE SITE may send in total across every recipient
+ * within `RESUME_EMAIL_WINDOW_MS`, when the site has not set its own
+ * `resumeEmail.maxSendsPerHour` (#5414).
+ *
+ * Twenty, sized against a small site's real application volume rather than
+ * against an attacker: a site running this feature takes a handful of listing
+ * applications a day, so twenty inside a single HOUR is already a launch-day
+ * spike, and a site with genuine volume raises the number for itself. Sized
+ * from the other end it is a brake rather than a wall — it bounds a flood at
+ * a few hundred messages a day instead of thousands, which is the difference
+ * between a sending domain an operator can still explain and one a mailbox
+ * provider has already decided about. The operator is told when it binds.
+ *
+ * It is a platform default and deliberately not any site's terms — the same
+ * posture `siteListingConfigSchema`'s own defaults take.
+ */
+const SITE_RESUME_EMAILS_PER_WINDOW = 20;
+
+/** One hour. The cap is a rolling window so any lockout expires on its own. */
+const RESUME_EMAIL_WINDOW_MS = 60 * 60 * 1000;
+
+/**
+ * When each site's budget was last reported, so the cap logs ONCE per window
+ * rather than once per suppressed send.
+ *
+ * A line per suppressed send would hand the same caller a log-flooding
+ * primitive on top of the mail flood, which is the opposite of what this
+ * control is for. Per PROCESS rather than per deployment, so N instances emit
+ * at most N lines an hour — the CAP is what has to hold across instances (it
+ * is counted in the database), and this is only its volume knob.
+ *
+ * The key space is the deployment's configured sites, so it does not grow with
+ * traffic.
+ */
+const siteCapLastLoggedAt = new Map<string, number>();
+
+function logSiteCapOncePerWindow(siteId: string, count: number): void {
+  const now = Date.now();
+  const last = siteCapLastLoggedAt.get(siteId);
+  if (last !== undefined && now - last < RESUME_EMAIL_WINDOW_MS) return;
+  siteCapLastLoggedAt.set(siteId, now);
+  // `siteId` and the count, and a constant naming which bound fired. No
+  // address, no founder name, no resume token, no link and no LISTING ID —
+  // this line is about a site's aggregate budget, and the draft that happened
+  // to trip it identifies a person the sibling lines deliberately do not name.
+  logger.warn({ siteId, count, reason: "site_rate_limited" }, "listing-resume-email-skipped");
+}
+
+/**
+ * The link back into the application.
+ *
+ * `?draft=<id>&token=<resumeToken>&verify=<verifyNonce>` is the exact shape
+ * `ListingApplicationFlow`'s `resume` prop reads. Assembled through `URL` so a
+ * `baseUrl` that already carries a query string gains three parameters rather
+ * than a second `?`, and so every value is percent-encoded.
+ *
+ * `verify` (#5407) is the one credential THIS MESSAGE IS THE ONLY CARRIER OF.
+ * The draft id and the resume token were both in `start`'s 201 body, so the
+ * browser that filled the form already holds them; the nonce was not, and is
+ * what lets the server distinguish "someone opened this draft" from "someone
+ * read mail at this address". That makes this link the sole path between the
+ * nonce and the outside world — which is why nothing in this module logs it,
+ * and why the log line below carries the link's HOST and never its query.
+ */
+function resumeLinkFor(
+  baseUrl: string,
+  draftId: string,
+  resumeToken: string,
+  verifyNonce: string,
+): string {
+  const url = new URL(baseUrl);
+  url.searchParams.set("draft", draftId);
+  url.searchParams.set("token", resumeToken);
+  url.searchParams.set("verify", verifyNonce);
+  return url.toString();
+}
+
+/**
+ * Send the resume email for a just-created draft. Never throws, and never
+ * reports success — the caller does not wait on it (see
+ * `sendListingResumeLink` below, which is what routes actually call).
+ */
+async function send(
+  listingId: string,
+  resumeToken: string,
+  verifyNonce: string,
+): Promise<void> {
+  const row = await prisma.projectListing.findFirst({
+    where: { id: listingId },
+    // `name` is null at step one, so `{projectName}` renders empty there. It
+    // is selected anyway because this function is about a ROW, not about a
+    // moment: a later caller on a named draft substitutes a real name with no
+    // change here.
+    select: { siteId: true, founderEmail: true, name: true, founderFirstName: true },
+  });
+  if (!row) return;
+
+  const config = await listingConfigFor(row.siteId);
+  const settings = config.resumeEmail;
+
+  if (settings?.fromAddress === undefined || settings.baseUrl === undefined) {
+    logger.info(
+      {
+        siteId: row.siteId,
+        listingId,
+        reason: settings?.fromAddress === undefined ? "no_from_address" : "no_base_url",
+      },
+      "listing-resume-email-skipped",
+    );
+    return;
+  }
+
+  const windowStart = new Date(Date.now() - RESUME_EMAIL_WINDOW_MS);
+
+  // Counts the DRAFTS this address has started on this site in the window,
+  // which is one-to-one with the emails it has been sent: this function runs
+  // exactly once per created draft. `founderEmail` is already normalized
+  // (trimmed and lowercased) at write time, so the count cannot be evaded with
+  // the shift key — the fix lesson 14 records.
+  const recentForRecipient = await prisma.projectListing.count({
+    where: {
+      siteId: row.siteId,
+      founderEmail: row.founderEmail,
+      createdAt: { gt: windowStart },
+    },
+  });
+  // `>` not `>=`: the draft that triggered this send is itself in the count.
+  if (recentForRecipient > RESUME_EMAILS_PER_RECIPIENT_PER_WINDOW) {
+    logger.warn(
+      { siteId: row.siteId, listingId, reason: "recipient_rate_limited" },
+      "listing-resume-email-skipped",
+    );
+    return;
+  }
+
+  // The same count without the address clause — the site's whole outbound
+  // budget for the window (#5414). `siteId` comes off the DRAFT ROW, as every
+  // read in this function does, so one site's flood can never spend another's
+  // budget however the caller addressed the request.
+  //
+  // An invalid `maxSendsPerHour` is already `undefined` by the time it reaches
+  // here (its own `.catch(undefined)` in the schema), so a bad cap lands on the
+  // platform default rather than on zero — and `listingConfigFor` has already
+  // logged that the operator's value is not in effect.
+  const siteCap = settings.maxSendsPerHour ?? SITE_RESUME_EMAILS_PER_WINDOW;
+  const recentForSite = await prisma.projectListing.count({
+    where: { siteId: row.siteId, createdAt: { gt: windowStart } },
+  });
+  if (recentForSite > siteCap) {
+    logSiteCapOncePerWindow(row.siteId, recentForSite);
+    return;
+  }
+
+  // `maxSendsPerHour` is the API's to consume, like `baseUrl` beside it — the
+  // email package is handed COPY, and a budget is not copy.
+  const { baseUrl, maxSendsPerHour: _cap, ...copy } = settings;
+  // The HOST only (security review, finding 2). An operator who repoints
+  // `baseUrl` at a third party would otherwise exfiltrate every founder's
+  // resume token — the sole credential on their draft — with nothing anywhere
+  // recording it. The host is not a secret; the path and query are, because
+  // the query carries the token.
+  logger.info(
+    { siteId: row.siteId, listingId, linkHost: new URL(baseUrl).host },
+    "listing-resume-email-sending",
+  );
+  const result = await sendListingResumeEmail({
+    to: row.founderEmail,
+    resumeLink: resumeLinkFor(baseUrl, listingId, resumeToken, verifyNonce),
+    settings: copy,
+    variables: {
+      // The site's own display name, or absent — `{siteName}` then renders as
+      // empty text rather than as a platform name the site never chose.
+      ...(config.siteName !== undefined && { siteName: config.siteName }),
+      ...(row.name !== null && { projectName: row.name }),
+      // #5407 — `{firstName}` now has a source, and only where the founder
+      // actually gave one. `founderName` is still deliberately NOT split to
+      // guess a first name: a split on the first space is wrong for most of
+      // the world's names, and getting a founder's name wrong in the first
+      // email they receive is worse than omitting it. A row whose site asks
+      // for one display line renders `{firstName}` empty, exactly as before.
+      ...(row.founderFirstName !== null && { firstName: row.founderFirstName }),
+    },
+  });
+
+  if (!result.ok) {
+    logger.warn(
+      { siteId: row.siteId, listingId, errorKind: result.error.kind },
+      "listing resume email send failed",
+    );
+  }
+}
+
+/**
+ * Fire-and-forget entry point — what `start` calls, and what makes the 201 on
+ * that route independent of Resend.
+ *
+ * Returns `void` rather than a promise so a caller cannot accidentally
+ * `await` it, and `.catch`-guards everything: `send` above can reject (a
+ * Prisma read, a malformed `baseUrl` reaching `new URL`) where
+ * `sendListingResumeEmail` itself never does, and nothing from either may
+ * reach a route whose row is already committed.
+ *
+ * Mirrors `project-listing-decision.ts#fileIssueOnApprove`'s shape, which is
+ * the same promise on the same feature: a best-effort side effect of a write
+ * that has already landed.
+ */
+export function sendListingResumeLink(
+  listingId: string,
+  resumeToken: string,
+  verifyNonce: string,
+): void {
+  send(listingId, resumeToken, verifyNonce).catch((err: unknown) => {
+    logger.warn(
+      { listingId, errName: err instanceof Error ? err.name : "UnknownError" },
+      "listing resume email rejected unexpectedly",
+    );
+  });
+}