create-ailk 0.2.0 → 0.3.0

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

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