create-ailk 0.1.0 → 0.2.0

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

@@ -0,0 +1,376 @@
+/**
+ * Invoice management routes — instantiated by `scaffold-commerce`'s
+ * surface-selection branch (SKILL.md § Step 10g, FEAT-023 U4) into the
+ * consumer's own `apps/api`. Lands at, e.g.,
+ * `apps/api/src/routes/commerce/invoices.ts`, registered as a Fastify
+ * plugin (see "Registration" below).
+ *
+ * SECURITY — this surface exposes customer PII (names, emails, amounts, line
+ * items) and moves money-adjacent state, so it carries THREE independent
+ * gates. It mirrors `apps/api/src/routes/billing/read.ts`, whose actual
+ * safety property is not a role check but SERVER-DERIVED TENANCY: the org is
+ * always `request.tenant.organizationId`, never a client-supplied id.
+ *
+ *   1. AUTHENTICATION + AUTHORIZATION (`requireSiteAdmin`). Invoice
+ *      management is a SITE-ADMIN action, never anonymous or plain-
+ *      authenticated-user. Requires `User.role` in {"admin","owner"}
+ *      (`database/auth/schema.prisma`'s `User.role` — present on every AILK
+ *      site, not conditional on the multi-tenant module), re-read from the DB
+ *      per request. NOTE: an entitlement check (`hasFeature("commerce")`) is
+ *      NOT authentication — it answers "does this deployment have commerce?",
+ *      never "is this caller allowed to do this?"; a prior review of the
+ *      sibling U3 (pay-by-link) template found relying on it alone let an
+ *      ANONYMOUS caller dump/create/void invoices. The commerce entitlement
+ *      gate for this surface is SCAFFOLD-TIME (this file is not emitted
+ *      without `feature:commerce`); there is deliberately no runtime
+ *      entitlement call here, and none is claimed.
+ *
+ *   2. TENANCY (`requireSingleTenantScope`). The org is derived server-side
+ *      from `request.tenant` — there is no client-supplied org id, so
+ *      cross-tenant enumeration is structurally impossible. On a MULTI-TENANT
+ *      deployment this surface HARD-REFUSES (403 `tenancy_unsupported`)
+ *      before any Stripe call. See "v1 tenancy limitation" below — a
+ *      mechanical refusal, not a prose warning.
+ *
+ *   3. NO PII IN LOGS OR ERRORS. Handlers never log invoice description /
+ *      customer / amount fields, and never echo a raw Stripe error (which may
+ *      embed request params) — only a fixed, generic message.
+ *
+ * Registration (REQUIRED): register this plugin inside `server.ts`'s
+ * TENANT-GUARDED scope — the inner `tenantScope` that registers
+ * `tenantPreHandlerPlugin` (the same scope `billingRoutes` uses), NOT the
+ * outer `authScope`:
+ *
+ *     await tenantScope.register(invoiceRoutes);
+ *
+ * `tenantPreHandlerPlugin` is default-deny: it resolves the caller's active
+ * tenant and 403s anything that is not an explicit grant, so `request.tenant`
+ * is populated before any handler below runs. This works on BOTH deployment
+ * shapes — a single-tenant site resolves the default org/workspace
+ * (`resolveSingleTenantDefault`), a multi-tenant site resolves the caller's
+ * active workspace. Every handler ALSO defensively re-checks the caller
+ * (belt-and-suspenders): if a consumer mis-registers this plugin outside
+ * `tenantScope`, `request.tenant` is `undefined` and every handler fails
+ * CLOSED with a 403 — the surface goes dark rather than serving unscoped.
+ *
+ * Because `tenantScope` nests inside `authScope`'s `authPreHandlerPlugin`,
+ * the cookie path's same-origin check already covers CSRF for every non-GET
+ * request — no bespoke token scheme needed. Note this also means a
+ * BEARER-token caller is denied (a bearer token carries no workspace
+ * binding); invoice management is a cookie-session admin-UI action.
+ *
+ * v1 TENANCY LIMITATION — mechanically enforced, not merely documented:
+ * `loadStripeSurfaceConfig()` resolves ONE deployment-wide `STRIPE_SECRET_KEY`
+ * and v1 has NO per-organization Stripe account/customer namespace (see
+ * `docs/research/commerce-template-audit/invoices.md` findings 7 + 9). An
+ * invoice therefore carries no org attribution, so on a multi-tenant
+ * deployment there is no honest way to decide whether a caller-supplied
+ * `invoiceId` / `customerId` belongs to the caller's org — one org's admin
+ * could read another org's invoices (a cross-tenant PII leak). Rather than
+ * ship an unscoped admin surface with a warning label,
+ * `requireSingleTenantScope` admits ONLY the deployment's own operator org
+ * (the fixed single-tenant sentinel `DEFAULT_ORG_ID`, which an org created
+ * through the multi-tenant module never carries) and REFUSES every tenant
+ * org's admin outright. Lifting the refusal — i.e. making invoices work
+ * per-tenant — needs a per-org Stripe Connect / customer-namespace model: a
+ * tracked follow-up, not something silently claimed as fixed here.
+ *
+ * TEST-MODE ONLY (v1), and the live-key guard is COMPLETE as of AILK#3734.
+ * `assertSandboxKey` (a SHARED file, `@working-theory/stripe-client`'s
+ * `client.ts`, outside this template's scope) is an ALLOW-LIST: it accepts only
+ * the three recognized sandbox prefixes (`sk_test_`, `pk_test_`, `rk_test_`)
+ * and refuses everything else. A Stripe RESTRICTED live key is refused, as is
+ * any live-mode prefix Stripe introduces later — not because each is named on a
+ * ban-list, but because it is absent from the allow-list. Fail-closed is a
+ * property of the shape, not a special case.
+ *
+ * That is a reason to trust the guard, not a reason to test it in production:
+ * still never place a real API key of ANY kind in a non-production environment.
+ */
+import { DEFAULT_ORG_ID } from "@working-theory/database/tenancy";
+import type { FastifyPluginAsync, FastifyReply, FastifyRequest } from "fastify";
+import { z } from "zod";
+
+import {
+  createInvoice,
+  listInvoices,
+  retrieveInvoice,
+  sendInvoice,
+} from "@working-theory/stripe-client";
+
+import { prisma } from "../../lib/prisma.js";
+import { loadStripeSurfaceConfig } from "./stripe-config.template.js";
+
+// ── Response helpers (no PII, no raw error echo) ─────────────────────────────
+
+function unauthorized(reply: FastifyReply): void {
+  reply.status(401).send({
+    ok: false,
+    error: { code: "unauthorized", message: "Authentication required." },
+  });
+}
+
+function forbidden(reply: FastifyReply): void {
+  reply.status(403).send({
+    ok: false,
+    error: { code: "forbidden", message: "Admin access required." },
+  });
+}
+
+/**
+ * The multi-tenant refusal. Identical for EVERY request — it never depends on
+ * the requested `invoiceId` / `customerId`, so it leaks no information about
+ * which invoices exist (no enumeration oracle).
+ */
+function tenancyUnsupported(reply: FastifyReply): void {
+  reply.status(403).send({
+    ok: false,
+    error: {
+      code: "tenancy_unsupported",
+      message:
+        "Invoice management is unavailable on a multi-tenant deployment: v1 has no per-organization Stripe customer namespace, so invoices cannot be attributed to an organization.",
+    },
+  });
+}
+
+function invalidBody(reply: FastifyReply): void {
+  reply.status(400).send({
+    ok: false,
+    error: { code: "invalid_body", message: "Invalid request body." },
+  });
+}
+
+function serverError(reply: FastifyReply): void {
+  // Never echo the raw Stripe/internal error — it may embed request params
+  // (customer ids, line-item text) or internal detail.
+  reply.status(500).send({
+    ok: false,
+    error: { code: "internal_error", message: "Something went wrong." },
+  });
+}
+
+// ── Guards ────────────────────────────────────────────────────────────────────
+
+/**
+ * The site-admin role set. `User.role` is a per-deployment String
+ * ("user" | "admin" | "owner") — DISTINCT from the org-membership `Role` enum
+ * the multi-tenant module uses. Named rather than compared inline so the next
+ * role change is one greppable edit per template; mirrored from
+ * `payment-link-route.template.ts:135` because these are copied-not-imported
+ * scaffold sources with nowhere to share a constant (AILK#3765).
+ */
+const SITE_ADMIN_ROLES: ReadonlySet<string> = new Set(["admin", "owner"]);
+
+/**
+ * Gate 1 — requires an authenticated, site-admin caller. `request.userId` is
+ * populated by `authPreHandlerPlugin` (see the Registration note above); this
+ * re-checks it defensively rather than trusting registration order blindly.
+ * Sends the 401/403 itself and returns `null` on denial; the caller's handler
+ * must `return` immediately when this returns `null`.
+ */
+async function requireSiteAdmin(
+  request: FastifyRequest,
+  reply: FastifyReply,
+): Promise<string | null> {
+  const userId = request.userId;
+  if (!userId) {
+    unauthorized(reply);
+    return null;
+  }
+
+  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.
+    //
+    // Unwrapped, a rejection here escapes to Fastify's default error handler,
+    // which serializes `error.message` back to the caller — contradicting this
+    // file's own contract above (`serverError`: "Never echo the raw
+    // Stripe/internal error"). It always denied; it denied while leaking.
+    request.log.error(
+      {
+        method: request.method,
+        path: request.url,
+        message: err instanceof Error ? err.message : "unknown",
+      },
+      "[invoices] role resolution failed; DENYING",
+    );
+    serverError(reply);
+    return null;
+  }
+
+  // A missing user row (deleted account, stale session) has no role -> denied.
+  if (!role || !SITE_ADMIN_ROLES.has(role)) {
+    forbidden(reply);
+    return null;
+  }
+
+  return userId;
+}
+
+/**
+ * Gate 2 — the tenancy guard (the fix for the cross-tenant invoice-PII IDOR).
+ *
+ * v1 resolves ONE deployment-wide `STRIPE_SECRET_KEY` and has NO per-org
+ * Stripe customer namespace, so an invoice carries no organization
+ * attribution: there is no honest way to check a caller-supplied `invoiceId` /
+ * `customerId` against the caller's org. Rather than ship an unscoped admin
+ * surface, this guard admits ONLY the deployment's own operator org — the
+ * well-known single-tenant sentinel `DEFAULT_ORG_ID` — and refuses everyone
+ * else, before any Stripe call.
+ *
+ * Two refusals, both fail-closed. Returns `true` only when the request is safe
+ * to serve; sends the 403 itself otherwise, so the caller's handler must
+ * `return` immediately on `false`.
+ *
+ *   - No `request.tenant` → 403. `tenantPreHandlerPlugin` denies an
+ *     unresolvable tenant before this handler runs, so reaching here means the
+ *     plugin was mis-registered OUTSIDE `tenantScope`. Deny rather than serve
+ *     unscoped.
+ *   - The caller's org is NOT the default/operator org → 403
+ *     `tenancy_unsupported`. `DEFAULT_ORG_ID` is a fixed reserved-range
+ *     sentinel minted only by the single-tenant provision path
+ *     (`resolveSingleTenantDefault`); an organization created through the
+ *     multi-tenant module NEVER carries it. So a tenant org's admin — the
+ *     caller who could otherwise read another tenant's customer PII (names,
+ *     emails, amounts, line items) out of the shared Stripe account — is
+ *     refused outright. This is the IDOR being closed.
+ *
+ * The org is read from `request.tenant` (server-derived — there is no
+ * client-supplied org id, so cross-tenant enumeration is structurally
+ * impossible) and the refusal is byte-identical for every `invoiceId`, so it
+ * is no enumeration oracle.
+ *
+ * KNOWN RESIDUAL (disclosed, not silently accepted): the DEPLOYMENT OPERATOR
+ * (the default org, site-admin role) can still see every invoice in the
+ * deployment-wide Stripe account, including invoices raised for other orgs.
+ * That is NOT a privilege escalation — the operator holds the
+ * `STRIPE_SECRET_KEY` and can read exactly the same data from the Stripe
+ * dashboard. It is nonetheless why the per-org Stripe Connect /
+ * customer-namespace follow-up still matters: until it lands, invoice
+ * management is an OPERATOR surface, not a per-tenant self-service one.
+ */
+async function requireSingleTenantScope(
+  request: FastifyRequest,
+  reply: FastifyReply,
+): Promise<boolean> {
+  const tenant = request.tenant;
+  if (!tenant) {
+    forbidden(reply);
+    return false;
+  }
+
+  if (tenant.organizationId !== DEFAULT_ORG_ID) {
+    tenancyUnsupported(reply);
+    return false;
+  }
+
+  return true;
+}
+
+// ── Input validation ──────────────────────────────────────────────────────────
+
+/**
+ * `createInvoice` issues ONE sequential Stripe API call per line item, so an
+ * unbounded array turns a single POST into thousands of upstream calls
+ * (request-thread exhaustion + Stripe rate-limit burn). Bound it.
+ */
+const MAX_LINE_ITEMS = 50;
+/** 99_999_999 minor units = $999,999.99 — a sane ceiling on one line item. */
+const MAX_AMOUNT_MINOR = 99_999_999;
+
+const createInvoiceBodySchema = z.object({
+  customerId: z.string().min(1).max(255),
+  items: z
+    .array(
+      z.object({
+        description: z.string().min(1).max(500),
+        amountMinor: z.number().int().positive().max(MAX_AMOUNT_MINOR),
+        currency: z
+          .string()
+          .length(3)
+          .regex(/^[A-Za-z]{3}$/, "currency must be an ISO-4217 code"),
+        quantity: z.number().int().positive().max(1000).optional(),
+      }),
+    )
+    .min(1)
+    .max(MAX_LINE_ITEMS),
+  description: z.string().max(1000).optional(),
+});
+
+const sendInvoiceBodySchema = z.object({
+  invoiceId: z.string().min(1).max(255),
+});
+
+const listQuerySchema = z.object({
+  customerId: z.string().min(1).max(255).optional(),
+  invoiceId: z.string().min(1).max(255).optional(),
+});
+
+// ── Routes ────────────────────────────────────────────────────────────────────
+
+export const invoiceRoutes: FastifyPluginAsync = async (fastify) => {
+  // GET /v1/commerce/invoices — list, or retrieve one via ?invoiceId=
+  fastify.get("/v1/commerce/invoices", async (request, reply) => {
+    if (!(await requireSiteAdmin(request, reply))) return;
+    if (!(await requireSingleTenantScope(request, reply))) return;
+
+    const query = listQuerySchema.safeParse(request.query);
+    if (!query.success) return invalidBody(reply);
+
+    try {
+      loadStripeSurfaceConfig();
+      if (query.data.invoiceId) {
+        const invoice = await retrieveInvoice({
+          invoiceId: query.data.invoiceId,
+        });
+        return reply.send({ ok: true, data: invoice });
+      }
+      const result = await listInvoices(
+        query.data.customerId ? { customerId: query.data.customerId } : {},
+      );
+      return reply.send({ ok: true, data: result });
+    } catch {
+      return serverError(reply);
+    }
+  });
+
+  // POST /v1/commerce/invoices — create a draft invoice
+  fastify.post("/v1/commerce/invoices", async (request, reply) => {
+    if (!(await requireSiteAdmin(request, reply))) return;
+    if (!(await requireSingleTenantScope(request, reply))) return;
+
+    const parsed = createInvoiceBodySchema.safeParse(request.body);
+    if (!parsed.success) return invalidBody(reply);
+
+    try {
+      loadStripeSurfaceConfig();
+      const created = await createInvoice(parsed.data);
+      return reply.status(201).send({ ok: true, data: created });
+    } catch {
+      return serverError(reply);
+    }
+  });
+
+  // POST /v1/commerce/invoices/send — finalize + send a draft (draft → open)
+  fastify.post("/v1/commerce/invoices/send", async (request, reply) => {
+    if (!(await requireSiteAdmin(request, reply))) return;
+    if (!(await requireSingleTenantScope(request, reply))) return;
+
+    const parsed = sendInvoiceBodySchema.safeParse(request.body);
+    if (!parsed.success) return invalidBody(reply);
+
+    try {
+      loadStripeSurfaceConfig();
+      const sent = await sendInvoice(parsed.data);
+      return reply.send({ ok: true, data: sent });
+    } catch {
+      return serverError(reply);
+    }
+  });
+};