create-ailk 0.1.1 → 0.3.0

package/templates/apps/api/src/routes/project-listings/me.ts

@@ -0,0 +1,86 @@
+/**
+ * NOT marked `oss: false` (D-48/#5366 escalation, mirrors the original
+ * multi-tenant/#5088 card's own conclusion about this exact file, lines
+ * 556-571 of module-architecture.ts): `./index.ts` in this directory is a
+ * MIXED barrel that statically imports this file, and `server.ts` reaches
+ * `./index.ts` via a plain (non-slice) literal `import()` for multi-tenant's
+ * tenant-scoped routes — a specifier `tsc` always resolves, module selection
+ * or not. Stripping this file leaves that barrel with a dangling import on
+ * every tree. Registration stays gated (`isModuleEnabled("signal-collectors")`
+ * in server.ts); only the source file itself must ship unconditionally.
+ *
+ * GET /v1/project-listings/me
+ *
+ * The FOUNDER'S OWN listings read (#5295) — the `/v1/flow-checkouts/me` and
+ * `/v1/waitlist-signups/me` posture, for `ProjectListing`.
+ *
+ * Registered INSIDE `server.ts`'s `authScope` (auth only — NOT the inner
+ * `tenantScope`): a founder is not a workspace member, and the tenant guard is
+ * default-deny, so a founder reaching the tenant-scoped list route gets a 403
+ * for their own submission. That is the problem this route exists to solve, and
+ * it is solved by ADDING this route rather than by relaxing
+ * `PROJECT_LISTING_ROLES` — the operator floor on
+ * `GET|PATCH /v1/project-listings[/:id]` is unchanged and still `owner|admin`.
+ *
+ * Identity is `request.userId` ONLY. The route declares no query schema and
+ * reads no query or body key — an `email` parameter is never parsed and never
+ * read — and the service joins on the owner link and nothing else
+ * (`services/project-listings.ts`'s `listMyProjectListings`: `ownerUserId ===
+ * userId`, never a `founderEmail` comparison at read time).
+ *
+ * Route precedence: this static path is registered alongside the parametric
+ * `/v1/project-listings/:id` in the tenant scope. Fastify's router prefers a
+ * static segment over a parametric one, so `/me` reaches this handler, exactly
+ * as the already-shipped static `/v1/project-listings/public` coexists with the
+ * same parametric route.
+ *
+ * Envelope per apps/api/CLAUDE.md: `{ ok: true, data }` /
+ * `{ ok: false, error: { code, message } }`, real HTTP status codes:
+ *   401 unauthorized · 500 internal_error (the 200 body failed its own
+ *   contract schema — a drift is never a leak). A signed-in caller who owns
+ *   NOTHING is a 200 with an empty list, never a 403: they are legitimately
+ *   signed in and simply own no listing yet.
+ *
+ * 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/flow-checkouts/me` and `/v1/waitlist-signups/me`).
+ */
+import { projectListingMeResponseSchema } from "@working-theory/validation";
+import type { FastifyPluginAsync, FastifyReply } from "fastify";
+
+import { listMyProjectListings } from "../../services/project-listings.js";
+
+import { sendValidated } from "./respond.js";
+
+function unauthorized(reply: FastifyReply) {
+  return reply.status(401).send({
+    ok: false,
+    error: { code: "unauthorized", message: "Authentication required" },
+  });
+}
+
+export const projectListingMeRoute: FastifyPluginAsync = async (fastify) => {
+  fastify.get("/v1/project-listings/me", async (request, reply) => {
+    const userId = request.userId;
+    if (!userId) return unauthorized(reply);
+
+    const listings = await listMyProjectListings(userId);
+
+    // The omission is explicit at the send site rather than hidden in a schema
+    // strip, the idiom `patch-draft.ts` uses: `projectListingDraftSchema` is
+    // `.strict()`, so a key that stops being dropped here becomes a 500 instead
+    // of quietly shipping an internal reference to the founder.
+    const data = listings.map(
+      ({
+        siteId: _siteId,
+        leadId: _leadId,
+        decidedBy: _decidedBy,
+        issueUrl: _issueUrl,
+        experimentKey: _experimentKey,
+        ...mine
+      }) => mine,
+    );
+
+    return sendValidated(reply, projectListingMeResponseSchema, data, "me");
+  });
+};

package/templates/apps/api/src/routes/project-listings/patch-draft.ts

@@ -1,4 +1,9 @@
 /**
+ * NOT marked `oss: false` — see `./me.ts`'s header comment (D-48/#5366
+ * escalation: `./index.ts` is a mixed barrel multi-tenant's `server.ts`
+ * reaches by a literal, always-resolved `import()`; this file ships
+ * unconditionally, registration stays gated).
+ *
  * PATCH /v1/project-listings/drafts/:id
  *
  * `patch` — the save-as-you-go write (#5036 D1). Anonymous, token-gated,

package/templates/apps/api/src/routes/project-listings/public.ts

@@ -1,4 +1,9 @@
 /**
+ * NOT marked `oss: false` — see `./me.ts`'s header comment (D-48/#5366
+ * escalation: `./index.ts` is a mixed barrel multi-tenant's `server.ts`
+ * reaches by a literal, always-resolved `import()`; this file ships
+ * unconditionally, registration stays gated).
+ *
  * GET /v1/project-listings/public?siteKey=
  *
  * The anonymous page-render read (#4998 AC4, reshaped by #5033). Every

package/templates/apps/api/src/routes/project-listings/respond.ts

@@ -1,4 +1,15 @@
 /**
+ * NOT marked `oss: false` (D-48/#5366 escalation, reversing this pass's
+ * own D6 read — see `./me.ts`'s header comment): `sendValidated` is imported
+ * by `./me.ts`, `./patch-draft.ts` and `./public.ts`, each of which must ship
+ * unconditionally because `./index.ts`'s multi-tenant literal `import()`
+ * forces it. A file imported by an always-shipping file cannot itself be
+ * excluded — this is the ORIGINAL multi-tenant/#5088 card's own conclusion
+ * about this exact file (module-architecture.ts lines 569-571), which D6's
+ * "every other consumer is Pro Plus" premise doesn't override: two of its
+ * three non-tenant consumers are these three always-shipping files, not a
+ * gated one.
+ *
  * Response-schema validation for the project-listings routes (#4998),
  * mirroring `waitlist-experiments/respond.ts`'s discipline: response schemas
  * are contract-only unless re-parsed against their own `.strict()` schema

package/templates/apps/api/src/routes/project-listings/resume-token.ts

@@ -1,4 +1,9 @@
 /**
+ * NOT marked `oss: false` — see `./me.ts`'s header comment (D-48/#5366
+ * escalation): imported only by `./patch-draft.ts` and `./submit.ts`, both
+ * of which ship unconditionally (`./index.ts`'s multi-tenant literal
+ * `import()`), so this file cannot be excluded either.
+ *
  * The resume token's transport (#5036 D1).
  *
  * `start` hands the client an opaque token; `patch` and `submit` present it

package/templates/apps/api/src/routes/project-listings/start.ts

@@ -1,4 +1,9 @@
 /**
+ * NOT marked `oss: false` — see `./me.ts`'s header comment (D-48/#5366
+ * escalation: `./index.ts` is a mixed barrel multi-tenant's `server.ts`
+ * reaches by a literal, always-resolved `import()`; this file ships
+ * unconditionally, registration stays gated).
+ *
  * POST /v1/project-listings
  *
  * `start` — step one of the application (#5036 D1). Anonymous, registered in
@@ -37,6 +42,24 @@
  * PII-safe logging (mirrors `routes/leads/index.ts`): routing metadata only —
  * never founderEmail, founderName, or the resume token.
  *
+ * SENDS THE RESUME EMAIL (#5406), fire-and-forget, after the row exists. The
+ * 201 below is never delayed or failed by it: `sendListingResumeLink` returns
+ * `void` and swallows everything, exactly as `sendListingDecisionEmail`'s
+ * `fileIssueOnApprove` does on the approve path. The email is OPT-IN — a site
+ * whose `SiteListingConfig` carries no `resumeEmail.fromAddress` gets none, so
+ * a site sending its own today does not start sending two — and the request
+ * and response shapes of this hard-floor route are unchanged.
+ *
+ * THE EMAIL IS ALSO THE ONLY CARRIER OF THE VERIFICATION NONCE (#5407).
+ * `startProjectListingDraft` mints it, stores only its digest, and returns it
+ * as a SIBLING of the result — never inside the value parsed below, because
+ * `projectListingStartResponseSchema` is this route's hard-floor contract and
+ * carries `id` and `resumeToken` and nothing else. The nonce reaches
+ * `sendListingResumeLink` from a local variable and goes nowhere else: not
+ * into the response, not into the log line above it. That is precisely what
+ * makes `email_verified_at` mean something the resume token alone could not
+ * prove — see `verifyProjectListingDraftEmail`.
+ *
  * The response uses the API's own `{ ok, data }` / `{ ok, error }` envelope
  * (`apps/api/CLAUDE.md`) on BOTH the success and the failure path — the
  * anonymous create it replaces answered bare on success and enveloped on
@@ -49,6 +72,7 @@ import {
 import type { FastifyPluginAsync } from "fastify";
 
 import { siteIdForPublicKey } from "../../services/listing-config.js";
+import { sendListingResumeLink } from "../../services/project-listing-resume-email.js";
 import { startProjectListingDraft } from "../../services/project-listings.js";
 
 export const startProjectListingRoute: FastifyPluginAsync = async (fastify) => {
@@ -83,12 +107,26 @@ export const startProjectListingRoute: FastifyPluginAsync = async (fastify) => {
     }
 
     const result = await startProjectListingDraft(siteId, parsed.data);
+    // #5275 — a `consents` map declining a REQUIRED purpose contradicts the
+    // body's own `consent: true`; no row was created.
+    if (!result.ok) {
+      return reply.status(400).send({
+        ok: false,
+        error: { code: result.error.kind, message: result.error.message },
+      });
+    }
 
     request.log.info(
       { siteId, listingId: result.id, ip: request.ip },
       "project listing draft started",
     );
 
+    // #5406 — the founder's way back to this draft. NOT awaited: the 201 must
+    // not wait on Resend, and must not fail if Resend does. Both credentials
+    // are handed over here and neither is ever logged — they ride the link
+    // inside the email, and the #5407 nonce rides NOTHING ELSE anywhere.
+    sendListingResumeLink(result.id, result.resumeToken, result.verifyNonce);
+
     const body = projectListingStartResponseSchema.parse({
       id: result.id,
       resumeToken: result.resumeToken,

package/templates/apps/api/src/routes/project-listings/submit.ts

@@ -1,4 +1,9 @@
 /**
+ * NOT marked `oss: false` — see `./me.ts`'s header comment (D-48/#5366
+ * escalation: `./index.ts` is a mixed barrel multi-tenant's `server.ts`
+ * reaches by a literal, always-resolved `import()`; this file ships
+ * unconditionally, registration stays gated).
+ *
  * POST /v1/project-listings/drafts/:id/submit
  *
  * `submit` — the moment an application stops being a draft (#5036 D1).

package/templates/apps/api/src/routes/project-listings/verify-email.ts

@@ -0,0 +1,150 @@
+/**
+ * POST /v1/project-listings/drafts/:id/verify-email
+ *
+ * Records that the founder proved control of `founderEmail`, by opening the
+ * resume link emailed at step one (#5407). Anonymous, credential-gated,
+ * registered in the same rate-limited `leadsScope` as the other three
+ * anonymous listing routes.
+ *
+ * WHY THE ROUTE EXISTS. The resume email (#5406) tells the founder to "verify
+ * your email and continue", and until this route nothing made that sentence
+ * true: `ListingApplicationFlow` rehydrated from `?draft=&token=` entirely in
+ * the browser and touched the server only on the NEXT advance — so a founder
+ * who opened the link and closed the tab left no record, and the operator had
+ * no way to tell a proved address from a typed one at review (samhenry spec
+ * 316 D6b).
+ *
+ * WHAT IT PROVES. That somebody who can read mail at `founderEmail` opened
+ * this link — evidence about the ADDRESS, not about who is driving the draft
+ * (`verifyProjectListingDraftEmail` carries the full note). It takes
+ * TWO credentials and only the second carries that: the `Authorization:
+ * Bearer` resume token says "you opened this draft" (it is in `start`'s own
+ * 201 body, so anyone who posted the form has it), and the `verifyNonce` in
+ * the body says "you read the email" — it is minted at `start`, digested onto
+ * the row, and handed to nothing but the resume-email builder, reaching the
+ * outside world only as the `?verify=` parameter inside the message. Keying
+ * this route on the resume token ALONE was the first design and was
+ * forgeable in two HTTP calls; `verifyProjectListingDraftEmail` carries the
+ * full note.
+ *
+ * It still says nothing about WHO the founder is. `ownerUserId` (#5295) is
+ * the column that carries an identity claim.
+ *
+ * A SITE THAT SENDS NO RESUME EMAIL CAN NEVER VERIFY, and that is correct:
+ * the nonce is minted on every draft but delivered only by the email, so
+ * where `SiteListingConfig` carries no `resumeEmail` the column stays null
+ * forever — nobody has read anything at that address.
+ *
+ * IDEMPOTENT, AND WRITE-ONCE. The service stamps by compare-and-swap on
+ * `emailVerifiedAt: null`, so a founder who opens the link five times is
+ * stamped once and every call answers with that FIRST stamp.
+ *
+ * THE ERROR SURFACE IS `patch`'s AND `submit`'s, deliberately unchanged: a
+ * malformed id or a body that is not `{ verifyNonce }` is `400
+ * validation_failed`, a missing or malformed `Authorization: Bearer` is `401
+ * unauthorized`, and a WRONG token, a WRONG nonce, a credential bound to
+ * another listing, an unknown id and an already-submitted row are all one
+ * `404 not_found`. The 400s describe the REQUEST's shape and reveal nothing
+ * about any row; everything that depends on a row is the single 404. An
+ * anonymous surface must not distinguish "exists but not yours" from "does
+ * not exist", and this route least of all — a distinguishable answer would
+ * make it both an oracle for which drafts exist and a guessing channel for
+ * the nonce.
+ *
+ * THE NONCE TRAVELS IN THE BODY, not the query string, for the reason
+ * `resume-token.ts` gives about the resume token: a query parameter lands in
+ * access logs, proxy logs and `Referer` headers. The claim is about THIS hop
+ * only, and it is worth being exact about that — the nonce's DELIVERY hop is
+ * itself a query parameter on the consuming site's URL, so it lands in that
+ * site's own access logs exactly as the resume token does. What the body
+ * placement buys is that the API's logs and any proxy between the browser and
+ * this server never see it. The resume token keeps its `Authorization:
+ * Bearer` header. Neither credential is ever logged and neither is ever
+ * returned.
+ */
+import { zProjectListingId } from "@working-theory/ids";
+import { projectListingVerifyEmailResponseSchema } from "@working-theory/validation";
+import type { FastifyPluginAsync } from "fastify";
+import { z } from "zod";
+
+import { verifyProjectListingDraftEmail } from "../../services/project-listings.js";
+
+import { sendValidated } from "./respond.js";
+import { resumeTokenFrom } from "./resume-token.js";
+
+const paramsSchema = z.object({ id: zProjectListingId });
+
+/**
+ * The nonce, as the emailed link carried it. Bounded so an oversized body is
+ * refused before any digest is computed; the value is 256 bits of CSPRNG
+ * output in base64url, which is 43 characters.
+ */
+const bodySchema = z.object({ verifyNonce: z.string().min(1).max(256) }).strict();
+
+export const verifyProjectListingDraftEmailRoute: FastifyPluginAsync = async (
+  fastify,
+) => {
+  fastify.post(
+    "/v1/project-listings/drafts/:id/verify-email",
+    async (request, reply) => {
+      const parsedParams = paramsSchema.safeParse(request.params);
+      if (!parsedParams.success) {
+        return reply.status(400).send({
+          ok: false,
+          error: { code: "validation_failed", message: "Invalid project listing id" },
+        });
+      }
+
+      const resumeToken = resumeTokenFrom(request);
+      if (resumeToken === null) {
+        return reply.status(401).send({
+          ok: false,
+          error: { code: "unauthorized", message: "A resume token is required" },
+        });
+      }
+
+      // The message names the FIELD, never whether the value would have
+      // matched — that distinction is the 404's, below.
+      const parsedBody = bodySchema.safeParse(request.body);
+      if (!parsedBody.success) {
+        return reply.status(400).send({
+          ok: false,
+          error: {
+            code: "validation_failed",
+            message: "A verification nonce is required",
+          },
+        });
+      }
+
+      const result = await verifyProjectListingDraftEmail(
+        parsedParams.data.id,
+        resumeToken,
+        parsedBody.data.verifyNonce,
+      );
+      if (!result.ok) {
+        return reply.status(404).send({
+          ok: false,
+          error: { code: "not_found", message: "Draft not found" },
+        });
+      }
+
+      // Routing metadata only, the same PII boundary `start` documents: the
+      // listing id and the caller's ip, never the founder's email and never
+      // the token.
+      request.log.info(
+        { listingId: result.value.id, ip: request.ip },
+        "project listing draft email verified",
+      );
+
+      return sendValidated(
+        reply,
+        projectListingVerifyEmailResponseSchema,
+        {
+          id: result.value.id,
+          emailVerifiedAt: result.value.emailVerifiedAt.toISOString(),
+        },
+        "verify-email",
+      );
+    },
+  );
+};