create-ailk 0.23.0 → 0.25.1

package/templates/apps/api/src/services/plan-offerings.ts

@@ -1,125 +0,0 @@
-/**
- * The workspace's offerings as plan keys (#8514 D9) — moved here unchanged
- * from `routes/workspaces/plan.ts` by #8757 D4, so the magnet PATCH's
- * save-time offering check and the lead route's submit-time re-check
- * (`services/magnet-completion.ts`) read the same list `GET …/plan-offerings`
- * serves.
- *
- * Two sources (#8934, spec
- * docs/specs/8934-re-source-the-plan-offerings-spec.md D1–D4):
- *
- * - A connected workspace with the `commerce` claim lists its Offerings
- *   shown set (`getWorkspaceShownSet`, read from the database and never from
- *   Stripe — contract T7): one item per sellable Price, in the reader's
- *   order, `key` the Price's full lookup key (G5), `name` the product name
- *   and its billing word, `type` the product's group. The page list is not
- *   consulted.
- * - An unclaimed workspace, or one the reader answers `null` for (no
- *   workspace, no connection, no selection), lists its OWN Service then
- *   Product pages: `key` is the page slug's last segment when it is an
- *   offering key (else the page is skipped), the first page per key wins, at
- *   most 200; `name` is the page title. Off the database content adapter only
- *   the default workspace has content (`workspaceContentAdapter`), so every
- *   other workspace reads `[]`.
- *
- * Never throws: a failed read answers `{ failed }` with a fixed word or the
- * error's class name only, so a caller can tell "none listed" from "could not
- * tell" — a failure is never a pass. `LicenseUndetermined` (the licence could
- * not be read, so the Offerings services may not be called — 8876 D10),
- * `OfferingsSnapshotExpired` and `OfferingsSnapshotEmpty` (the rows say what
- * is shown, but no current snapshot says which keys it sells).
- *
- * Base tree (SEC-8757-D): no `oss: false` marker and no `MODULE_SLICES`
- * entry, because the never-gate lead route reaches it.
- */
-import {
-  PLAN_OFFERINGS_MAX,
-  planOfferingSchema,
-  type PlanOfferingItem,
-} from "@working-theory/validation";
-
-import { resolveCommerceClaim } from "../lib/require-commerce-claim.js";
-
-import { getWorkspaceShownSet } from "./offerings/index.js";
-import { workspaceContentAdapter } from "./public-site-resolver.js";
-
-/** `planOfferingItemSchema.name`'s bound, in UTF-16 units. */
-const NAME_MAX = 200;
-
-/** The workspace's offerings as plan keys (D3). */
-export async function listPlanOfferings(
-  workspaceId: string,
-): Promise<PlanOfferingItem[] | { failed: string }> {
-  try {
-    const claim = await resolveCommerceClaim();
-    if (claim === "undetermined") return { failed: "LicenseUndetermined" };
-    if (claim === "unclaimed") return await pageOfferings(workspaceId);
-    const shown = await getWorkspaceShownSet(workspaceId);
-    if (shown === null) return await pageOfferings(workspaceId);
-    if (shown.state === "expired") return { failed: "OfferingsSnapshotExpired" };
-    if (shown.state === "empty") return { failed: "OfferingsSnapshotEmpty" };
-    return collect(
-      shown.offerings.flatMap((offering) =>
-        offering.prices.map((price) => ({
-          key: price.lookupKey,
-          name: planOfferingName(offering.name, price.interval),
-          type: offering.ailkGroup,
-        })),
-      ),
-    );
-  } catch (error) {
-    // The error's class name only — never its message, which may name a slug.
-    return { failed: error instanceof Error ? error.name : typeof error };
-  }
-}
-
-/** The workspace's Service then Product pages as plan keys (D4, #8514 D9). */
-async function pageOfferings(workspaceId: string): Promise<PlanOfferingItem[]> {
-  const adapter = await workspaceContentAdapter(workspaceId);
-  if (!adapter) return [];
-  const [services, products] = await Promise.all([
-    adapter.listPages("Service"),
-    adapter.listPages("Product"),
-  ]);
-  const typed = [
-    ...services.map((page) => ({ page, type: "service" as const })),
-    ...products.map((page) => ({ page, type: "product" as const })),
-  ];
-  return collect(
-    typed.map(({ page, type }) => ({
-      key: page.slug.split("/").filter(Boolean).pop() ?? "",
-      name: page.title.trim().slice(0, NAME_MAX),
-      type,
-    })),
-  );
-}
-
-/** The guards both sources share: a valid key, a name, each key once, at most 200. */
-function collect(candidates: PlanOfferingItem[]): PlanOfferingItem[] {
-  const offerings: PlanOfferingItem[] = [];
-  const seen = new Set<string>();
-  for (const { key, name, type } of candidates) {
-    if (offerings.length >= PLAN_OFFERINGS_MAX) break;
-    if (!planOfferingSchema.safeParse(key).success || name === "" || seen.has(key)) continue;
-    seen.add(key);
-    offerings.push({ key, name, type });
-  }
-  return offerings;
-}
-
-/**
- * `<product name> (<word>)`, the word from the Price's interval (D2). Whole
- * code points are dropped from the end of the product name until the name
- * fits `NAME_MAX` units, so a surrogate pair is never split; the word is
- * always kept.
- */
-function planOfferingName(productName: string, interval: "month" | "year" | null): string {
-  const word = interval === "month" ? "Monthly" : interval === "year" ? "Annual" : "One-time";
-  const suffix = ` (${word})`;
-  let name = "";
-  for (const point of productName) {
-    if (name.length + point.length + suffix.length > NAME_MAX) break;
-    name += point;
-  }
-  return name + suffix;
-}

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

@@ -1,326 +0,0 @@
-/**
- * @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",
-    );
-  });
-}