create-ailk 0.1.0 → 0.2.0

package/templates/.claude/skills/scaffold-commerce/templates/payment-link-route.template.ts

@@ -0,0 +1,471 @@
+/**
+ * Payment-link MANAGEMENT route — emitted by `scaffold-commerce`'s
+ * surface-selection branch (SKILL.md § Surface-selection branch, Step 10e-ii,
+ * FEAT-023 U3). Three Fastify handlers: list, create (from a `lookupKey`),
+ * archive/restore (by id).
+ *
+ * Instantiated into the consumer's own `apps/api/src/routes/payment-links/`,
+ * alongside `stripe-config.ts` (Step 10d) — the SAME home as the checkout
+ * sibling, and for the same two reasons:
+ *   1. `architecture.yaml`: `apps/web` MAY NOT import `packages/stripe-client`
+ *      ("billing is org-scoped and server-side via apps/api"). Stripe secrets
+ *      never enter the Next.js app.
+ *   2. `apps/api` is where the auth middleware this route depends on LIVES.
+ *      (An earlier revision of this template was a Next.js App Router handler.
+ *      It shipped with NO authentication at all — AILK#3744, a P0. A management
+ *      surface mounted in a runtime that has no auth preHandler in front of it
+ *      is a hole waiting to happen; this one was.)
+ *
+ * ── Auth posture — AUTHENTICATED + SITE-ADMIN ONLY (the opposite of checkout) ─
+ * This is a MANAGEMENT surface: it LISTS, CREATES, and ARCHIVES payment
+ * objects. The checkout sibling (`checkout-route.template.ts`) is deliberately
+ * public — it is a storefront "buy" action that can only ever create one new
+ * Checkout Session for one allowlisted product. Its own header says it plainly:
+ * "A management surface (list/update/archive payment objects) is a DIFFERENT
+ * shape and MUST be authenticated". This is that surface. Do not copy the
+ * checkout route's public posture here.
+ *
+ * Without authentication, an anonymous caller could:
+ *   - GET   -> read every Payment Link on the site (ids, buy URLs, active flags)
+ *   - PATCH -> archive them; iterating the GET output deactivates EVERY link:
+ *              total denial of revenue, in two curl calls
+ *   - POST  -> mint Payment Links against the merchant's own Stripe account
+ *
+ * ── Entitlement is NOT authorization (the AILK#3744 reasoning error) ──────────
+ * `assertCommerceEntitled()` reads the SITE's license from env. It returns the
+ * IDENTICAL answer for every request, anonymous or not — it answers "does this
+ * DEPLOYMENT have commerce?", never "is this CALLER allowed to manage payment
+ * links?". It is a correct check and it fails closed, but it is the WRONG AXIS,
+ * so failing closed buys nothing on its own. It is kept below, LAYERED UNDER
+ * the identity gate — never as a substitute for it.
+ *
+ * ── Registration — LOAD-BEARING; the route is fail-closed if you get it wrong ─
+ * Register INSIDE the authenticated scope, so `authPreHandlerPlugin` decorates
+ * `request.userId` (and applies its same-origin CSRF check) before any handler
+ * here runs:
+ *
+ *   await fastify.register(async (authed) => {
+ *     authed.register(authPreHandlerPlugin, { frontendOrigin: config.frontendUrl });
+ *     authed.get("/api/payment-links", listPaymentLinksHandler);
+ *     authed.post("/api/payment-links", createPaymentLinkHandler);
+ *     authed.patch("/api/payment-links", updatePaymentLinkHandler);
+ *   });
+ *
+ * If you mis-register these OUTSIDE that scope, `request.userId` is `undefined`
+ * and every handler answers 401 — `requireSiteAdmin()` re-checks it rather than
+ * assuming the preHandler ran. That belt-and-suspenders re-check is the reason
+ * a mis-registration is a broken feature instead of an open door.
+ *
+ * ── CSRF ─────────────────────────────────────────────────────────────────────
+ * Inherited from the auth scope: `apps/api/src/middleware/auth.ts` requires a
+ * same-origin `Origin` header on every cookie-authenticated non-GET request
+ * (`isOriginAllowed`). No custom token scheme is needed — but that protection
+ * exists ONLY inside the auth scope, which is the second reason the
+ * registration above is load-bearing.
+ *
+ * ── Tenancy ──────────────────────────────────────────────────────────────────
+ * Deliberately NOT registered inside `tenantScope`, and the org is deliberately
+ * NOT read from `request.tenant`. This surface manages the SITE OWNER's own
+ * Stripe catalog: `packages/stripe-client` is single-tenant (one Stripe account
+ * per deployment), a Stripe Payment Link carries no organization binding, and
+ * no local table maps a payment link to an org. The multi-tenant module's
+ * org-scoped billing is a SEPARATE surface (`apps/api/src/routes/billing/`,
+ * which DOES derive its org from `request.tenant.organizationId`, and whose
+ * `apps/workspace` consumer may not import `stripe-client` at all).
+ *
+ * Cross-account access is therefore structurally impossible rather than
+ * checked: Stripe object ids are scoped to the account whose key made the call,
+ * so a payment-link id from any other Stripe account comes back
+ * `resource_missing` — mapped below to the SAME 404 shape as a simply-unknown
+ * id, so the response is never an enumeration oracle.
+ *
+ * The correct authorization axis for this surface is therefore the SITE role,
+ * not the org membership: `User.role` in {"admin","owner"}
+ * (`database/auth/schema.prisma` — a per-deployment String, distinct from the
+ * org-membership `Role` enum used by the multi-tenant module).
+ *
+ * ── Test-mode-only ───────────────────────────────────────────────────────────
+ * Carried in twice, belt-and-suspenders: `loadStripeSurfaceConfig()` guards
+ * this surface's entry point; `@working-theory/stripe-client`'s
+ * `getStripeClient()`/`assertSandboxKey()` guards the SDK call itself. This
+ * route deliberately does NOT hand-roll its own live-key prefix check — it
+ * defers ENTIRELY to the shared guard so it inherits that guard's coverage (and
+ * any future fix to it) rather than risking a second, divergent implementation.
+ *
+ * Error mapping:
+ *   401 unauthorized             — no authenticated caller (anonymous, or the
+ *                                  route mis-registered outside the auth scope)
+ *   403 forbidden                — authenticated, but not a site admin/owner
+ *   403 not-entitled             — the deployment lacks `feature:commerce`
+ *   400 invalid-input            — malformed body (bad lookupKey / link id)
+ *   404 not-found                — no such payment link IN THIS ACCOUNT
+ *   500 config-error             — Stripe/site env missing or misconfigured
+ *   500 internal-error           — the role lookup itself failed (fail-closed)
+ *   502 payment-link-unavailable — Stripe SDK threw an unexpected error
+ */
+import { checkLicense } from "@working-theory/license";
+import {
+  createPaymentLink,
+  listPaymentLinks,
+  StripeConfigError,
+  UnknownProductCodeError,
+  updatePaymentLink,
+} from "@working-theory/stripe-client";
+import type { FastifyReply, FastifyRequest } from "fastify";
+
+// The consumer's own Prisma singleton (`apps/api/src/lib/prisma.ts`) — the same
+// client the auth middleware uses to resolve sessions.
+import { prisma } from "../../lib/prisma.js";
+
+// Sibling file instantiated at Step 10d — same directory as this route.
+import { loadStripeSurfaceConfig } from "./stripe-config.js";
+
+// ── Authorization ─────────────────────────────────────────────────────────────
+
+/**
+ * The site roles allowed to manage the payment catalog.
+ *
+ * `User.role` is a per-deployment String ("user" | "admin" | "owner"). On a
+ * site with open signup, "authenticated" is NOT a meaningful bar — it is "the
+ * whole internet with an extra step" — so authentication alone would not close
+ * AILK#3744. The role check is what makes this an authorization control.
+ */
+const SITE_ADMIN_ROLES: ReadonlySet<string> = new Set(["admin", "owner"]);
+
+const PAYMENT_LINK_ID_REGEX = /^plink_[A-Za-z0-9_]{1,100}$/;
+const LOOKUP_KEY_REGEX = /^[A-Za-z0-9._-]{1,200}$/;
+
+function errorResponse(
+  reply: FastifyReply,
+  status: number,
+  code: string,
+  message: string,
+): FastifyReply {
+  return reply.status(status).send({ ok: false, error: { code, message } });
+}
+
+/**
+ * The gate. Returns `true` only for an authenticated caller whose CURRENT role
+ * — re-read from the database on every request — is a site admin or owner.
+ * Every other path replies and returns `false`; the caller MUST bail out.
+ *
+ * Call it as the FIRST statement of every handler:
+ *
+ *   if (!(await requireSiteAdmin(request, reply))) return;
+ *
+ * Three properties are load-bearing:
+ *
+ *   1. The role is re-read from the DB by the caller's id — never trusted off
+ *      the request. A stale session belonging to a user who has since been
+ *      demoted loses access on their very next request.
+ *   2. It FAILS CLOSED. A throw while resolving the role DENIES (500). It never
+ *      falls through to allow — the classic catch-and-continue that turns a
+ *      transient DB blip into an open door.
+ *   3. It re-checks `request.userId` rather than assuming the auth preHandler
+ *      ran, so a MIS-REGISTRATION (routes mounted outside the auth scope) is a
+ *      401 — a broken feature, not an open door.
+ */
+export async function requireSiteAdmin(
+  request: FastifyRequest,
+  reply: FastifyReply,
+): Promise<boolean> {
+  const userId = request.userId;
+  if (!userId) {
+    // Anonymous — or mis-registered outside the auth scope. Same answer.
+    errorResponse(
+      reply,
+      401,
+      "unauthorized",
+      "Authentication is required.",
+    );
+    return false;
+  }
+
+  let role: string | undefined;
+  try {
+    const user = await prisma.user.findUnique({
+      where: { id: userId },
+      select: { role: true },
+    });
+    role = user?.role;
+  } catch (err) {
+    // FAIL CLOSED. Never `catch {}` into the happy path.
+    request.log.error(
+      {
+        method: request.method,
+        path: request.url,
+        message: err instanceof Error ? err.message : "unknown",
+      },
+      "[payment-links] role resolution failed; DENYING",
+    );
+    errorResponse(
+      reply,
+      500,
+      "internal-error",
+      "Could not verify your permissions.",
+    );
+    return false;
+  }
+
+  // A missing user row (deleted account, stale session) has no role -> denied.
+  if (!role || !SITE_ADMIN_ROLES.has(role)) {
+    request.log.warn(
+      { method: request.method, path: request.url, status: 403 },
+      "[payment-links] caller is not a site admin; refused",
+    );
+    errorResponse(
+      reply,
+      403,
+      "forbidden",
+      "Managing payment links requires a site admin role.",
+    );
+    return false;
+  }
+
+  return true;
+}
+
+// ── Entitlement (layered UNDER authorization — never a substitute for it) ─────
+
+/**
+ * Resolves the deployment's license and enforces the `feature:commerce`
+ * entitlement. Fails closed: no license, an expired license, a revoked license,
+ * or a license without the `commerce` feature are all treated as NOT entitled.
+ *
+ * This answers "does this DEPLOYMENT have commerce?" — a DIFFERENT question
+ * from "may this CALLER manage payment links?", which is `requireSiteAdmin`'s
+ * job. Both are enforced, in that order.
+ */
+async function assertCommerceEntitled(): Promise<void> {
+  const result = await checkLicense();
+
+  // A revoked license is treated as feature-less — the feature check below then
+  // throws, same as an absent license.
+  const features: readonly string[] = result.revoked ? [] : result.features;
+
+  // Expiry first, then the feature claim — the same order, and the same two
+  // conditions, the paid entitlement helper applies. The third thing that
+  // helper does is assert the feature's verification MODE against the license
+  // manifest; `commerce` is declared `verification: static`, so that assert is
+  // a no-op pass for this call, and the manifest is a paid-tier package an
+  // emitted OSS route may not reach. Both throws below are caught by
+  // `preflight()` and mapped to the SAME 403 not-entitled response, so the
+  // error type is not observable at the route boundary.
+  //
+  // `LicenseResult.expiresAt` is `Date | null`; normalise anyway so a licence
+  // resolver that yields `undefined` reads as "no expiry" rather than throwing.
+  const expiresAt = result.expiresAt ?? null;
+  if (expiresAt !== null && expiresAt.getTime() <= Date.now()) {
+    throw new Error("This site's license has expired.");
+  }
+  if (!features.includes("commerce")) {
+    throw new Error("This site's license does not include the commerce feature.");
+  }
+}
+
+/**
+ * Runs the entitlement + Stripe-config preflight shared by all three handlers.
+ * Returns `true` when the request may proceed to a Stripe call.
+ *
+ * Callers MUST have cleared `requireSiteAdmin` first — this function performs
+ * no identity check of its own.
+ */
+async function preflight(
+  request: FastifyRequest,
+  reply: FastifyReply,
+): Promise<boolean> {
+  try {
+    await assertCommerceEntitled();
+  } catch {
+    errorResponse(
+      reply,
+      403,
+      "not-entitled",
+      "This site is not entitled to the commerce feature.",
+    );
+    return false;
+  }
+
+  try {
+    loadStripeSurfaceConfig();
+  } catch (err) {
+    request.log.error(
+      {
+        method: request.method,
+        path: request.url,
+        message: err instanceof Error ? err.message : "unknown",
+      },
+      "[payment-links] config error",
+    );
+    errorResponse(
+      reply,
+      500,
+      "config-error",
+      "Stripe is misconfigured for this site.",
+    );
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Stripe raises `resource_missing` for an id that does not exist IN THIS
+ * ACCOUNT — which is also what a payment-link id belonging to a DIFFERENT
+ * Stripe account looks like, since object ids are account-scoped. Both map to
+ * the same 404, so the response cannot be used to enumerate ids.
+ */
+function isResourceMissing(err: unknown): boolean {
+  return (
+    typeof err === "object" &&
+    err !== null &&
+    (err as { code?: unknown }).code === "resource_missing"
+  );
+}
+
+/** Shared Stripe error mapping. Never echoes caller input back. */
+function stripeErrorResponse(
+  request: FastifyRequest,
+  reply: FastifyReply,
+  err: unknown,
+): FastifyReply {
+  if (isResourceMissing(err)) {
+    return errorResponse(reply, 404, "not-found", "No such payment link.");
+  }
+  if (err instanceof StripeConfigError) {
+    return errorResponse(
+      reply,
+      500,
+      "config-error",
+      "Payment links are misconfigured.",
+    );
+  }
+  request.log.error(
+    {
+      method: request.method,
+      path: request.url,
+      errName: err instanceof Error ? err.name : "unknown",
+    },
+    "[payment-links] stripe error; payment-link-unavailable",
+  );
+  return errorResponse(
+    reply,
+    502,
+    "payment-link-unavailable",
+    "Payment links are temporarily unavailable.",
+  );
+}
+
+// ── Handlers ──────────────────────────────────────────────────────────────────
+
+/** GET /api/payment-links[?active=true|false] — list payment links. */
+export async function listPaymentLinksHandler(
+  request: FastifyRequest,
+  reply: FastifyReply,
+): Promise<void> {
+  if (!(await requireSiteAdmin(request, reply))) return;
+  if (!(await preflight(request, reply))) return;
+
+  const query = request.query as { active?: string } | undefined;
+  const activeParam = query?.active;
+  const active = activeParam === undefined ? undefined : activeParam === "true";
+
+  try {
+    const { paymentLinks } = await listPaymentLinks({ active });
+    reply.send({ ok: true, data: { paymentLinks } });
+  } catch (err) {
+    stripeErrorResponse(request, reply, err);
+  }
+}
+
+/** POST /api/payment-links — create a Payment Link from a lookupKey. */
+export async function createPaymentLinkHandler(
+  request: FastifyRequest,
+  reply: FastifyReply,
+): Promise<void> {
+  if (!(await requireSiteAdmin(request, reply))) return;
+  if (!(await preflight(request, reply))) return;
+
+  const body = request.body as
+    | { lookupKey?: unknown; quantity?: unknown }
+    | undefined;
+  if (
+    !body ||
+    typeof body.lookupKey !== "string" ||
+    !LOOKUP_KEY_REGEX.test(body.lookupKey)
+  ) {
+    errorResponse(
+      reply,
+      400,
+      "invalid-input",
+      "lookupKey is required and must match /^[A-Za-z0-9._-]{1,200}$/.",
+    );
+    return;
+  }
+
+  const quantity =
+    typeof body.quantity === "number" &&
+    Number.isInteger(body.quantity) &&
+    body.quantity >= 1 &&
+    body.quantity <= 999
+      ? body.quantity
+      : undefined;
+
+  try {
+    const link = await createPaymentLink({
+      lookupKey: body.lookupKey,
+      quantity,
+    });
+    reply.status(201).send({ ok: true, data: link });
+  } catch (err) {
+    if (err instanceof UnknownProductCodeError) {
+      // Do NOT echo the lookupKey back to the caller.
+      errorResponse(
+        reply,
+        404,
+        "unknown-lookup-key",
+        "No active price exists for that product.",
+      );
+      return;
+    }
+    stripeErrorResponse(request, reply, err);
+  }
+}
+
+/** PATCH /api/payment-links — archive/restore a Payment Link by id. */
+export async function updatePaymentLinkHandler(
+  request: FastifyRequest,
+  reply: FastifyReply,
+): Promise<void> {
+  if (!(await requireSiteAdmin(request, reply))) return;
+  if (!(await preflight(request, reply))) return;
+
+  const body = request.body as
+    | { paymentLinkId?: unknown; active?: unknown }
+    | undefined;
+  if (
+    !body ||
+    typeof body.paymentLinkId !== "string" ||
+    !PAYMENT_LINK_ID_REGEX.test(body.paymentLinkId) ||
+    typeof body.active !== "boolean"
+  ) {
+    // Shape-checked BEFORE any Stripe call. Does not echo the input back.
+    errorResponse(
+      reply,
+      400,
+      "invalid-input",
+      "paymentLinkId (plink_...) and active (boolean) are required.",
+    );
+    return;
+  }
+
+  try {
+    const link = await updatePaymentLink({
+      paymentLinkId: body.paymentLinkId,
+      active: body.active,
+    });
+    reply.send({ ok: true, data: link });
+  } catch (err) {
+    stripeErrorResponse(request, reply, err);
+  }
+}