create-ailk 0.2.0 → 0.3.0

package/templates/apps/api/src/services/deliverable-fulfillment.ts

@@ -3,6 +3,16 @@
  * @description The deliverable-fulfillment service (#3961 D3/D4/D5/D7;
  * extended #3998 D1/D3/D5; extended FEAT-074 U4b, #4718 D4).
  *
+ * NOT marked `oss: false` and NOT in signal-collectors's `ownedFiles`
+ * (module-architecture.ts), despite D-48/D6 placing this file with
+ * signal-collectors — `services/recommender-capture.ts` imports it directly
+ * and is itself reached from `server.ts` by a plain, unconditional static
+ * import today (commerce/#5364 has not yet landed the gate around it).
+ * Marking or excluding this file broke both the OSS-strip and the create-ailk
+ * starter snapshot for EVERY module, not just signal-collectors (spec §5.4
+ * escalation boundary; see module-architecture.ts's comment on this file).
+ * Revert once #5364 lands.
+ *
  * `fulfillDeliverable` is the one entry point, called from flow-engine's
  * completion branch after `routeLead` succeeds and only when the session's
  * `configSnapshot` carries a `deliverables` block (D4 — the block is opt-in

package/templates/apps/api/src/services/listing-config.ts

@@ -1,4 +1,10 @@
 /**
+ * NOT marked `oss: false` (D-48/#5366 escalation — see
+ * `routes/project-listings/me.ts`'s header comment): imported by
+ * `routes/project-listings/{start,public}.ts`, each of which ships
+ * unconditionally because `routes/project-listings/index.ts`'s multi-tenant
+ * literal `import()` forces it. Registration stays gated.
+ *
  * @file listing-config.ts
  * @description The per-site project-listings config read (#5033) — one
  * function, `listingConfigFor`, that resolves a site's window bounds and
@@ -53,9 +59,61 @@ export async function listingConfigFor(siteId: string): Promise<SiteListingConfi
     );
     return SITE_LISTING_CONFIG_DEFAULTS;
   }
+  warnOnDroppedField(siteId, row.data, parsed.data);
   return parsed.data;
 }
 
+/**
+ * The two `.catch(undefined)` members of `siteListingConfigSchema` are silent
+ * by construction (#5406): a malformed `resumeEmail` or `siteName` is DROPPED
+ * rather than failing the whole blob, so the site keeps its own window bounds
+ * and collected fields instead of silently reverting to the platform's more
+ * permissive defaults.
+ *
+ * Silent is the right BEHAVIOUR and the wrong OBSERVABILITY. An operator who
+ * typos a subject key gets a site that quietly stops sending the resume email
+ * with nothing anywhere saying why. This closes that: when the stored blob has
+ * the key and the parsed config does not, the drop is logged.
+ *
+ * Field NAMES only, never values — `resumeEmail` carries the site's addresses
+ * and the founder-facing copy, and this module sits on the anonymous path.
+ */
+function warnOnDroppedField(
+  siteId: string,
+  stored: unknown,
+  parsed: SiteListingConfig,
+): void {
+  if (typeof stored !== "object" || stored === null) return;
+  const raw = stored as Record<string, unknown>;
+  for (const field of ["resumeEmail", "siteName"] as const) {
+    if (raw[field] !== undefined && parsed[field] === undefined) {
+      logger.warn(
+        { siteId, field },
+        "[listing-config] stored field failed its schema and was DROPPED — the rest of this site's config still applies, but this field is not in effect",
+      );
+    }
+  }
+
+  // `resumeEmail.maxSendsPerHour` carries its OWN `.catch(undefined)` (#5414),
+  // so a bad cap is dropped while the block around it survives — which the
+  // loop above, comparing whole members, cannot see. Checked only when the
+  // block itself parsed: a dropped block is already reported once above, and
+  // reporting it twice would make the narrower line the less trustworthy one.
+  const storedEmail = raw["resumeEmail"];
+  if (
+    typeof storedEmail === "object" &&
+    storedEmail !== null &&
+    (storedEmail as Record<string, unknown>)["maxSendsPerHour"] !== undefined &&
+    parsed.resumeEmail !== undefined &&
+    parsed.resumeEmail.maxSendsPerHour === undefined
+  ) {
+    logger.warn(
+      { siteId, field: "resumeEmail.maxSendsPerHour" },
+      "[listing-config] stored field failed its schema and was DROPPED — the rest of this site's config still applies, but this field is not in effect",
+    );
+  }
+}
+
 /**
  * Resolve a site from its PUBLIC SITE KEY (#5048 D2).
  *

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",
+    );
+  });
+}