create-ailk 0.2.0 → 0.3.0

package/templates/.claude/skills/scaffold-commerce/references/lookup-keys-template.md

@@ -1,71 +0,0 @@
-# Lookup Keys — generated by `scaffold-commerce`
-
-This file lists every Stripe product the `scaffold-commerce` skill
-created in your test-mode account. The skill writes one row per
-product as it goes; re-running the skill appends new rows under
-"## Added by re-run YYYY-MM-DD".
-
-## How to use this file
-
-Stripe `lookup_key`s are stable identifiers — they survive price
-recreates (e.g., when you change an amount, you can keep the same
-`lookup_key`). They're the canonical reference for AILK pricing UI.
-
-When wiring a pricing page (e.g., from `scaffold-page` (#362) on a
-`Product` slug), refer to `lookup_key` in your code:
-
-```ts
-// apps/web/app/pricing/page.tsx
-const PRICING_LOOKUP_KEYS = ["pro_monthly", "team_monthly"];
-
-// Server-side fetch (apps/api):
-const prices = await stripe.prices.list({
-  lookup_keys: PRICING_LOOKUP_KEYS,
-  expand: ["data.product"],
-});
-```
-
-The pricing page renders from `prices`. If you change a price's
-amount in the Stripe dashboard later, the `lookup_key` resolves to
-the new price automatically — no app-code change needed.
-
-## Products created this session
-
-(The skill fills this table during Step 8 of the Stripe path. Empty
-on first emit; populated as products are created.)
-
-| Product    | Lookup key | Amount | Interval | Stripe ID |
-| ---------- | ---------- | ------ | -------- | --------- |
-| _none yet_ | _ -_       | _-_    | _-_      | _-_       |
-
-Example after a session that created two products:
-
-| Product   | Lookup key     | Amount     | Interval | Stripe ID        |
-| --------- | -------------- | ---------- | -------- | ---------------- |
-| Pro plan  | `pro_monthly`  | $29.00 USD | monthly  | `price_1XXXX...` |
-| Team plan | `team_monthly` | $99.00 USD | monthly  | `price_1YYYY...` |
-
-## Re-running the skill
-
-If you re-run `scaffold-commerce` and add more products:
-
-- Existing rows are not modified.
-- New products land under `## Added by re-run <DATE>` heading at the
-  end of the file.
-- Conflict-handling (skill Step 4) means existing `lookup_key`s are
-  never silently changed — you'll be asked to keep / overwrite /
-  pick a different key.
-
-## Pointers
-
-- **Pricing page UI:** `scaffold-page` (#362) on a `Product` slug.
-  Wire the `PRICING_LOOKUP_KEYS` array to point at the keys above.
-- **Production webhook:** `provision-config` (#367). Dev-mode
-  webhook is set up via `stripe listen` per skill Step 7.
-- **Sandbox-only at v1:** AILK rejects live keys (`sk_live_*`,
-  `pk_live_*`) at multiple layers. Production setup is a future
-  deploy lane.
-- **Stripe dashboard:**
-  - Test products: <https://dashboard.stripe.com/test/products>
-  - Test prices: <https://dashboard.stripe.com/test/prices>
-  - Test API keys: <https://dashboard.stripe.com/test/apikeys>

package/templates/.claude/skills/scaffold-commerce/references/marketplace-brand-pages.md

@@ -1,83 +0,0 @@
-# Marketplace Brand Pages
-
-AILK does **not** bundle marketplace logo SVGs (Amazon, Etsy, Shopify,
-eBay, Gumroad). Trademarks are not blanket-licensed for redistribution
-through third-party templates, and shipping them in the AILK template
-chain would put us in the redistribution chain.
-
-Brand recognition value is preserved via the **brand name in the
-button text** ("Buy on Amazon", "View on Etsy"). Consumers who want
-the logo too can fetch it themselves from each marketplace's official
-brand-kit page (links below) and drop it in their own `public/logos/`
-directory, then pass `iconSrc="/logos/amazon.svg"` to
-`<MarketplaceCTA>`.
-
-Each link below points at the marketplace's first-party brand-asset
-page. URLs may change; if a link breaks, search "<marketplace> brand
-guidelines" or "<marketplace> press kit" — the canonical source is
-always the marketplace's own brand site.
-
-## Amazon
-
-- **Brand assets:** <https://brand.amazon.com> (US Brand Standards)
-- **Press / logo:** <https://www.aboutamazon.com/news/company-news/press-room>
-- Notes: Amazon's brand guidelines restrict use of the smile-arrow
-  logo. The "Available at Amazon" badge is the consumer-permitted
-  affiliate-style asset.
-
-## Etsy
-
-- **Press kit:** <https://www.etsy.com/press>
-- **Logo + brand guidelines:** linked from the press page.
-- Notes: "Sell on Etsy" assets are for sellers; "Available on Etsy"
-  / "Buy on Etsy" buttons are appropriate for outbound links.
-
-## Shopify
-
-- **Brand assets:** <https://www.shopify.com/news/brand-assets> (or
-  search "Shopify brand guidelines")
-- Notes: Shopify provides logo files for partners; consumers using
-  Shopify as their backend can typically use the logo in
-  reasonable-context "Powered by Shopify" / "Buy on our Shopify
-  store" buttons.
-
-## eBay
-
-- **Brand center:** <https://partnernetwork.ebay.com/marketing-center>
-  (eBay Partner Network — affiliate context)
-- **Press / logo:** <https://www.ebayinc.com/company/press-room>
-- Notes: eBay distinguishes affiliate-context use (covered by EPN
-  assets) from general use. For "View on eBay" buttons linking to a
-  specific seller's storefront, the EPN assets apply.
-
-## Gumroad
-
-- **Brand assets:** <https://gumroad.com> (search the footer for
-  "press" or "brand"; Gumroad's logo policy is permissive for
-  outbound links to creator pages)
-- Notes: simplest of the five; Gumroad's logo and "Available on
-  Gumroad" badge are typically copyable directly from their
-  about/press surface.
-
-## Custom storefronts
-
-If the consumer has their own storefront (Webflow, Squarespace,
-Bigcartel, custom-built), they don't need a marketplace logo — a
-plain "Buy now" or "Shop" button works. The `iconSrc` prop is
-optional.
-
-## Legal note (no legal advice)
-
-- Trademarks are owned by the marketplaces. AILK does not grant
-  permission to use any marketplace logo; the consumer's use is
-  governed by each marketplace's brand guidelines.
-- For affiliate context (consumer earns a referral fee), most
-  marketplaces have explicit affiliate-asset programs (Amazon
-  Associates, eBay Partner Network, etc.) with permitted logo use.
-- For non-affiliate "I have a store there, send people to it"
-  context, the marketplace's general brand guidelines apply. When
-  in doubt, the brand name in text only — `Buy on {marketplace}`
-  — is always safe.
-
-This file is informational. Consumers responsible for compliance
-with each marketplace's brand guidelines for their specific use.

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

@@ -1,370 +0,0 @@
-/**
- * One-time checkout route — scaffolded by `scaffold-commerce`'s checkout
- * surface (FEAT-023 U2, Step 10e). Instantiated into the consumer's own
- * `apps/api/src/routes/checkout/` (Fastify — checkout creation is
- * server-side only, architecture.yaml `apps/web.may_not_import_from:
- * packages/stripe-client`). Register the exported handler on a POST route,
- * scoped behind the shared per-IP rate-limit middleware (mirrors the "leads
- * routes" anonymous-write registration pattern in `apps/api/src/server.ts`
- * — this route is exactly that shape: an anonymous write with no auth):
- *
- *   await fastify.register(async (checkoutScope) => {
- *     checkoutScope.register(rateLimitMiddleware); // apps/api/src/middleware/rate-limit.ts
- *     checkoutScope.post("/api/checkout/one-time", oneTimeCheckoutHandler);
- *   });
- *
- * ── SCAFFOLD-TIME EDITS REQUIRED (both — the route is fail-closed until then) ─
- *   1. `ALLOWED_LOOKUP_KEYS` below — replace the placeholder with the
- *      lookup_key(s) this surface may sell (Step 10e-i step 1's selection).
- *      Until you do, EVERY request 404s. That is deliberate.
- *   2. `FRONTEND_URL` in the consumer's API env — the site origin every
- *      checkout redirect is locked to. Unset ⇒ this route 500s `config-error`.
- *
- * ── Auth posture — PUBLIC BY DESIGN, not an oversight ──────────────────────
- * This handler is intentionally UNAUTHENTICATED. It is a storefront "buy"
- * action, not a management endpoint — it does exactly ONE thing: create a
- * NEW Stripe Checkout Session for ONE OF THE PRODUCTS THIS SURFACE WAS
- * SCAFFOLDED TO SELL (`ALLOWED_LOOKUP_KEYS`, enforced server-side before any
- * Stripe call; the caller can neither name an arbitrary price nor set an
- * amount — the price is resolved server-side via
- * `stripe.prices.list({lookup_keys})` inside `createCheckoutSession`).
- * It has:
- *   - NO list/read of existing sessions, products, or any other data,
- *   - NO update/delete/archive of anything,
- *   - NO local database read or write (stateless — the only side effect is
- *     a new object created directly in the site owner's own Stripe account),
- *   - NO cross-tenant surface (single-tenant `packages/stripe-client`
- *     commerce catalog; the multi-tenant module's org-scoped billing is a
- *     SEPARATE surface — `apps/workspace` may not import `stripe-client` at
- *     all, architecture.yaml — so there is no tenant to scope this route to).
- * A management surface (list/update/archive payment objects) is a DIFFERENT
- * shape and MUST be authenticated + tenant-scoped — do not use this handler
- * as a pattern for one.
- *
- * NOT a mirror of `apps/api/src/routes/checkout/sessions.ts`'s auth posture.
- * That route carries an env-conditional `X-Internal-Auth` gate
- * (`OSS_API_INTERNAL_SECRET`, #935); this one deliberately does not — it is
- * public on purpose. If you have set `OSS_API_INTERNAL_SECRET` to lock
- * `/v1/checkout/sessions` to internal callers, be aware that registering THIS
- * route adds a second, ungated checkout entry point to the same API. Add your
- * own gate here if that is not what you want.
- *
- * ── Abuse hardening ─────────────────────────────────────────────────────
- * An unauthenticated session-creation endpoint is a known "card testing"
- * target (repeated session-creation attempts against stolen card numbers).
- * The registration example above wires the shared per-IP rate-limit
- * middleware for exactly this reason — do not register this route without
- * it. AILK's `apps/api/src/server.ts` also registers a GLOBAL rate limit, but
- * it is IN-MEMORY: on a multi-instance or serverless deployment it does not
- * bound the aggregate rate, so back it with a shared store (e.g. Redis) before
- * taking real traffic. Input is otherwise tightly bounded: `lookupKey` must be
- * in `ALLOWED_LOOKUP_KEYS`, `quantity` is clamped 1-999, and
- * `successUrl`/`cancelUrl` are origin-locked to the site's own origin.
- *
- * Design decision (spec § 3): consumes `stripe-client/checkout.ts` directly
- * — no new client method. One-time payment is `mode: "payment"` on the
- * existing Checkout Session call (pinned here, never caller-overridable, so
- * this endpoint can never be used to open a subscription session).
- *
- * Config: loads via the sibling `loadStripeSurfaceConfig()`
- * (`stripe-config.template.ts`, instantiated alongside this file at Step
- * 10d) rather than re-deriving env access — the SAME `assertSandboxKey`
- * test-mode-only guard `getStripeClient()` already applies is enforced again
- * here, belt-and-suspenders, before any Stripe call. This route deliberately
- * does NOT hand-roll its own live-key prefix check — it defers ENTIRELY to
- * the shared `assertSandboxKey` guard (`packages/stripe-client/src/client.ts`)
- * so it inherits that guard's coverage (and any future fix to it) rather than
- * risking a second, divergent implementation.
- *
- * Security invariants:
- *   - Allowlisted products only: a `lookupKey` outside `ALLOWED_LOOKUP_KEYS` is
- *     refused BEFORE any Stripe call, with the same response shape as a
- *     genuinely-unknown price (so the 404 is not an enumeration oracle).
- *   - Origin-locked redirects: `successUrl`/`cancelUrl` may only resolve to
- *     this site's own origin. An attacker cannot mint a real Checkout Session
- *     for this merchant that lands the paying victim on an attacker page.
- *   - Sandbox-only: a live Stripe key is rejected before any Stripe call.
- *   - No PII in logs: successUrl/cancelUrl and full session ids are never
- *     logged — only the first 8 chars of the session id.
- *   - Error responses never echo user input (lookupKey, URLs).
- *
- * Error mapping:
- *   400 validation-error      — Zod validation failed (missing/invalid fields)
- *   400 invalid-redirect-url  — successUrl/cancelUrl does not resolve same-origin
- *   404 unknown-product-code  — lookupKey is not allowlisted for this surface,
- *                               OR no active Stripe price exists for it (the
- *                               404 deliberately does not distinguish the two)
- *   429 rate_limited          — per-IP rate limit exceeded (see registration example above)
- *   500 live-mode-forbidden   — the configured Stripe key is a LIVE key
- *   500 config-error          — the Stripe/site env is missing or misconfigured
- *   502 checkout-unavailable  — Stripe SDK threw an unexpected error
- */
-import type { FastifyReply, FastifyRequest } from "fastify";
-import { z } from "zod";
-import {
-  createCheckoutSession,
-  StripeConfigError,
-  UnknownProductCodeError,
-} from "@working-theory/stripe-client";
-
-// Sibling file instantiated at Step 10d — same directory as this route.
-import { loadStripeSurfaceConfig } from "./stripe-config.js";
-
-// ── Purchasable-product allowlist — SCAFFOLD-TIME EDIT ────────────────────────
-
-/**
- * The ONLY lookup_keys this surface is allowed to sell.
- *
- * Without this allowlist the route resolves a caller-supplied `lookupKey`
- * against the merchant's ENTIRE Stripe account — so ANY active price in it (a
- * privately-negotiated discount, an internal comp price, a $0 test price)
- * becomes publicly purchasable by an anonymous caller who guesses or
- * enumerates its key. Pin the products, not the account.
- *
- * scaffold-commerce Step 10e-i replaces the placeholder below with the
- * lookup_key(s) the consumer selected at step 1. Until it does, no request
- * reaches Stripe — fail-closed.
- */
-const ALLOWED_LOOKUP_KEYS: ReadonlySet<string> = new Set<string>([
-  "REPLACE_WITH_YOUR_STRIPE_LOOKUP_KEY",
-]);
-
-// ── Input validation schema ───────────────────────────────────────────────────
-
-const LOOKUP_KEY_REGEX = /^[A-Za-z0-9._-]{1,200}$/;
-
-/**
- * Redirects are validated in TWO stages:
- *   1. here — shape only (non-empty, bounded length), because the site origin
- *      they must match is env-derived and so only known at request time;
- *   2. `toSameOriginRedirect()` — the actual origin lock, applied after config
- *      load. THAT is the security-bearing check; this schema is not.
- */
-const REDIRECT_MAX_LENGTH = 2048;
-
-const OneTimeCheckoutRequestSchema = z.object({
-  lookupKey: z
-    .string()
-    .regex(LOOKUP_KEY_REGEX, "lookupKey must match /^[A-Za-z0-9._-]{1,200}$/"),
-  successUrl: z
-    .string()
-    .min(1, "successUrl is required")
-    .max(REDIRECT_MAX_LENGTH, "successUrl is too long"),
-  cancelUrl: z
-    .string()
-    .min(1, "cancelUrl is required")
-    .max(REDIRECT_MAX_LENGTH, "cancelUrl is too long"),
-  quantity: z.number().int().min(1).max(999).optional(),
-});
-
-// ── Internal helpers (not exported — this module's only export is the handler) ─
-
-/**
- * The site's own origin — the ONLY origin a checkout redirect may resolve to.
- *
- * `FRONTEND_URL` is the env var the consumer's `apps/api` already uses for its
- * CORS origin (`apps/api/src/config/index.ts`), reused here rather than
- * inventing a second site-origin contract. Fail-closed: unset or unparseable ⇒
- * `config-error`, never a permissive default.
- */
-function loadSiteOrigin(): URL {
-  const raw = process.env.FRONTEND_URL;
-  if (!raw) {
-    throw new Error(
-      "FRONTEND_URL is missing. It is the site origin checkout redirects are locked to.",
-    );
-  }
-  try {
-    return new URL(raw);
-  } catch {
-    throw new Error("FRONTEND_URL is not a valid absolute URL.");
-  }
-}
-
-/**
- * Resolve a caller-supplied redirect against the site's own origin. Returns the
- * absolute same-origin URL, or `null` if the redirect lands ANYWHERE else.
- *
- * A relative path ("/checkout/success") is composed server-side onto the site
- * origin — the recommended shape. An absolute URL is accepted only if it is
- * exactly same-origin (scheme + host + port). Everything else — another host, a
- * look-alike host, a non-http(s) scheme (`javascript:`, `data:`, …) — is `null`.
- *
- * Why this is security-bearing: without the origin lock, an anonymous caller
- * can create a REAL Checkout Session for the REAL merchant whose `success_url`
- * points at a site the attacker controls. The victim sees the merchant's real
- * branding on Stripe's real domain, pays, and is redirected to the attacker —
- * an open redirect laundered through a trusted payment page, carrying the
- * credibility of a completed payment. `cancel_url` is the same vector without
- * the victim even having to pay.
- */
-function toSameOriginRedirect(raw: string, siteOrigin: URL): string | null {
-  let resolved: URL;
-  try {
-    resolved = new URL(raw, siteOrigin);
-  } catch {
-    return null;
-  }
-
-  if (resolved.protocol !== "https:" && resolved.protocol !== "http:") {
-    return null;
-  }
-  // Exact origin equality (scheme + host + port). A prefix/suffix comparison
-  // would accept `https://<site-origin>.evil.example`.
-  if (resolved.origin !== siteOrigin.origin) {
-    return null;
-  }
-
-  return resolved.toString();
-}
-
-// ── Handler ───────────────────────────────────────────────────────────────────
-
-/**
- * POST handler — creates a test-mode ONE-TIME (`mode: "payment"`) Checkout
- * Session for `lookupKey` and returns `{ sessionId, url }`. The caller (the
- * scaffolded `CheckoutForm` block's `onCheckout`) redirects the browser to
- * `url` on success.
- *
- * @public-by-design — a storefront "buy" action, intentionally
- * UNAUTHENTICATED (see the file-header "Auth posture" note). It creates ONE
- * allowlisted Checkout Session and reads/mutates nothing else; it is NOT a
- * management surface. The per-handler marker (route-template-auth-gate,
- * #3751) exempts THIS handler from the identity gate — the exemption is
- * per-handler and reviewed, never a file-level blanket.
- */
-export async function oneTimeCheckoutHandler(
-  request: FastifyRequest,
-  reply: FastifyReply,
-): Promise<void> {
-  // ── Config: fail-closed, with an EXPLICIT cause classification ────────────
-  //
-  // The two causes are classified DELIBERATELY, never inferred from whichever
-  // Error subclass the sibling config helper happens to throw:
-  //
-  //   (a) missing env     → `config-error`        — checked HERE, first.
-  //   (b) live Stripe key → `live-mode-forbidden` — with (a) ruled out, the
-  //       only thing `loadStripeSurfaceConfig()`'s `assertSandboxKey` can
-  //       reject, so a StripeConfigError at this point unambiguously means a
-  //       live key.
-  //
-  // Getting this backwards is not cosmetic: it makes the live-mode refusal
-  // signal dead code, and makes a mere missing-env fault cry "live mode
-  // forbidden" — training operators to ignore the one alarm that matters.
-  let siteOrigin: URL;
-  try {
-    if (!process.env.STRIPE_SECRET_KEY || !process.env.STRIPE_PUBLISHABLE_KEY) {
-      throw new Error(
-        "STRIPE_SECRET_KEY / STRIPE_PUBLISHABLE_KEY are missing. Run scaffold-commerce (direct payments path) first.",
-      );
-    }
-    siteOrigin = loadSiteOrigin();
-    loadStripeSurfaceConfig();
-  } catch (err) {
-    if (err instanceof StripeConfigError) {
-      // LIVE KEY — the sandbox-only hard floor. Log loudly: this IS the alarm.
-      request.log.error(
-        { method: request.method, path: request.url, message: err.message },
-        "[checkout] one-time: LIVE Stripe key REFUSED — live-mode-forbidden",
-      );
-      return reply.status(500).send({ error: "live-mode-forbidden" });
-    }
-    request.log.error(
-      {
-        method: request.method,
-        path: request.url,
-        message: err instanceof Error ? err.message : "unknown",
-      },
-      "[checkout] one-time: config error",
-    );
-    return reply.status(500).send({ error: "config-error" });
-  }
-
-  const parsed = OneTimeCheckoutRequestSchema.safeParse(request.body);
-  if (!parsed.success) {
-    return reply.status(400).send({
-      error: "validation-error",
-      details: parsed.error.issues,
-    });
-  }
-
-  const { lookupKey, successUrl, cancelUrl, quantity } = parsed.data;
-
-  // ── Allowlist gate — BEFORE any Stripe call ───────────────────────────────
-  // Same response shape as a genuinely-unknown price (the 404 below), so this
-  // is not an oracle telling an attacker which lookup_keys exist in the
-  // merchant's Stripe account.
-  if (!ALLOWED_LOOKUP_KEYS.has(lookupKey)) {
-    request.log.warn(
-      { method: request.method, path: request.url, status: 404 },
-      "[checkout] one-time: lookupKey is not in this surface's allowlist; refused",
-    );
-    return reply.status(404).send({ error: "unknown-product-code" });
-  }
-
-  // ── Redirect origin lock — BEFORE any Stripe call ─────────────────────────
-  const safeSuccessUrl = toSameOriginRedirect(successUrl, siteOrigin);
-  const safeCancelUrl = toSameOriginRedirect(cancelUrl, siteOrigin);
-  if (safeSuccessUrl === null || safeCancelUrl === null) {
-    // Do NOT echo the rejected URL back to the caller.
-    request.log.warn(
-      { method: request.method, path: request.url, status: 400 },
-      "[checkout] one-time: redirect URL is not same-origin; refused",
-    );
-    return reply.status(400).send({ error: "invalid-redirect-url" });
-  }
-
-  try {
-    // Pinned mode: "payment" — this endpoint can never open a subscription
-    // session, regardless of caller input (spec § 3 design decision).
-    const { sessionId, url } = await createCheckoutSession({
-      productCode: lookupKey,
-      successUrl: safeSuccessUrl,
-      cancelUrl: safeCancelUrl,
-      mode: "payment",
-      quantity: quantity ?? 1,
-    });
-
-    request.log.info(
-      {
-        method: request.method,
-        path: request.url,
-        sessionIdPrefix: sessionId.substring(0, 8),
-        status: 201,
-      },
-      "[checkout] one-time: session created",
-    );
-
-    return reply.status(201).send({ sessionId, url });
-  } catch (err) {
-    if (err instanceof UnknownProductCodeError) {
-      // 404 — do NOT echo lookupKey in the response body.
-      return reply.status(404).send({ error: "unknown-product-code" });
-    }
-    if (err instanceof StripeConfigError) {
-      // Config was already validated above, so this is a late/racing config
-      // fault raised inside `getStripeClient()` (which throws StripeConfigError
-      // for BOTH a missing and a live key — hence the generic mapping here; the
-      // authoritative live-key classification is the pre-flight block above).
-      request.log.error(
-        {
-          method: request.method,
-          path: request.url,
-          errName: err.name,
-          message: err.message,
-        },
-        "[checkout] one-time: config error",
-      );
-      return reply.status(500).send({ error: "config-error" });
-    }
-    request.log.error(
-      {
-        method: request.method,
-        path: request.url,
-        errName: err instanceof Error ? err.name : "unknown",
-      },
-      "[checkout] one-time: stripe error; checkout-unavailable",
-    );
-    return reply.status(502).send({ error: "checkout-unavailable" });
-  }
-}