create-ailk 0.1.0 → 0.2.0

package/templates/apps/api/src/openapi/spec.ts

@@ -21,9 +21,10 @@ export function buildOpenApiSpec() {
       title: "AI Launch Kit — Public Content API",
       version: API_VERSION,
       description:
-        "Read-only HTTP API exposing AILK content as schema.org JSON-LD. " +
-        "Designed for agent consumption (AX) — every response carries " +
-        "`@context` and `@type` at the document root.",
+        "HTTP API exposing AILK content as schema.org JSON-LD, plus a small set " +
+        "of anonymous write routes (lead capture, checkout). Designed for agent " +
+        "consumption (AX) — every content response carries `@context` and " +
+        "`@type` at the document root.",
       license: { name: "MIT" },
     },
     servers: [
@@ -104,6 +105,175 @@ export function buildOpenApiSpec() {
           },
         },
       },
+      "/v1/leads/submit": {
+        post: {
+          operationId: "submitLead",
+          summary: "Capture a contact-form lead",
+          description:
+            "Stores a contact-form-style lead — an email plus an arbitrary payload of " +
+            "form fields — for the given siteId. `source` is a free-form tag the caller " +
+            "sets to identify the channel (for example `agent`); it is stored as-is and " +
+            "not checked against a fixed vocabulary. A 201 response means the lead " +
+            "landed, in the database or (if the database is unavailable) a file " +
+            "fallback; the response's `email` field reports, best-effort, whether the " +
+            "site operator was notified.",
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/LeadSubmitRequest" },
+              },
+            },
+          },
+          responses: {
+            "201": {
+              description: "Lead captured",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/LeadWriteResponse" },
+                },
+              },
+            },
+            "400": {
+              description: "Validation error — invalid request body",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/InvalidInputResponse" },
+                },
+              },
+            },
+            "503": {
+              description:
+                "Lead capture unavailable — persistence failed, or neither file " +
+                "capture nor a database is configured",
+              content: {
+                "application/json": {
+                  schema: {
+                    oneOf: [
+                      { $ref: "#/components/schemas/PersistFailedResponse" },
+                      {
+                        $ref: "#/components/schemas/LeadCaptureNotConfiguredResponse",
+                      },
+                    ],
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+      "/v1/leads/subscribe": {
+        post: {
+          operationId: "subscribeLead",
+          summary: "Add an email to the newsletter list",
+          description:
+            "Adds an email address to the given siteId's newsletter list. `source` is " +
+            "a free-form tag the caller sets to identify the signup channel (for " +
+            "example `agent`); it is stored as-is and not checked against a fixed " +
+            "vocabulary. A 201 response means the subscription landed — a duplicate " +
+            "email for the same site returns the existing subscriber's id rather than " +
+            "erroring.",
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/LeadSubscribeRequest" },
+              },
+            },
+          },
+          responses: {
+            "201": {
+              description: "Subscription captured",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/LeadWriteResponse" },
+                },
+              },
+            },
+            "400": {
+              description: "Validation error — invalid request body",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/InvalidInputResponse" },
+                },
+              },
+            },
+            "503": {
+              description:
+                "Lead capture unavailable — persistence failed, or neither file " +
+                "capture nor a database is configured",
+              content: {
+                "application/json": {
+                  schema: {
+                    oneOf: [
+                      { $ref: "#/components/schemas/PersistFailedResponse" },
+                      {
+                        $ref: "#/components/schemas/LeadCaptureNotConfiguredResponse",
+                      },
+                    ],
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+      "/v1/leads/callback": {
+        post: {
+          operationId: "requestCallback",
+          summary: "Request a callback",
+          description:
+            "Stores a name, phone number, optional preferred time, and an arbitrary " +
+            "payload for the given siteId so a site operator can call the lead back. " +
+            "Unlike submit/subscribe there is no `source` or `email` field. A 201 " +
+            "response means the request landed, in the database or (if the database " +
+            "is unavailable) a file fallback; the response's `email` field reports, " +
+            "best-effort, whether the site operator was notified.",
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/LeadCallbackRequest" },
+              },
+            },
+          },
+          responses: {
+            "201": {
+              description: "Callback request captured",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/LeadWriteResponse" },
+                },
+              },
+            },
+            "400": {
+              description: "Validation error — invalid request body",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/InvalidInputResponse" },
+                },
+              },
+            },
+            "503": {
+              description:
+                "Lead capture unavailable — persistence failed, or neither file " +
+                "capture nor a database is configured",
+              content: {
+                "application/json": {
+                  schema: {
+                    oneOf: [
+                      { $ref: "#/components/schemas/PersistFailedResponse" },
+                      {
+                        $ref: "#/components/schemas/LeadCaptureNotConfiguredResponse",
+                      },
+                    ],
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
       "/v1/content/types": {
         get: {
           operationId: "listContentTypes",
@@ -251,6 +421,11 @@ export function buildOpenApiSpec() {
               default: 1,
               description: "Line-item quantity; defaults to 1",
             },
+            allowPromotionCodes: {
+              type: "boolean",
+              description:
+                "Show the promotion-code field on the hosted Checkout page. Omit to leave it off",
+            },
           },
         },
         CheckoutSessionResponse: {
@@ -300,6 +475,140 @@ export function buildOpenApiSpec() {
             error: { type: "string", enum: ["checkout-unavailable"] },
           },
         },
+        LeadSubmitRequest: {
+          type: "object",
+          additionalProperties: false,
+          required: ["siteId", "source", "email", "payload"],
+          properties: {
+            siteId: {
+              type: "string",
+              pattern: "^[a-zA-Z0-9._-]{1,128}$",
+              description: "Site/tenant identifier",
+            },
+            source: {
+              type: "string",
+              pattern: "^[^\\r\\n]{1,64}$",
+              description:
+                "Free-form caller-set channel tag (e.g. `agent`); no CR/LF",
+            },
+            email: { type: "string", format: "email", maxLength: 254 },
+            payload: {
+              type: "object",
+              maxProperties: 64,
+              additionalProperties: true,
+              description: "Arbitrary form fields, up to 64 keys",
+            },
+          },
+        },
+        LeadSubscribeRequest: {
+          type: "object",
+          additionalProperties: false,
+          required: ["siteId", "email", "source"],
+          properties: {
+            siteId: {
+              type: "string",
+              pattern: "^[a-zA-Z0-9._-]{1,128}$",
+              description: "Site/tenant identifier",
+            },
+            email: { type: "string", format: "email", maxLength: 254 },
+            source: {
+              type: "string",
+              pattern: "^[^\\r\\n]{1,64}$",
+              description:
+                "Free-form caller-set channel tag (e.g. `agent`); no CR/LF",
+            },
+          },
+        },
+        LeadCallbackRequest: {
+          type: "object",
+          additionalProperties: false,
+          required: ["siteId", "name", "phone", "payload"],
+          properties: {
+            siteId: {
+              type: "string",
+              pattern: "^[a-zA-Z0-9._-]{1,128}$",
+              description: "Site/tenant identifier",
+            },
+            name: { type: "string", minLength: 1, maxLength: 128 },
+            phone: { type: "string", minLength: 3, maxLength: 32 },
+            preferredTime: { type: "string", maxLength: 64 },
+            payload: {
+              type: "object",
+              maxProperties: 64,
+              additionalProperties: true,
+              description: "Arbitrary form fields, up to 64 keys",
+            },
+          },
+        },
+        LeadEmailResult: {
+          description:
+            "Best-effort operator-notification outcome. `skipped` means email " +
+            "notification isn't configured; persistence already succeeded either way.",
+          oneOf: [
+            {
+              type: "object",
+              required: ["ok", "messageId"],
+              properties: {
+                ok: { type: "boolean", enum: [true] },
+                messageId: { type: "string" },
+              },
+            },
+            {
+              type: "object",
+              required: ["ok", "error"],
+              properties: {
+                ok: { type: "boolean", enum: [false] },
+                error: { type: "string" },
+              },
+            },
+            {
+              type: "object",
+              required: ["skipped", "reason"],
+              properties: {
+                skipped: { type: "boolean", enum: [true] },
+                reason: { type: "string" },
+              },
+            },
+          ],
+        },
+        LeadWriteResponse: {
+          type: "object",
+          required: ["id", "persisted", "email"],
+          properties: {
+            id: {
+              type: "string",
+              description:
+                "Server-assigned record id — a DB-prefixed entity id when " +
+                'persisted is "db", or a `fallback-<ts>-<rand>` file id when ' +
+                'persisted is "file"',
+            },
+            persisted: { type: "string", enum: ["db", "file"] },
+            email: { $ref: "#/components/schemas/LeadEmailResult" },
+          },
+        },
+        InvalidInputResponse: {
+          type: "object",
+          required: ["error", "message"],
+          properties: {
+            error: { type: "string", enum: ["invalid_input"] },
+            message: { type: "string" },
+          },
+        },
+        PersistFailedResponse: {
+          type: "object",
+          required: ["error"],
+          properties: {
+            error: { type: "string", enum: ["persist_failed"] },
+          },
+        },
+        LeadCaptureNotConfiguredResponse: {
+          type: "object",
+          required: ["error", "message"],
+          properties: {
+            error: { type: "string", enum: ["lead_capture_not_configured"] },
+            message: { type: "string" },
+          },
+        },
         ContentPage: {
           type: "object",
           required: ["type", "slug", "title", "description"],

package/templates/apps/api/src/routes/aeo/__tests__/index.test.ts

@@ -0,0 +1,175 @@
+/**
+ * @file index.test.ts
+ * Route-level inject tests for POST /v1/aeo/score and GET /v1/aeo/score/example
+ * (#4666 D5).
+ *
+ * Mirrors apps/api/src/routes/schedule/__tests__/index.test.ts's shape: a bare
+ * Fastify instance with only the routes under test registered; the fetch
+ * boundary is stubbed rather than the service, so these tests cover the real
+ * crawler + scorer alongside the route's envelope and status mapping. Test
+ * URLs use literal public/blocked IP addresses so the SSRF gate's DNS step is
+ * never exercised (no real network egress needed).
+ */
+import type { FastifyInstance } from "fastify";
+
+import { scoreAeoRoute, exampleAeoRoute } from "../index";
+
+const HOME_HTML =
+  '<html><script type="application/ld+json">{"@type":"HomePage","name":"Home"}</script></html>';
+
+/** Typed as the platform signature so it assigns to `globalThis.fetch` with no cast. */
+type FetchStub = jest.Mock<Promise<Response>, [RequestInfo | URL, RequestInit?]>;
+
+function buildApp(): FastifyInstance {
+  const fastify = require("fastify")();
+  fastify.register(scoreAeoRoute);
+  fastify.register(exampleAeoRoute);
+  return fastify as FastifyInstance;
+}
+
+describe("POST /v1/aeo/score", () => {
+  let app: FastifyInstance;
+  const realFetch = globalThis.fetch;
+
+  beforeEach(() => {
+    app = buildApp();
+  });
+
+  afterEach(async () => {
+    await app.close();
+    globalThis.fetch = realFetch;
+    delete process.env["AEO_SCORE_BUDGET_MS"];
+  });
+
+  it("400s on a malformed body", async () => {
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/aeo/score",
+      payload: { url: "not-a-url" },
+    });
+    expect(res.statusCode).toBe(400);
+    const body = JSON.parse(res.body) as { ok: boolean; error: { code: string } };
+    expect(body.ok).toBe(false);
+    expect(body.error.code).toBe("invalid_input");
+  });
+
+  it("200s with data.status ready for a reachable public-IP host", async () => {
+    const stub: FetchStub = jest.fn(async () => new Response(HOME_HTML));
+    globalThis.fetch = stub;
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/aeo/score",
+      payload: { url: "http://93.184.216.34/" },
+    });
+
+    expect(res.statusCode).toBe(200);
+    const body = JSON.parse(res.body) as { ok: boolean; data: { status: string; score: number } };
+    expect(body.ok).toBe(true);
+    expect(body.data.status).toBe("ready");
+    expect(typeof body.data.score).toBe("number");
+  });
+
+  it("200s with data.status unavailable/ssrf_blocked for a loopback URL (never 4xx/5xx)", async () => {
+    const stub: FetchStub = jest.fn();
+    globalThis.fetch = stub;
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/aeo/score",
+      payload: { url: "http://127.0.0.1/admin" },
+    });
+
+    expect(res.statusCode).toBe(200);
+    const body = JSON.parse(res.body) as { ok: boolean; data: { status: string; reason: string } };
+    expect(body.ok).toBe(true);
+    expect(body.data.status).toBe("unavailable");
+    expect(body.data.reason).toBe("ssrf_blocked");
+    expect(stub).not.toHaveBeenCalled();
+  });
+
+  // AILK #4707 — the specific SSRF rejection detail (which internal
+  // hostname/IP triggered the block, or that DNS resolved to one) is an
+  // anonymous-endpoint recon primitive and must never reach the caller; the
+  // response carries only the generic reason enum + a fixed message, with
+  // the specific detail logged server-side only.
+  it("returns a generic message for an SSRF-rejected URL — the specific rejection reason never reaches the response body", async () => {
+    const stub: FetchStub = jest.fn();
+    globalThis.fetch = stub;
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/aeo/score",
+      payload: { url: "http://127.0.0.1/admin" },
+    });
+
+    const body = JSON.parse(res.body) as {
+      ok: boolean;
+      data: { status: string; reason: string; message: string };
+    };
+    expect(body.data.reason).toBe("ssrf_blocked");
+    // Same fixed text flow-engine.ts's aeo_score step already scrubs its
+    // own SSRF-blocked result to (#4663 M1) — one client-facing message
+    // across both aeo_score entry points.
+    expect(body.data.message).toBe("This URL cannot be scored.");
+    expect(body.data.message).not.toMatch(/127\.0\.0\.1/);
+    expect(body.data.message).not.toMatch(/blocked|internal|loopback|metadata/i);
+  });
+
+  it("logs the specific SSRF rejection reason server-side (never returned to the caller)", async () => {
+    const logLines: string[] = [];
+    const logCapture = require("fastify")({
+      logger: {
+        level: "info",
+        stream: { write: (msg: string) => logLines.push(msg) },
+      },
+    }) as FastifyInstance;
+    await logCapture.register(scoreAeoRoute);
+    await logCapture.ready();
+
+    const stub: FetchStub = jest.fn();
+    globalThis.fetch = stub;
+
+    try {
+      await logCapture.inject({
+        method: "POST",
+        url: "/v1/aeo/score",
+        payload: { url: "http://127.0.0.1/admin" },
+      });
+
+      const logText = logLines.join("\n");
+      expect(logText).toMatch(/127\.0\.0\.1/);
+      expect(logText).toMatch(/blocked host/i);
+    } finally {
+      await logCapture.close();
+    }
+  });
+});
+
+describe("GET /v1/aeo/score/example", () => {
+  let app: FastifyInstance;
+
+  beforeEach(() => {
+    app = buildApp();
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+
+  it("200s with the bundled example, meta.example true, and the illustrative disclosure wire-visible (acceptance-review finding)", async () => {
+    const res = await app.inject({ method: "GET", url: "/v1/aeo/score/example" });
+    expect(res.statusCode).toBe(200);
+    const body = JSON.parse(res.body) as {
+      ok: boolean;
+      data: { status: string; meta: { example: boolean; sourceUrl: string; illustrative: boolean } };
+    };
+    expect(body.ok).toBe(true);
+    expect(body.data.status).toBe("ready");
+    expect(body.data.meta.example).toBe(true);
+    expect(body.data.meta.sourceUrl).toBe("https://ailaunchkit.ai");
+    // Today's fixture is hand-authored, not a genuine crawl — the caller
+    // must not be told this is a live measurement without qualification.
+    expect(body.data.meta.illustrative).toBe(true);
+  });
+});

package/templates/apps/api/src/routes/aeo/index.ts

@@ -0,0 +1,107 @@
+/**
+ * AEO score route group (#4666 D5).
+ *
+ * Routes:
+ *   POST /v1/aeo/score          — score a URL against the four content rules
+ *   GET  /v1/aeo/score/example  — the bundled pre-launch annotated example
+ *
+ * Anonymous, like the sibling `/v1/flows/*` and `/v1/schedule/*` routes — a
+ * waitlist respondent has no account. Both routes return `200 { ok: true,
+ * data }` for BOTH `ready` and `unavailable` results — an `unavailable`
+ * result is a successful call reporting a degraded outcome, not an HTTP
+ * error; the caller branches on `data.status`, mirroring how the browser
+ * will handle the `computing` state this route never itself emits. Only a
+ * malformed request body is a `400 invalid_input`.
+ *
+ * No MCP twin (a recorded, deliberate exception — brief D7 / apps/api/CLAUDE.md):
+ * exposing an arbitrary-URL crawler to anonymous agents is a security-posture
+ * decision the AEO Layer 1 MCP tool (`apps/mcp/src/tools/audit.ts`) already
+ * declines by staying same-origin-locked.
+ *
+ * Envelope per apps/api/CLAUDE.md: `{ ok: true, data }` /
+ * `{ ok: false, error: { code, message } }`, never 200-with-ok:false.
+ *
+ * SSRF-reason leak (security review, AILK #4707): `assertUrlSafe`'s reject
+ * `reason` text (e.g. "Host x resolves to a blocked address: 10.1.2.3")
+ * is a recon primitive for an anonymous caller mapping internal
+ * infrastructure via DNS-rebinding probes. It is logged server-side only
+ * (`request.log.info`); the response's `data.message` is replaced with the
+ * fixed `SSRF_BLOCKED_CLIENT_MESSAGE` for `reason: "ssrf_blocked"`. The
+ * `reason` enum itself is unchanged — it is already generic, and is the
+ * discriminant the api-client contract keys on. `flow-engine.ts`'s
+ * `aeo_score` step landed the identical scrub for its own caller in #4663
+ * (M1) and named this route's gap explicitly as out of that fix's scope —
+ * this closes it, reusing that fix's exact client-facing message text for
+ * consistency across both `aeo_score` entry points.
+ */
+import { aeoScoreInputSchema } from "@working-theory/validation";
+import type { FastifyPluginAsync } from "fastify";
+
+import {
+  resolveScoreBudgetMs,
+  loadExampleScore,
+  scoreUrl,
+} from "../../services/aeo-score.js";
+
+const SSRF_BLOCKED_CLIENT_MESSAGE = "This URL cannot be scored.";
+
+export const scoreAeoRoute: FastifyPluginAsync = async (fastify) => {
+  fastify.post("/v1/aeo/score", async (request, reply) => {
+    const parsedBody = aeoScoreInputSchema.safeParse(request.body);
+    if (!parsedBody.success) {
+      return reply.status(400).send({
+        ok: false,
+        error: {
+          code: "invalid_input",
+          message: parsedBody.error.issues[0]?.message ?? "Invalid request body.",
+        },
+      });
+    }
+
+    const budgetMs = resolveScoreBudgetMs(process.env["AEO_SCORE_BUDGET_MS"], {
+      warn: (msg) => request.log.warn(msg),
+    });
+    const data = await scoreUrl(parsedBody.data.url, { budgetMs });
+
+    const host = safeHost(parsedBody.data.url);
+    if (data.status === "ready") {
+      request.log.info(
+        { host, pagesAudited: data.meta.pagesAudited, skipped: data.meta.skipped.length, status: data.status },
+        "aeo score computed",
+      );
+      return reply.send({ ok: true, data });
+    }
+
+    if (data.status === "unavailable") {
+      // The specific rejection detail (e.g. which internal hostname/IP an
+      // SSRF probe resolved to) is logged here, server-side only — never
+      // sent to the caller.
+      request.log.info(
+        { host, status: data.status, reason: data.reason, message: data.message },
+        "aeo score unavailable",
+      );
+      const clientData: typeof data =
+        data.reason === "ssrf_blocked"
+          ? { ...data, message: SSRF_BLOCKED_CLIENT_MESSAGE }
+          : data;
+      return reply.send({ ok: true, data: clientData });
+    }
+
+    return reply.send({ ok: true, data });
+  });
+};
+
+export const exampleAeoRoute: FastifyPluginAsync = async (fastify) => {
+  fastify.get("/v1/aeo/score/example", async (_request, reply) => {
+    return reply.send({ ok: true, data: loadExampleScore() });
+  });
+};
+
+/** Never log the full URL — host only (§ 5.2 Logging: no PII, no query strings). */
+function safeHost(rawUrl: string): string {
+  try {
+    return new URL(rawUrl).host;
+  } catch {
+    return "invalid";
+  }
+}

package/templates/apps/api/src/routes/auth/__tests__/auth-tokens.functional.test.ts

@@ -149,6 +149,9 @@ describe("tokens routes — functional via dual-mode preHandler", () => {
 
     it("DELETE /api/auth/tokens/:id succeeds via bearer; revokes the row", async () => {
       const bearer = "tok_live_zzz";
+      // Well-formed apitok_ id (ADR-0031): the :id param is validated with
+      // zApiTokenId before any query runs.
+      const targetId = "apitok_00000000-0000-7000-8000-000000000009";
       (prisma.apiToken.findUnique as jest.Mock).mockResolvedValue({
         id: "tok_id",
         userId: "user_bear",
@@ -160,13 +163,13 @@ describe("tokens routes — functional via dual-mode preHandler", () => {
       app = await buildApp();
       const res = await app.inject({
         method: "DELETE",
-        url: "/v1/auth/tokens/tok_other",
+        url: `/v1/auth/tokens/${targetId}`,
         headers: { authorization: `Bearer ${bearer}` },
       });
 
       expect(res.statusCode).toBe(200);
       expect(prisma.apiToken.updateMany).toHaveBeenCalledWith({
-        where: { id: "tok_other", userId: "user_bear", revokedAt: null },
+        where: { id: targetId, userId: "user_bear", revokedAt: null },
         data: { revokedAt: expect.any(Date) },
       });
     });