create-ailk 0.5.0 → 0.6.0

package/templates/apps/api/src/routes/requests/confirm.ts

@@ -0,0 +1,601 @@
+/**
+ * GET  /v1/requests/:id/confirm — the tenant's confirm form
+ * POST /v1/requests/:id/confirm — confirm, mint a Payment Link, email the buyer
+ *
+ * The pay half of request-and-confirm (#5970, D-67 / SUB-100). The tenant
+ * arrives holding a one-time link mailed to them when the request landed; they
+ * type a time and a price, and the POST produces a hosted Stripe URL the buyer
+ * pays on. No money is ever taken here — this route MINTS A LINK. Payment
+ * happens on Stripe's own page, which is what keeps PCI between the seller and
+ * Stripe (`.claude/rules/vocabulary.md` § Commerce), and it is a hard line
+ * rather than a default.
+ *
+ * Handler idiom: `routes/checkout/sessions.ts` — Zod at the boundary, a named
+ * error map, `assertSandboxKey` at request time, no user input echoed into an
+ * error body, and only an 8-char id prefix in a log line.
+ *
+ * ── THE COMMERCE CLAIM IS NOT READ IN THIS FILE (spec D3/D9, issue AC-4) ────
+ *
+ * The confirm route sits INSIDE the commerce claim — it creates a chargeable
+ * Stripe artifact, and money paths are paid (DECISION-LOG D-63; D-67 assigns
+ * request-and-confirm to the Commerce rung rather than exempting it). The gate
+ * is applied by COMPOSITION at registration in `server.ts`, exactly as the
+ * checkout launcher applies it, so no new file imports the licence package and
+ * AC-4's literal requirement holds. (Named as prose, not as a specifier: the
+ * spec verifies this with a `grep`, which a quoted identifier would trip.)
+ * Without the claim both verbs answer the module-disabled 404,
+ * indistinguishable from a build that never registered them.
+ *
+ * ── THE HTML SURFACE (spec D7) ─────────────────────────────────────────────
+ *
+ * This is the API's first `text/html` response, and it is the right place for
+ * the precedent: the STOP boundary forbids an Admin UI, the link lands in a
+ * mail client, and a JSON body is not a thing a person can confirm. The
+ * discipline that comes with it:
+ *
+ *   - one self-contained document; no script, no external asset, no framework;
+ *   - EVERY interpolated value is HTML-escaped — `name`, `phone` and
+ *     `preferredTime` arrive through an anonymous, rate-limited capture route
+ *     and are attacker-supplied;
+ *   - `Referrer-Policy: no-referrer`, because the token is in the query string
+ *     and this is what keeps it out of a third party's referrer log;
+ *   - `Cache-Control: no-store`, `X-Robots-Tag: noindex`, and a CSP of
+ *     `default-src 'none'` so the document can fetch nothing at all.
+ *
+ * ── PII BOUNDARY ───────────────────────────────────────────────────────────
+ *
+ * A log line here carries an 8-char callback-id prefix, an outcome and an
+ * error name. Never the token, never the query, never the buyer's address,
+ * never the requester's name or phone.
+ */
+
+import { zCallbackId } from "@working-theory/ids";
+import type { FastifyReply, FastifyRequest } from "fastify";
+import { z } from "zod";
+
+import {
+  assertSandboxKey,
+  createAdHocPrice,
+  createPaymentLink,
+  StripeConfigError,
+  UnknownProductCodeError,
+} from "../../lib/stripe.js";
+import {
+  type ConfirmableRequest,
+  claimConfirmation,
+  recordPaymentLink,
+  releaseConfirmation,
+  requestConfirmConfig,
+  resolveConfirmableRequest,
+  sendPaidLinkToBuyer,
+} from "../../services/request-confirm.js";
+
+// ── HTML ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Escape the five characters that let a value break out of element text or an
+ * attribute. Deliberately a local five-line function rather than a dependency:
+ * this route renders one document with no user-controlled markup, and a
+ * sanitizer's job (permitting SOME markup safely) is not the job here.
+ */
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+const HTML_HEADERS = {
+  "content-type": "text/html; charset=utf-8",
+  // The token is in the query string. Without this, every asset a mail
+  // client's browser fetches would carry it in a Referer header.
+  "referrer-policy": "no-referrer",
+  "cache-control": "no-store",
+  "x-robots-tag": "noindex, nofollow",
+  // `default-src 'none'` does not govern framing, so `frame-ancestors` is
+  // named separately; `nosniff` stops a browser second-guessing the type of a
+  // document that interpolates attacker-supplied text (#5970 security review,
+  // § 8).
+  "x-content-type-options": "nosniff",
+  // `form-action` and `base-uri` have NO fallback to `default-src` under CSP3,
+  // so `'none'` above does not constrain the one form on this page or a
+  // `<base>` tag. Named explicitly (#5970 security review round 2, L4).
+  "content-security-policy":
+    "default-src 'none'; style-src 'unsafe-inline'; frame-ancestors 'none'; form-action 'self'; base-uri 'none'",
+} as const;
+
+const PAGE_STYLE = `
+  body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif;
+         max-width: 34rem; margin: 0 auto; padding: 2rem 1rem; color: #111; line-height: 1.5; }
+  h1 { font-size: 1.5rem; margin-bottom: 0.5rem; }
+  dl { background: #f6f6f6; border-radius: 6px; padding: 1rem 1.25rem; }
+  dt { font-weight: 600; font-size: 0.8125rem; color: #555; }
+  dd { margin: 0 0 0.75rem; }
+  label { display: block; margin-top: 1.25rem; font-weight: 600; font-size: 0.875rem; }
+  input { width: 100%; box-sizing: border-box; padding: 0.625rem; margin-top: 0.25rem;
+          font-size: 1rem; border: 1px solid #ccc; border-radius: 4px; }
+  button { margin-top: 1.5rem; width: 100%; min-height: 2.75rem; padding: 0.875rem;
+           font-size: 1rem; font-weight: 700; color: #fff; background: #111;
+           border: 0; border-radius: 6px; cursor: pointer; }
+  .note { font-size: 0.8125rem; color: #555; }
+  a { color: #111; }
+`;
+
+function page(title: string, body: string): string {
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex, nofollow">
+<title>${escapeHtml(title)}</title>
+<style>${PAGE_STYLE}</style>
+</head>
+<body>
+${body}
+</body>
+</html>`;
+}
+
+/**
+ * The confirm form.
+ *
+ * The two price paths are both offered, and the POST refuses a submission
+ * carrying both or neither (spec D4): a `lookupKey` names an offering the
+ * tenant has already registered in their own Stripe catalogue, and an amount
+ * is priced here and now. Which one a tenant uses is a property of their
+ * business, not something this form can decide for them.
+ */
+function confirmFormPage(
+  row: ConfirmableRequest,
+  token: string,
+  defaultCurrency: string,
+  prefillEmail: string | undefined,
+): string {
+  const preferred =
+    row.preferredTime === null || row.preferredTime === ""
+      ? "&mdash;"
+      : escapeHtml(row.preferredTime);
+  return page(
+    "Confirm this request",
+    `<h1>Confirm this request</h1>
+<p>Set a time and a price. We will email the customer a secure Stripe page to pay on.</p>
+<dl>
+<dt>Name</dt><dd>${escapeHtml(row.name)}</dd>
+<dt>Phone</dt><dd>${escapeHtml(row.phone)}</dd>
+<dt>Preferred time</dt><dd>${preferred}</dd>
+</dl>
+<form method="post">
+<input type="hidden" name="token" value="${escapeHtml(token)}">
+<label>Confirmed time
+<input name="confirmedTime" required maxlength="200" value="${
+      row.preferredTime === null ? "" : escapeHtml(row.preferredTime)
+    }">
+</label>
+<label>Customer email
+<input name="buyerEmail" type="email" required maxlength="320" value="${escapeHtml(
+      prefillEmail ?? "",
+    )}">
+</label>
+<label>Price, in cents
+<input name="amountMinor" type="number" min="1" step="1" inputmode="numeric">
+</label>
+<label>Currency
+<input name="currency" maxlength="3" value="${escapeHtml(defaultCurrency)}">
+</label>
+<label>&hellip; or a price you have already set up in Stripe
+<input name="lookupKey" maxlength="200" placeholder="lookup_key">
+</label>
+<p class="note">Fill in either a price or a Stripe lookup key &mdash; not both.</p>
+<button type="submit">Confirm and send the payment link</button>
+</form>
+<p class="note">This link works once. Once you confirm, it stops working.</p>`,
+  );
+}
+
+function confirmedPage(paymentUrl: string, buyerNotified: boolean): string {
+  return page(
+    "Request confirmed",
+    `<h1>Request confirmed</h1>
+<p>${
+      buyerNotified
+        ? "We have emailed the customer their payment link."
+        : "The request is confirmed, but we could not email the customer &mdash; send them the link below yourself."
+    }</p>
+<p><a href="${escapeHtml(paymentUrl)}">${escapeHtml(paymentUrl)}</a></p>
+<p class="note">You will see the payment in your own Stripe dashboard as soon as it goes through.</p>`,
+  );
+}
+
+function errorPage(message: string): string {
+  return page("Sorry", `<h1>Sorry</h1><p>${escapeHtml(message)}</p>`);
+}
+
+/**
+ * The ONE refusal every unresolvable credential gets.
+ *
+ * A tampered token, an expired one, one already spent, and a valid one aimed
+ * at another row are deliberately indistinguishable here — the resolver puts
+ * all four predicates in one `where` precisely so this handler cannot leak
+ * which of them happened. An id that does not exist reads the same way.
+ */
+function notFound(reply: FastifyReply) {
+  return reply
+    .status(404)
+    .headers(HTML_HEADERS)
+    .send(
+      errorPage(
+        "This link is not valid any more. It may have expired, or it may already have been used. Ask for a new one.",
+      ),
+    );
+}
+
+// ── Input ────────────────────────────────────────────────────────────────────
+
+/**
+ * The `:id` route parameter, validated the sibling routes' way
+ * (`routes/project-listings/get.ts`'s `paramsSchema` + `safeParse`) rather
+ * than trusted as `request.params as { id: string }`. A malformed id can
+ * never resolve a row anyway — `resolveConfirmableRequest` would just find
+ * zero — so this changes nothing about what a caller can learn: it still
+ * ends at the one uniform `notFound(reply)` every unresolvable credential
+ * gets. It only stops a shape Postgres itself would refuse (an `id` column
+ * of any other format) from ever reaching a query.
+ */
+const IdParamsSchema = z.object({ id: zCallbackId });
+
+const TokenQuerySchema = z.object({ token: z.string().min(1).max(200) });
+
+/**
+ * The POST body, as a browser form sends it — every value arrives a string,
+ * so `amountMinor` is coerced rather than typed.
+ *
+ * The XOR between the two price paths is NOT expressed here: a Zod refinement
+ * would collapse it into the same 400 as a malformed field, and the two are
+ * different operator mistakes worth different messages.
+ */
+const ConfirmBodySchema = z.object({
+  token: z.string().min(1).max(200),
+  confirmedTime: z.string().min(1).max(200),
+  buyerEmail: z.string().email().max(320),
+  /**
+   * The wire form is checked BEFORE it is coerced (#5970 security review
+   * round 3, L3). `z.coerce.number()` alone happily reads `"1e5"` as 100000
+   * and `"0x2710"` as 10000, so an amount pasted from a spreadsheet export
+   * would be charged at a figure nobody typed. On a money path a surprising
+   * parse has to be a 400, not a silent reinterpretation — so only plain
+   * decimal digits are accepted, and the length bound keeps the value inside
+   * the `INTEGER` column the ceiling is expressed in.
+   */
+  amountMinor: z
+    .string()
+    .regex(/^[0-9]{1,10}$/, "amountMinor must be a whole number of minor units")
+    .transform(Number)
+    .pipe(z.number().int().positive())
+    .optional(),
+  currency: z
+    .string()
+    .regex(/^[a-z]{3}$/i, "currency must be an ISO-4217 code")
+    .optional(),
+  lookupKey: z.string().min(1).max(200).optional(),
+});
+
+/**
+ * Empty strings are how a browser submits an untouched optional input, and
+ * they are not the same thing as the field being absent — `""` would fail
+ * `min(1)` and turn an untouched field into a 400. Stripped before parsing.
+ */
+function withoutEmptyStrings(body: unknown): Record<string, unknown> {
+  const source = (body ?? {}) as Record<string, unknown>;
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(source)) {
+    if (value === "" || value === undefined) continue;
+    out[key] = value;
+  }
+  return out;
+}
+
+/** Read `payload.email` off the captured row, when it is there and parses. */
+function prefillEmailFrom(payload: unknown): string | undefined {
+  if (payload === null || typeof payload !== "object") return undefined;
+  const candidate = (payload as Record<string, unknown>)["email"];
+  if (typeof candidate !== "string") return undefined;
+  return z.string().email().safeParse(candidate).success
+    ? candidate
+    : undefined;
+}
+
+function badRequest(reply: FastifyReply, message: string) {
+  return reply.status(400).headers(HTML_HEADERS).send(errorPage(message));
+}
+
+// ── GET ──────────────────────────────────────────────────────────────────────
+
+export async function confirmFormHandler(
+  request: FastifyRequest,
+  reply: FastifyReply,
+): Promise<void> {
+  const config = requestConfirmConfig();
+  if (config === null) return notFound(reply);
+
+  const params = IdParamsSchema.safeParse(request.params);
+  if (!params.success) return notFound(reply);
+  const { id } = params.data;
+  const query = TokenQuerySchema.safeParse(request.query);
+  if (!query.success) return notFound(reply);
+
+  const row = await resolveConfirmableRequest(id, query.data.token);
+  if (row === null) return notFound(reply);
+
+  return reply
+    .status(200)
+    .headers(HTML_HEADERS)
+    .send(
+      confirmFormPage(
+        row,
+        query.data.token,
+        config.currency,
+        prefillEmailFrom(row.payload),
+      ),
+    );
+}
+
+// ── POST ─────────────────────────────────────────────────────────────────────
+
+export async function confirmSubmitHandler(
+  request: FastifyRequest,
+  reply: FastifyReply,
+): Promise<void> {
+  const config = requestConfirmConfig();
+  if (config === null) return notFound(reply);
+
+  const params = IdParamsSchema.safeParse(request.params);
+  if (!params.success) return notFound(reply);
+  const { id } = params.data;
+  const idPrefix = id.substring(0, 8);
+
+  // ── The credential is checked FIRST (#5970 security review, finding 6) ──
+  //
+  // Every branch below this point is configuration-dependent — the money
+  // ceiling, the currency default, whether Stripe is configured, whether its
+  // key is live — and each answers with a different status. Running them
+  // before the token was checked handed an anonymous caller an oracle: by
+  // bisecting `amountMinor` against 400-vs-200 they could read
+  // `AILK_REQUEST_CONFIRM_MAX_MINOR` off a deployment they hold no credential
+  // for, and provoke `error`-level log lines at will.
+  //
+  // So a cheap indexed read runs first and answers the SAME uniform 404 the
+  // GET does. It is not the authorization — `claimConfirmation` below is, and
+  // it re-checks every predicate atomically, which is what still makes the
+  // double-POST race safe. This read only decides whether the caller is
+  // entitled to see any answer other than 404.
+  const preflight = ConfirmBodySchema.shape.token.safeParse(
+    (withoutEmptyStrings(request.body) as { token?: unknown }).token,
+  );
+  if (!preflight.success) return notFound(reply);
+  if ((await resolveConfirmableRequest(id, preflight.data)) === null) {
+    return notFound(reply);
+  }
+
+  const parsed = ConfirmBodySchema.safeParse(withoutEmptyStrings(request.body));
+  if (!parsed.success) {
+    // The message names what is wrong in the operator's own words and never
+    // echoes what they typed — the checkout route's rule.
+    return badRequest(
+      reply,
+      "Check the form: a time, a valid customer email, and either a price in cents or a Stripe lookup key.",
+    );
+  }
+  const body = parsed.data;
+
+  // ── The two price paths are exclusive (spec D4) ──────────────────────────
+  const hasAmount = body.amountMinor !== undefined;
+  const hasLookupKey = body.lookupKey !== undefined;
+  if (hasAmount === hasLookupKey) {
+    return badRequest(
+      reply,
+      hasAmount
+        ? "Give either a price or a Stripe lookup key, not both."
+        : "Give either a price in cents or a Stripe lookup key.",
+    );
+  }
+
+  // ── The money gate (spec D10), entirely before any Stripe call ───────────
+  if (hasAmount && body.amountMinor! > config.maxAmountMinor) {
+    request.log.warn(
+      { idPrefix, outcome: "amount_above_ceiling" },
+      "[request-confirm] amount refused",
+    );
+    return badRequest(
+      reply,
+      "That price is above the limit this site allows. Raise the limit in your configuration, or charge in stages.",
+    );
+  }
+  const currency = (body.currency ?? config.currency).toLowerCase();
+  if (hasAmount && !/^[a-z]{3}$/.test(currency)) {
+    return badRequest(reply, "Currency must be a three-letter ISO-4217 code.");
+  }
+
+  // ── Sandbox-only, asserted at request time as well as inside the client ──
+  const stripeSecretKey = process.env["STRIPE_SECRET_KEY"];
+  if (!stripeSecretKey) {
+    return reply
+      .status(500)
+      .headers(HTML_HEADERS)
+      .send(errorPage("Stripe is not configured on this site."));
+  }
+  try {
+    assertSandboxKey(stripeSecretKey);
+  } catch {
+    request.log.error(
+      { idPrefix, outcome: "live_mode_forbidden" },
+      "[request-confirm] live Stripe key refused",
+    );
+    return reply
+      .status(500)
+      .headers(HTML_HEADERS)
+      .send(errorPage("Stripe is not configured on this site."));
+  }
+
+  // ── Claim the credential BEFORE any Stripe call ──────────────────────────
+  //
+  // Verification and the stamp are one guarded update, so two simultaneous
+  // POSTs cannot both reach the SDK and mint two Payment Links: exactly one
+  // wins and the other is answered the same 404 an invalid token gets.
+  //
+  // Its cost, stated rather than hidden: a Stripe failure AFTER this point
+  // leaves the credential spent and the row stamped with no artifact id, and
+  // the tenant needs a fresh link. That is why every validation above runs
+  // first — only a genuine Stripe fault can burn a credential, and a stamped
+  // row with no artifact is visible and recoverable where a Payment Link
+  // nothing recorded is not.
+  const claimed = await claimConfirmation({
+    id,
+    token: body.token,
+    confirmedTime: body.confirmedTime,
+    buyerEmail: body.buyerEmail,
+    ...(hasAmount && { amountMinor: body.amountMinor!, currency }),
+  });
+  if (!claimed) return notFound(reply);
+
+  let paymentUrl: string;
+  try {
+    const lookupKey = hasLookupKey
+      ? body.lookupKey!
+      : (
+          await createAdHocPrice({
+            currency,
+            unitAmountMinor: body.amountMinor!,
+            // What Stripe shows the buyer. The requester's own name would be
+            // the natural label and is deliberately NOT used: a Payment Link's
+            // product name is visible to anyone holding the URL.
+            productName: "Booked service",
+            // Unique per row, so a second confirmation of a different request
+            // never collides with this one's price.
+            lookupKey: `ailk-request-${id}`,
+          })
+        ).lookupKey;
+
+    // `completedSessionsLimit: 1` (#5970 security review round 2, M1). A
+    // Payment Link with no restrictions is permanently and repeatedly payable
+    // by design — right for a catalogue link, wrong for one emailed against
+    // one job. Without it a buyer who double-clicks pays twice and only the
+    // first payment is ever recorded, because the webhook stamp matches on
+    // `paidAt: null`; the second is money taken with nothing tying it to the
+    // job. Stripe enforces the cap, so there is no race to win.
+    const link = await createPaymentLink({
+      lookupKey,
+      completedSessionsLimit: 1,
+    });
+    paymentUrl = link.url;
+
+    // Recorded OUTSIDE the Stripe try/catch below (#5970 security review
+    // round 2, L3). A Prisma fault here is not a Stripe fault, and reporting
+    // it as one told the operator "Stripe could not create the payment link —
+    // try again from a fresh link" when Stripe HAD created it: a live,
+    // chargeable link with no row to stamp, no buyer email, and no fresh link
+    // to try. It gets its own branch and its own honest wording.
+    try {
+      await recordPaymentLink(id, link.paymentLinkId);
+    } catch (dbErr) {
+      request.log.error(
+        {
+          idPrefix,
+          paymentLinkIdPrefix: link.paymentLinkId.substring(0, 8),
+          outcome: "record_failed",
+          errName: dbErr instanceof Error ? dbErr.name : "UnknownError",
+        },
+        "[request-confirm] payment link created but not recorded",
+      );
+      // The link is real and the buyer still needs it, so it is shown rather
+      // than withheld — but the page must not claim the payment will be
+      // tracked, because nothing will stamp a row this id was never written to.
+      return reply
+        .status(200)
+        .headers(HTML_HEADERS)
+        .send(
+          page(
+            "Request confirmed — check this one in Stripe",
+            `<h1>Request confirmed</h1>
+<p>The payment link below is live, but we could not record it against this request. Send it to your customer yourself, and watch for the payment in your Stripe dashboard &mdash; it will not show as paid here.</p>
+<p><a href="${escapeHtml(link.url)}">${escapeHtml(link.url)}</a></p>`,
+          ),
+        );
+    }
+
+    request.log.info(
+      {
+        idPrefix,
+        paymentLinkIdPrefix: link.paymentLinkId.substring(0, 8),
+        outcome: "confirmed",
+      },
+      "[request-confirm] payment link created",
+    );
+  } catch (err) {
+    if (err instanceof UnknownProductCodeError) {
+      // A typo, caught by a Stripe READ that created nothing — so the
+      // credential goes back and the operator can act on the advice below.
+      // Every other Stripe failure keeps the credential spent, because it may
+      // have created a Payment Link whose id never reached us.
+      await releaseConfirmation(id, body.token);
+      request.log.warn(
+        { idPrefix, outcome: "unknown_lookup_key" },
+        "[request-confirm] no active Stripe price for that lookup key",
+      );
+      return badRequest(
+        reply,
+        "No active Stripe price matches that lookup key. Check it in your Stripe dashboard, or set a price here instead.",
+      );
+    }
+    if (err instanceof StripeConfigError) {
+      request.log.error(
+        { idPrefix, outcome: "stripe_config_error" },
+        "[request-confirm] stripe config error",
+      );
+      return reply
+        .status(500)
+        .headers(HTML_HEADERS)
+        .send(errorPage("Stripe is not configured on this site."));
+    }
+    request.log.error(
+      {
+        idPrefix,
+        outcome: "stripe_unavailable",
+        errName: err instanceof Error ? err.name : "UnknownError",
+      },
+      "[request-confirm] stripe call failed",
+    );
+    return reply.status(502).headers(HTML_HEADERS).send(
+      // The copy says what is actually true (#5970 security review round 3,
+      // L2). It used to promise "try again from a fresh link" — there is no
+      // such link and no path that mints one: the credential is spent, and
+      // the only mint site guards on an unconfirmed row. Sending the
+      // operator back to a 404 and letting them think the link was merely
+      // retryable is worse than telling them the truth.
+      errorPage(
+        "Stripe could not create the payment link just now. This confirmation link is now used up, so it will not work again. Take the payment from your Stripe dashboard, or ask the customer to send the request through again.",
+      ),
+    );
+  }
+
+  // The buyer's email is awaited rather than fired and forgotten: the tenant
+  // is looking at this page, and whether the customer was actually told is the
+  // one thing they cannot find out anywhere else. It never throws, and a
+  // failure changes the page's wording rather than its status — the Payment
+  // Link exists either way.
+  const notified = await sendPaidLinkToBuyer({
+    id,
+    to: body.buyerEmail,
+    from: config.from,
+    paymentUrl,
+    confirmedTime: body.confirmedTime,
+    ...(hasAmount && { amountMinor: body.amountMinor!, currency }),
+  });
+
+  return reply
+    .status(200)
+    .headers(HTML_HEADERS)
+    .send(confirmedPage(paymentUrl, notified));
+}

package/templates/apps/api/src/routes/requests/index.ts

@@ -0,0 +1,54 @@
+/**
+ * Requests route group (#5970 — request-and-confirm).
+ *
+ * Routes:
+ *   GET  /v1/requests/:id/confirm — the tenant's confirm form (text/html)
+ *   POST /v1/requests/:id/confirm — confirm, mint a Payment Link, email the buyer
+ *
+ * Two-file split mirroring `routes/checkout/index.ts`: this file exports the
+ * plugin and routes the paths; `confirm.ts` holds the handlers. The `/v1`
+ * segment is typed into each path string rather than carried as a scope-level
+ * `prefix`, which is what `routes/checkout/index.ts:12` does and what ADR 0020
+ * reads (spec § 7).
+ *
+ * The commerce claim is attached at REGISTRATION in `server.ts`, not here —
+ * see `confirm.ts`'s header for why (spec D3/D9).
+ */
+import type { FastifyPluginAsync } from "fastify";
+
+import { confirmFormHandler, confirmSubmitHandler } from "./confirm.js";
+
+/**
+ * A form POST arrives `application/x-www-form-urlencoded`, which Fastify does
+ * not parse without `@fastify/formbody` — a dependency this repo does not
+ * carry and this feature does not need.
+ *
+ * `URLSearchParams` is the same parse. It is registered on THIS SCOPE ONLY, so
+ * no other route's body handling changes: the same containment the webhooks
+ * scope uses for its own raw-buffer parsers (`server.ts`).
+ *
+ * `Object.fromEntries` keeps the LAST value for a repeated key. That is the
+ * right reading here — every field is single-valued, and a duplicated field is
+ * a malformed submission the Zod schema judges on its merits either way.
+ */
+const urlencodedParser = (
+  _request: unknown,
+  body: string,
+  done: (err: Error | null, value?: unknown) => void,
+): void => {
+  try {
+    done(null, Object.fromEntries(new URLSearchParams(body)));
+  } catch (err) {
+    done(err instanceof Error ? err : new Error("invalid form body"));
+  }
+};
+
+export const requestRoutes: FastifyPluginAsync = async (fastify) => {
+  fastify.addContentTypeParser(
+    "application/x-www-form-urlencoded",
+    { parseAs: "string" },
+    urlencodedParser,
+  );
+  fastify.get("/v1/requests/:id/confirm", confirmFormHandler);
+  fastify.post("/v1/requests/:id/confirm", confirmSubmitHandler);
+};