create-ailk 0.2.0 → 0.3.0

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

@@ -1,365 +0,0 @@
-/**
- * Billing-portal session route — instantiated by `scaffold-commerce`'s
- * surface-selection branch (SKILL.md § Step 10i, FEAT-023 U6). Lands at,
- * e.g., `apps/api/src/routes/commerce/portal.ts`. Mints a Stripe
- * billing-portal session for a caller-supplied `customerId` and returns the
- * hosted portal `url` for the client to redirect to — the smallest FEAT-023
- * surface (spec §1: AILK owns only the entry; Stripe hosts the portal
- * itself). Consumes `@working-theory/stripe-client`'s
- * `createBillingPortalSession` directly — no new client method (spec §3
- * design decision).
- *
- * Registration (mirrors `invoice-route.template.ts` /
- * `subscription-route.template.ts`'s READ handler — an AUTHENTICATED +
- * TENANT-GUARDED management action, inside the TENANT-GUARDED scope
- * `apps/api`'s `billingRoutes` use):
- *
- *     await tenantScope.register(portalRoutes);
- *
- * ── Auth posture — mirrors the invoice/subscription READ handlers exactly ──
- * Starting a billing-portal session hands the caller a live, time-bounded
- * (Stripe-expiring) link into a CUSTOMER'S full billing surface — invoices,
- * payment methods, plan changes — for whichever `customerId` is supplied.
- * So this is a MANAGEMENT-shaped action, never public/anonymous/self-service
- * by session identity (v1's single-tenant commerce module has no
- * customer-facing login/session layer of its own — see
- * `docs/research/commerce-template-audit/portal.md`), gated by the SAME two
- * guards `invoiceRoutes` / `subscriptionRoutes` use on their read side:
- *
- *   1. `requireSiteAdmin` — `User.role` in {"admin","owner"}, re-read from
- *      the DB per request. Entitlement (`hasFeature("commerce")`) is NOT
- *      authorization — see the sibling templates' header comments for the
- *      AILK#3744 lesson this repeats (a P0 that let an anonymous caller
- *      manage payment links behind entitlement alone).
- *   2. `requireSingleTenantScope` — v1 has ONE deployment-wide
- *      `STRIPE_SECRET_KEY` and no per-organization Stripe customer
- *      namespace, so a `customerId` carries no org attribution and cannot be
- *      honestly checked against the caller's org. Admits ONLY the
- *      deployment's own operator org (`DEFAULT_ORG_ID`) and refuses every
- *      other org's admin with `tenancy_unsupported`, before any Stripe call
- *      — mirrors `invoice-route.template.ts` / `subscription-route.template.ts`
- *      verbatim (same v1 tenancy limitation).
- *
- * ── Return URL — server-derived, never caller-supplied ──────────────────────
- * Unlike checkout's `successUrl`/`cancelUrl` (a caller-chosen destination,
- * validated same-origin), the portal's return URL is a SINGLE fixed path
- * (`PORTAL_RETURN_PATH`) composed server-side from `FRONTEND_URL` — mirrors
- * `apps/api/src/routes/billing/portal.ts`'s existing convention (the
- * multi-tenant workspace module's own billing-portal route, a different
- * surface — `packages/stripe-client` is single-tenant, that route is
- * org-scoped via `request.tenant.organizationId`). There is no
- * caller-supplied return destination to validate, so the open-redirect
- * vector `checkout-route.template.ts`'s `toSameOriginRedirect` guards
- * against does not apply here — it is closed by construction (spec §8 open
- * question resolution: "follows the existing apps/api checkout return
- * handling" — same FRONTEND_URL-anchored approach, simplified to a fixed
- * path since the portal has only one return destination).
- *
- * TEST-MODE ONLY (v1) — inherits `loadStripeSurfaceConfig()`'s
- * `assertSandboxKey` guard exactly as every other U2–U6 surface does.
- * `assertSandboxKey` (`packages/stripe-client/src/client.ts`) is an
- * ALLOW-LIST as of AILK#3734 — the three recognized sandbox-only prefixes
- * only, so Stripe's restricted key type is refused here too when it is not
- * one of those sandbox prefixes, not merely the two unrestricted ones.
- *
- * Error mapping (mirrors `apps/api/src/routes/billing/portal.ts`'s shape):
- *   400 invalid_body        — Zod validation failed (missing/invalid customerId)
- *   401 unauthorized        — no authenticated caller
- *   403 forbidden           — authenticated but not admin/owner
- *   403 tenancy_unsupported — caller's org is not the deployment's operator org
- *   500 live-mode-forbidden — the configured Stripe key is a LIVE key
- *   500 config-error        — the Stripe/site env is missing or misconfigured
- *   502 portal-unavailable  — Stripe SDK threw an unexpected error
- */
-import { DEFAULT_ORG_ID } from "@working-theory/database/tenancy";
-import type {
-  FastifyPluginAsync,
-  FastifyReply,
-  FastifyRequest,
-} from "fastify";
-import { z } from "zod";
-
-import {
-  createBillingPortalSession,
-  StripeConfigError,
-} from "@working-theory/stripe-client";
-
-import { prisma } from "../../lib/prisma.js";
-import { loadStripeSurfaceConfig } from "./stripe-config.js";
-
-// ── Response helpers (no PII, no raw error echo — mirrors invoice/subscription-route) ──
-
-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." },
-  });
-}
-
-/** Identical for EVERY request — leaks no information about which customers exist (no enumeration oracle). */
-function tenancyUnsupported(reply: FastifyReply): void {
-  reply.status(403).send({
-    ok: false,
-    error: {
-      code: "tenancy_unsupported",
-      message:
-        "Billing-portal sessions are unavailable on a multi-tenant deployment: v1 has no per-organization Stripe customer namespace, so a customer cannot be attributed to an organization.",
-    },
-  });
-}
-
-function invalidBody(reply: FastifyReply): void {
-  reply.status(400).send({
-    ok: false,
-    error: { code: "invalid_body", message: "Invalid request." },
-  });
-}
-
-function liveModeForbidden(reply: FastifyReply): void {
-  reply.status(500).send({
-    ok: false,
-    error: {
-      code: "live-mode-forbidden",
-      message: "Live Stripe keys are not permitted.",
-    },
-  });
-}
-
-function configError(reply: FastifyReply): void {
-  reply.status(500).send({
-    ok: false,
-    error: { code: "config-error", message: "Billing portal is misconfigured." },
-  });
-}
-
-/**
- * A generic internal failure. Distinct from `configError`, which asserts
- * something specific about the deployment's Stripe/site env; this one says
- * nothing at all, because it is used where the cause must not reach the caller.
- * Never echo the raw error — it may embed request params or internal detail.
- */
-function serverError(reply: FastifyReply): void {
-  reply.status(500).send({
-    ok: false,
-    error: { code: "internal_error", message: "Something went wrong." },
-  });
-}
-
-function portalUnavailable(reply: FastifyReply): void {
-  reply.status(502).send({
-    ok: false,
-    error: {
-      code: "portal-unavailable",
-      message: "Billing portal is temporarily unavailable.",
-    },
-  });
-}
-
-// ── Guards (mirrors invoice-route.template.ts / subscription-route.template.ts verbatim) ──
-
-/**
- * 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. 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 no-raw-echo contract. It always denied; it denied while
-    // leaking.
-    request.log.error(
-      {
-        method: request.method,
-        path: request.url,
-        message: err instanceof Error ? err.message : "unknown",
-      },
-      "[portal] 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. v1 resolves ONE deployment-wide
- * `STRIPE_SECRET_KEY` and has no per-org Stripe customer namespace, so a
- * `customerId` carries no organization attribution — this guard admits ONLY
- * the deployment's own operator org (the fixed single-tenant sentinel
- * `DEFAULT_ORG_ID`) and refuses everyone else, before any Stripe call.
- * Mirrors `invoice-route.template.ts` / `subscription-route.template.ts`
- * verbatim.
- */
-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;
-}
-
-// ── Return URL — server-derived, fixed path (see header comment) ─────────────
-
-/**
- * Where the customer lands after leaving Stripe's hosted portal —
- * SCAFFOLD-TIME EDIT if the consumer's account/billing page lives elsewhere.
- * Composed server-side onto `FRONTEND_URL`; never caller-supplied.
- */
-const PORTAL_RETURN_PATH = "/account/billing";
-
-/** Site's own origin composed with `PORTAL_RETURN_PATH` — mirrors `checkout-route.template.ts`'s `loadSiteOrigin()`. */
-function loadReturnUrl(): string {
-  const raw = process.env.FRONTEND_URL;
-  if (!raw) {
-    throw new Error(
-      "FRONTEND_URL is missing. It is the site origin the billing-portal return URL is composed onto.",
-    );
-  }
-  let origin: URL;
-  try {
-    origin = new URL(raw);
-  } catch {
-    throw new Error("FRONTEND_URL is not a valid absolute URL.");
-  }
-  return new URL(PORTAL_RETURN_PATH, origin).toString();
-}
-
-// ── Input validation ───────────────────────────────────────────────────────
-
-const portalSessionBodySchema = z.object({
-  /** The consumer's own Stripe customer id (cus_…) for the customer requesting the portal. */
-  customerId: z.string().min(1).max(255),
-});
-
-// ── Route ─────────────────────────────────────────────────────────────────────
-
-/**
- * `portalRoutes` — a single POST endpoint: mint a billing-portal session for
- * `customerId` and return its hosted `url` (retrieve-on-demand, no webhook —
- * mirrors `subscriptionRoutes`'s escalation-boundary posture: no
- * portal-session webhook is scaffolded at v1).
- */
-export const portalRoutes: FastifyPluginAsync = async (fastify) => {
-  // POST /v1/commerce/portal-session
-  fastify.post("/v1/commerce/portal-session", async (request, reply) => {
-    if (!(await requireSiteAdmin(request, reply))) return;
-    if (!(await requireSingleTenantScope(request, reply))) return;
-
-    const parsed = portalSessionBodySchema.safeParse(request.body);
-    if (!parsed.success) return invalidBody(reply);
-
-    let returnUrl: string;
-    try {
-      returnUrl = loadReturnUrl();
-      loadStripeSurfaceConfig();
-    } catch (err) {
-      if (err instanceof StripeConfigError) {
-        request.log.error(
-          { method: request.method, path: request.url, message: err.message },
-          "[portal] session: LIVE Stripe key REFUSED — live-mode-forbidden",
-        );
-        return liveModeForbidden(reply);
-      }
-      request.log.error(
-        {
-          method: request.method,
-          path: request.url,
-          message: err instanceof Error ? err.message : "unknown",
-        },
-        "[portal] session: config error",
-      );
-      return configError(reply);
-    }
-
-    try {
-      const { url } = await createBillingPortalSession({
-        stripeCustomerId: parsed.data.customerId,
-        returnUrl,
-      });
-
-      request.log.info(
-        { method: request.method, path: request.url, status: 200 },
-        "[portal] session created",
-      );
-
-      return reply.status(200).send({ ok: true, data: { url } });
-    } catch (err) {
-      if (err instanceof StripeConfigError) {
-        request.log.error(
-          {
-            method: request.method,
-            path: request.url,
-            errName: err.name,
-            message: err.message,
-          },
-          "[portal] session: config error",
-        );
-        return configError(reply);
-      }
-      request.log.error(
-        {
-          method: request.method,
-          path: request.url,
-          errName: err instanceof Error ? err.name : "unknown",
-        },
-        "[portal] session: stripe error; portal-unavailable",
-      );
-      return portalUnavailable(reply);
-    }
-  });
-};

package/templates/.claude/skills/scaffold-commerce/templates/stripe-config.template.ts

@@ -1,60 +0,0 @@
-/**
- * Shared Stripe surface config — instantiated by each FEAT-023 payment
- * surface scaffolder (checkout · pay-by-link · invoice · subscription ·
- * portal, U2–U6). Centralizes the env-var contract every surface reads and
- * the test-mode-only guard, so no surface re-derives its own copy.
- *
- * Emitted by `scaffold-commerce`'s surface-selection branch (see SKILL.md
- * § Surface-selection branch). Lands in the consumer's own repo — this file
- * is copied/instantiated, not imported from `@working-theory/*`.
- *
- * Test-mode-only enforcement (belt-and-suspenders): `assertSandboxKey`
- * (`@working-theory/stripe-client`) is the SAME guard `getStripeClient()`
- * already applies — reusing it here means a `sk_live_*`/`pk_live_*` value is
- * refused before ANY new surface entry point wires up, not just at the
- * shared Stripe client singleton. v1 is sandbox-only; see
- * `.claude/rules/architecture.md` § Hard floors.
- */
-
-import { assertSandboxKey } from "@working-theory/stripe-client";
-
-export interface StripeSurfaceConfig {
-  secretKey: string;
-  publishableKey: string;
-  /** Set once `stripe listen` (dev) or the platform's webhook endpoint (prod) is wired. */
-  webhookSecret: string | undefined;
-}
-
-/**
- * Read + validate the Stripe env contract for a payment surface.
- *
- * Throws when:
- * - `STRIPE_SECRET_KEY` or `STRIPE_PUBLISHABLE_KEY` is missing — the
- *   consumer hasn't run `scaffold-commerce`'s direct-payments path yet.
- * - Either key is live-mode (`sk_live_*` / `pk_live_*`) — refused, test-mode
- *   only at v1.
- */
-export function loadStripeSurfaceConfig(): StripeSurfaceConfig {
-  const secretKey = process.env.STRIPE_SECRET_KEY;
-  const publishableKey = process.env.STRIPE_PUBLISHABLE_KEY;
-
-  if (!secretKey) {
-    throw new Error(
-      "STRIPE_SECRET_KEY is missing. Run scaffold-commerce (direct payments path) first.",
-    );
-  }
-  if (!publishableKey) {
-    throw new Error(
-      "STRIPE_PUBLISHABLE_KEY is missing. Run scaffold-commerce (direct payments path) first.",
-    );
-  }
-
-  assertSandboxKey(secretKey);
-  assertSandboxKey(publishableKey);
-
-  return {
-    secretKey,
-    publishableKey,
-    webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
-  };
-}