create-ailk 0.2.0 → 0.4.0

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

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

package/templates/.claude/skills/scaffold-commerce/templates/marketplace-cta-route.tsx.tmpl

@@ -1,72 +0,0 @@
-// Emitted by `scaffold-commerce` (link path). Owns its own
-// <MarketplaceCTA> component definition — not imported from
-// @working-theory/ui — so you can edit the styling, add tracking, change
-// the icon layout, etc., without forking a shared package.
-//
-// The skill substitutes:
-//   {{HREF}}   — storefront URL (e.g., https://amazon.com/my-shop)
-//   {{LABEL}}  — button text (e.g., "Buy on Amazon")
-//   {{ICON}}   — optional iconSrc prop binding (e.g., iconSrc="/logos/amazon.svg")
-//                or empty when the consumer chose text-only
-
-import type { ReactNode } from "react";
-
-interface MarketplaceCTAProps {
-  href: string;
-  label: ReactNode;
-  iconSrc?: string;
-  className?: string;
-}
-
-/**
- * MarketplaceCTA — outbound link to an external storefront.
- *
- * Renders a single anchor styled as a button. Optional iconSrc renders
- * a small <img> next to the label; omitting it produces a clean
- * text-only button. Customize freely — this component is yours, not
- * a shared dep.
- */
-function MarketplaceCTA({
-  href,
-  label,
-  iconSrc,
-  className,
-}: MarketplaceCTAProps) {
-  const baseClasses =
-    "inline-flex items-center gap-2 rounded-md border border-current px-4 py-2 text-sm font-medium hover:bg-current/5 transition-colors";
-  const finalClassName = className
-    ? `${baseClasses} ${className}`
-    : baseClasses;
-
-  return (
-    <a
-      href={href}
-      target="_blank"
-      rel="noopener noreferrer"
-      className={finalClassName}
-    >
-      {iconSrc ? (
-        <img src={iconSrc} alt="" aria-hidden="true" className="h-5 w-5" />
-      ) : null}
-      <span>{label}</span>
-    </a>
-  );
-}
-
-export default function BuyPage() {
-  return (
-    <main className="mx-auto max-w-2xl px-6 py-12">
-      <h1 className="text-3xl font-semibold">Get yours</h1>
-      <p className="mt-3 text-muted-foreground">
-        Available at our store on the marketplace below.
-      </p>
-      <div className="mt-8">
-        <MarketplaceCTA
-          href="{{HREF}}"
-          label="{{LABEL}}"
-          {{ICON}}
-        />
-      </div>
-    </main>
-  );
-}