create-ailk 0.2.0 → 0.3.0

package/templates/apps/api/src/routes/flow-checkouts/index.ts

@@ -1,82 +0,0 @@
-/**
- * Flow-checkouts respondent route (#4984 — the "my purchases" read behind
- * the respondent account surface).
- *
- * Routes:
- *   GET /v1/flow-checkouts/me  — the caller's OWN flow checkouts, newest first
- *
- * Registered INSIDE server.ts's `authScope` (auth only — NOT the inner
- * `tenantScope`: a respondent has no workspace membership, and the tenant
- * guard is default-deny) so `request.userId` is populated by
- * `authPreHandlerPlugin` before the handler runs. An unauthenticated caller
- * receives the preHandler's existing 401, untouched. The identity is
- * `request.userId` ONLY: the route declares no query schema and reads no
- * query or body key (an `email` parameter is never parsed, never read),
- * never enumerates, never reads across sites — see
- * `services/flow-checkouts.ts`, where the only join is the lead-promotion
- * link (`Lead.promotedUserId`), never an email match.
- *
- * Envelope per apps/api/CLAUDE.md: `{ ok: true, data }` /
- * `{ ok: false, error: { code, message } }`, real HTTP status codes:
- *   401 unauthorized · 403 email_unverified · 404 user_not_found ·
- *   500 internal_error (the 200 body failed its own contract schema — a
- *   drift is never a leak). A verified user with nothing to show is a 200
- *   with an empty list.
- *
- * API↔MCP parity: identity-bound (the session IS the identity; the OSS MCP
- * surface is identity-blind) — no MCP twin (#3591 exception, the same shape
- * as `/v1/billing/*`, `/v1/workspaces/*`, `/v1/waitlist-signups/me`).
- */
-import { logger } from "@working-theory/observability";
-import { flowCheckoutMeResponseSchema } from "@working-theory/validation";
-import type { FastifyPluginAsync, FastifyReply } from "fastify";
-
-import { readMyCheckouts } from "../../services/flow-checkouts.js";
-
-function unauthorized(reply: FastifyReply) {
-  return reply.status(401).send({
-    ok: false,
-    error: { code: "unauthorized", message: "Authentication required" },
-  });
-}
-
-const ERROR_STATUS = {
-  not_found_user: 404,
-  email_unverified: 403,
-} as const;
-
-const ERROR_CODE = {
-  not_found_user: "user_not_found",
-  email_unverified: "email_unverified",
-} as const;
-
-export const flowCheckoutRoutes: FastifyPluginAsync = async (fastify) => {
-  fastify.get("/v1/flow-checkouts/me", async (request, reply) => {
-    const userId = request.userId;
-    if (!userId) return unauthorized(reply);
-
-    const result = await readMyCheckouts(userId);
-    if (!result.ok) {
-      return reply.status(ERROR_STATUS[result.error.kind]).send({
-        ok: false,
-        error: { code: ERROR_CODE[result.error.kind], message: result.error.message },
-      });
-    }
-
-    // D5 — re-validate the body against its own strict contract before it
-    // leaves the process (the waitlist-signups idiom): a shape drift is an
-    // internal error, never a leak. Log issues only — never the value.
-    const parsed = flowCheckoutMeResponseSchema.safeParse(result.value);
-    if (!parsed.success) {
-      logger.error(
-        { route: "flow-checkouts/me", issues: parsed.error.issues },
-        "[flow-checkouts] response failed its own contract schema",
-      );
-      return reply.status(500).send({
-        ok: false,
-        error: { code: "internal_error", message: "Response failed contract validation" },
-      });
-    }
-    return reply.status(200).send({ ok: true, data: parsed.data });
-  });
-};

package/templates/apps/api/src/routes/flows/README.md

@@ -1,147 +0,0 @@
-# Flows — `apps/api/src/routes/flows/`
-
-```
-GET  /v1/flows/:slug           — serve a validated flow config
-POST /v1/flows/:slug/steps     — submit one step's answers; persists
-                                  server-side on landing
-GET  /v1/flows/:slug/aggregate — anonymous per-question response counts
-                                  for the results reveal (#4771)
-POST /v1/flows/:slug/save      — the recommender's "email me this plan"
-                                  moment: FlowSession + Lead (+ T+0 grant)
-                                  for the permalink's answers (#4841)
-POST /v1/flows/:slug/checkout  — the purchase moment: the email moment,
-                                  the FlowCheckout buyer row at a
-                                  SERVER-recomputed price, then a Stripe
-                                  TEST-mode Checkout Session (#4841)
-```
-
-Every route is anonymous — no auth, no `siteId` on the wire (see the
-module docstring in `index.ts` for the single-site default). All sit
-behind the per-IP rate limiter (`middleware/rate-limit.ts`), registered
-once for the whole `flowsScope` in `server.ts`.
-
-## The email moment (`recommender.ts`, #4841)
-
-A recommending flow captures no PII until the visitor chooses save or
-checkout (PRD L108). Both routes take the permalink's answer map + an
-email; `checkout` additionally takes `offerKey` / `period` (+ `seats`,
-`creditStop`) and the two redirect URLs — and **no amount of any name**:
-the body schema is `.strict()`, and the server recomputes `price()` from
-the register it served (PRD L104). Checkout refuses a register with
-`stripeConfigRef: null` or no `rateTable.currency` (409), refuses any key
-outside the `sk_test_` allow-list before any side effect (500), and only
-opens the Stripe session AFTER the session, lead and buyer row exist — a
-Stripe outage returns 502 and the record survives. The Stripe session's
-`metadata` carries `flowCheckoutId`, `flowSlug`, `offerKey`, `sessionId`,
-`leadId` and the `permalink` (chunked `permalink_2…` past 500 chars) — the
-join the webhook (#4838) stamps on.
-
-## Checkout redirect origins (#4912)
-
-`successUrl` and `cancelUrl` must be on **this site's own origin**. The
-shared `flowRedirectUrlSchema` pins only "an `http(s)` URL with a host",
-so without this gate a caller posting straight at the API — bypassing the
-consumer's Server Action, which builds both URLs itself — could mint a
-real Checkout Session whose post-payment redirect lands on a host they
-control: an open redirect carrying the credibility of a completed
-payment, and `cancelUrl` is the same vector without the victim even
-paying.
-
-| Var            | Default                 | Meaning                                                                    |
-| -------------- | ----------------------- | -------------------------------------------------------------------------- |
-| `FRONTEND_URL` | `http://localhost:3000` | The site origin checkout redirects are locked to — the allow-list, of one. |
-
-**The allow-list source is `FRONTEND_URL`**, read per request. It is the
-same variable this API already uses as its CORS origin
-(`apps/api/src/server.ts`), for the origin check in
-`middleware/auth.ts`, and to compose the billing-portal return URL
-(`routes/billing/portal.ts`) — reused rather than inventing a second
-site-origin contract, exactly as the scaffolded commerce checkout route
-does (`packages/create-ailk/templates/.claude/skills/scaffold-commerce/
-templates/checkout-route.template.ts`). The default is byte-identical to
-the one `apps/api/src/config/index.ts` applies.
-
-The comparison is **exact origin equality** — scheme, host and port must
-all match. A prefix or suffix test would accept
-`https://<site-origin>.evil.example`. A relative path cannot arrive: the
-shared schema refuses it before this gate runs. A refused redirect is a
-`400 invalid_input` raised **before** the register read, so no session,
-no lead and no buyer row is written and Stripe is never called; the
-offending URL is never echoed back or logged.
-
-**Operator consequence.** In production, leave `FRONTEND_URL` unset and
-your own checkout redirects will 400 — the same fail-closed direction
-CORS already takes on this variable. Set it to the origin visitors reach
-the site on. A value that is set but not a parseable absolute URL is a
-`500 config-error`, never a silently widened allow-list.
-
-## Rate limit — env var and default
-
-| Var                                 | Default | Meaning                                                                                                                   |
-| ----------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
-| `AILK_RATE_LIMIT_PER_IP_PER_MINUTE` | `20`    | Requests one visitor IP may make against a rate-limited anonymous scope (flows/leads/aeo/schedule) in a 60-second window. |
-
-**Why 20.** The default is sized to a full flow — one visitor completing
-the longest shipped flow in one sitting should never trip the limit. The
-longest shipped flow, `ailk-founder-diagnostic`, is **13 steps + 1 GET**
-(the initial config fetch) = 14 requests. 20 leaves headroom for an
-invisible `aeo_score` step's own submission (fired alongside a visible
-step, #4663 D7) and one legitimate resubmit (e.g. a transient failure the
-visitor retries).
-
-If a customer fork ships a longer flow, raise this env var to
-`<step count> + 1 (GET) + 1 (aeo_score, if the flow has one) + a small
-margin` rather than lowering the floor for every other flow.
-
-## Visitor-IP forwarding (#4730)
-
-A consumer site's own Server Action (`apps/web/app/[locale]/flows/[slug]/
-flow.actions.ts`) calls these routes from ITS OWN server process — every
-visitor of that site shares one calling process. Without forwarding, the
-API would see that process's egress IP for every request, and every
-visitor would share ONE rate-limit bucket.
-
-The fix has two halves:
-
-1. `apps/api/src/server.ts` sets `trustProxy: true` on the Fastify
-   instance, so `req.ip` resolves the LEFTMOST address of a multi-hop
-   `X-Forwarded-For` chain (Fastify's built-in `@fastify/proxy-addr`
-   parsing) instead of a socket address that's meaningless once requests
-   are bridged through `.inject()` (the Vercel serverless handler,
-   `apps/api/api/index.ts`, never opens a real socket).
-2. The Server Action reads ITS OWN incoming request's `x-forwarded-for`
-   (falling back to `x-real-ip`) via Next's `headers()` and forwards it
-   as an explicit `x-forwarded-for` header on the outbound
-   `flows.submitStep` call. This APPENDS to, rather than replaces,
-   whatever hop this API's own edge subsequently adds — the leftmost
-   entry in the resulting chain is still the real visitor.
-
-**Trade-off, stated plainly.** A caller hitting these routes directly
-(bypassing a consumer's Server Action) can set `x-forwarded-for` to
-anything — there is no fixed, allowlistable upstream proxy to trust,
-because this API's actual "proxies" are arbitrary consumer web
-processes. Per-IP rate limiting on these anonymous surfaces is a
-best-effort abuse deterrent, not a hard security boundary; this fix
-trades a small amount of spoof-resistance for correctness on the
-overwhelmingly common path (Server-Action-forwarded traffic), which was
-previously broken for every visitor.
-
-## GET config fetch is NOT IP-forwarded (yet)
-
-`apps/web/app/[locale]/flows/[slug]/page.tsx` (a Server Component) calls
-`flows.get(slug)` directly — it does not forward a visitor IP header.
-That GET therefore still buckets on whatever `req.ip` resolves to for the
-calling process (not the visitor), separately from the POST-step bucket
-above. This is a known, narrower gap than the one #4730 fixes (a
-single-visitor lockout across 13+ POST steps); extending `flows.get` +
-`page.tsx` the same way is a natural follow-up if it proves to matter in
-practice.
-
-**What this means concretely, so the gap isn't understated:** a site
-receiving more than the default 20 flow-page loads per minute from one
-calling process would 429 its own config GET — and that failure would
-surface **nowhere in the UI**, because `flows.get` (unlike
-`flows.submitStep`) has no 429-to-`rate_limited` mapping at all; the page
-would simply fail to render the flow. This is not a regression (the
-pre-#4730 shared bucket was smaller, at 10), and no acceptance criterion
-covers it — named here so the follow-up starts from the right severity.