create-ailk 0.4.0 → 0.6.0

package/templates/apps/api/src/services/__tests__/revalidation.test.ts

@@ -0,0 +1,238 @@
+/**
+ * @file revalidation.test.ts
+ * @description Proves the publish-revalidation webhook (#5851) against a REAL
+ * loopback HTTP server (spec D11), not a `global.fetch` double: the contract
+ * under test is the wire format, and only a real server proves that the bytes
+ * on the wire are the bytes the signature covers. The server recomputes the
+ * HMAC inside its own handler — the receiver's verification, performed for
+ * real — and compares with `timingSafeEqual`, exactly as a Phase-3 receiver
+ * will (spec FR7).
+ *
+ * The server binds 127.0.0.1, which `ssrfBlocked` rejects; D7's
+ * `allowPrivate: true` is what makes this substrate runnable at all.
+ *
+ * `CONTENT_REVALIDATE_*` are read through `config`, which snapshots
+ * `process.env` at import time — so every case sets env first and then
+ * `require`s the service through `jest.resetModules()`.
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { createServer, type Server } from "node:http";
+import type { AddressInfo } from "node:net";
+
+// Obviously-fake signing key — never a real secret (repo rule).
+const TEST_SECRET = "not-a-real-secret-fixture-value";
+const SIGNATURE_HEADER = "x-ailk-revalidate-signature";
+const EVENT_HEADER = "x-ailk-revalidate-event";
+
+const TARGET = {
+  workspaceId: "ws_test_0001",
+  type: "page",
+  slug: "pricing",
+  locale: "en",
+};
+
+interface LogLine {
+  level: "info" | "warn" | "error";
+  obj: Record<string, unknown>;
+  msg: string;
+}
+
+// Captured through the observability boundary so assertions don't depend on
+// pino's stdout serialization — the idiom of config/__tests__/index.test.ts.
+const mockLogLines: LogLine[] = [];
+const mockRecord =
+  (level: LogLine["level"]) => (obj: Record<string, unknown>, msg: string) =>
+    void mockLogLines.push({ level, obj, msg });
+
+jest.mock("dotenv", () => ({ config: jest.fn() }));
+jest.mock("@working-theory/observability", () => ({
+  createLogger: jest.fn(() => ({
+    info: mockRecord("info"),
+    warn: mockRecord("warn"),
+    error: mockRecord("error"),
+    debug: jest.fn(),
+  })),
+  logger: {
+    error: jest.fn(),
+    warn: jest.fn(),
+    info: jest.fn(),
+    debug: jest.fn(),
+  },
+}));
+
+interface Recorded {
+  rawBody: string;
+  signatureValid: boolean;
+  signatureHeader: string;
+  eventHeader: string;
+  contentType: string;
+  receivedAt: number;
+}
+
+let server: Server;
+let serverUrl: string;
+let recorded: Recorded[] = [];
+/** Status codes the server replies with, one per request, in order. */
+let responseStatuses: number[] = [];
+
+beforeAll(async () => {
+  server = createServer((req, res) => {
+    const chunks: Buffer[] = [];
+    req.on("data", (c: Buffer) => void chunks.push(c));
+    req.on("end", () => {
+      const raw = Buffer.concat(chunks);
+
+      // The receiver's own verification (FR7): recompute HMAC-SHA256 over the
+      // RAW request body bytes and compare in constant time.
+      const expected = Buffer.from(
+        createHmac("sha256", TEST_SECRET).update(raw).digest("hex"),
+        "utf8",
+      );
+      const received = Buffer.from(
+        String(req.headers[SIGNATURE_HEADER] ?? "").replace(/^sha256=/, ""),
+        "utf8",
+      );
+      const signatureValid =
+        expected.length === received.length &&
+        timingSafeEqual(expected, received);
+
+      recorded.push({
+        rawBody: raw.toString("utf8"),
+        signatureValid,
+        signatureHeader: String(req.headers[SIGNATURE_HEADER] ?? ""),
+        eventHeader: String(req.headers[EVENT_HEADER] ?? ""),
+        contentType: String(req.headers["content-type"] ?? ""),
+        receivedAt: Date.now(),
+      });
+
+      res.writeHead(responseStatuses[recorded.length - 1] ?? 200);
+      res.end();
+    });
+  });
+
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const { port } = server.address() as AddressInfo;
+  serverUrl = `http://127.0.0.1:${port}/api/revalidate`;
+});
+
+afterAll(async () => {
+  await new Promise<void>((resolve, reject) =>
+    server.close((err) => (err ? reject(err) : resolve())),
+  );
+});
+
+const originalEnv = process.env;
+
+beforeEach(() => {
+  jest.resetModules();
+  process.env = { ...originalEnv };
+  process.env.CONTENT_REVALIDATE_URL = serverUrl;
+  process.env.CONTENT_REVALIDATE_SECRET = TEST_SECRET;
+  recorded = [];
+  responseStatuses = [];
+  mockLogLines.length = 0;
+});
+
+afterEach(() => {
+  process.env = originalEnv;
+});
+
+function loadService(): typeof import("../revalidation") {
+  return require("../revalidation") as typeof import("../revalidation");
+}
+
+describe("notifyRevalidate", () => {
+  it("POSTs the four-key body once with a signature the receiver verifies", async () => {
+    responseStatuses = [200];
+
+    await loadService().notifyRevalidate(TARGET, { event: "publish" });
+
+    expect(recorded).toHaveLength(1);
+    const [req] = recorded;
+    expect(JSON.parse(req.rawBody)).toEqual(TARGET);
+    expect(Object.keys(JSON.parse(req.rawBody))).toEqual([
+      "workspaceId",
+      "type",
+      "slug",
+      "locale",
+    ]);
+    expect(req.signatureValid).toBe(true);
+    expect(req.signatureHeader).toMatch(/^sha256=[0-9a-f]{64}$/);
+    expect(req.eventHeader).toBe("publish");
+    expect(req.contentType).toBe("application/json");
+
+    const sent = mockLogLines.filter((l) => l.msg === "revalidate.sent");
+    expect(sent).toHaveLength(1);
+    expect(sent[0]).toMatchObject({
+      level: "info",
+      obj: { ...TARGET, event: "publish", attempt: 1, status: 200 },
+    });
+  });
+
+  it("retries a 5xx with D3 backoff and succeeds on the third attempt", async () => {
+    responseStatuses = [500, 500, 200];
+
+    await loadService().notifyRevalidate(TARGET, { event: "unpublish" });
+
+    expect(recorded).toHaveLength(3);
+    // D3 — 500 ms before attempt 2, 2000 ms before attempt 3. Bounded on BOTH
+    // sides: a lower bound alone would pass an arbitrarily long backoff, and
+    // the whole point of D3's schedule is that it fits the 60 s publish budget.
+    // The upper slack absorbs loopback scheduling jitter, nothing more.
+    const gapA = recorded[1].receivedAt - recorded[0].receivedAt;
+    const gapB = recorded[2].receivedAt - recorded[1].receivedAt;
+    expect(gapA).toBeGreaterThanOrEqual(500);
+    expect(gapA).toBeLessThan(2000);
+    expect(gapB).toBeGreaterThanOrEqual(2000);
+    expect(gapB).toBeLessThan(4000);
+    expect(recorded.every((r) => r.signatureValid)).toBe(true);
+
+    expect(
+      mockLogLines.filter((l) => l.msg === "revalidate.sent"),
+    ).toHaveLength(1);
+    expect(mockLogLines.some((l) => l.level === "error")).toBe(false);
+  }, 20_000);
+
+  it("stops at three attempts, logs the failure at error, and still resolves", async () => {
+    responseStatuses = [500, 500, 500];
+
+    await expect(
+      loadService().notifyRevalidate(TARGET, { event: "publish" }),
+    ).resolves.toBeUndefined();
+
+    expect(recorded).toHaveLength(3);
+
+    const perAttempt = mockLogLines.filter(
+      (l) => l.level === "warn" && l.msg === "revalidate.failed",
+    );
+    expect(perAttempt.map((l) => l.obj.attempt)).toEqual([1, 2, 3]);
+
+    const terminal = mockLogLines.filter(
+      (l) => l.level === "error" && l.msg === "revalidate.failed",
+    );
+    expect(terminal).toHaveLength(1);
+    expect(terminal[0].obj).toMatchObject({
+      ...TARGET,
+      event: "publish",
+      attempts: 3,
+      lastStatus: 500,
+    });
+  }, 20_000);
+
+  it("is a single-warning no-op with CONTENT_REVALIDATE_URL unset", async () => {
+    delete process.env.CONTENT_REVALIDATE_URL;
+    delete process.env.CONTENT_REVALIDATE_SECRET;
+
+    await expect(
+      loadService().notifyRevalidate(TARGET, { event: "publish" }),
+    ).resolves.toBeUndefined();
+
+    expect(recorded).toHaveLength(0);
+    expect(mockLogLines).toHaveLength(1);
+    expect(mockLogLines[0]).toMatchObject({
+      level: "warn",
+      msg: "revalidate.skipped",
+      obj: { ...TARGET, event: "publish", reason: "url_unset" },
+    });
+  });
+});

package/templates/apps/api/src/services/__tests__/verified-email.test.ts

@@ -0,0 +1,78 @@
+/**
+ * @file verified-email.test.ts
+ *
+ * The shared verified-email read (#5701 D4) — the one `User {id, email,
+ * emailVerified}` read every email-keyed authorization path goes through.
+ *
+ * What is asserted: the read's exact shape (the `where` and the three
+ * selected fields, which is what makes `tools/lint-email-authz.ts`'s
+ * predicate satisfiable and what the five migrated call sites' own tests
+ * still expect); the two distinct refusals, which the callers map to
+ * different outcomes on the wire; and — the invariant itself — that the
+ * address never leaves this function unless `emailVerified === true`.
+ */
+import { findVerifiedEmail } from "../verified-email";
+
+// eslint-disable-next-line no-restricted-syntax -- jest mock factory must be hoisted
+jest.mock("../../lib/prisma.js", () => ({
+  prisma: { user: { findUnique: jest.fn() } },
+}));
+
+import { prisma } from "../../lib/prisma.js";
+
+const USER_ID = "user_00000000-0000-7000-8000-0000000000a1";
+const EMAIL = "founder@example.com";
+
+beforeEach(() => {
+  jest.clearAllMocks();
+});
+
+describe("findVerifiedEmail", () => {
+  it("reads the User by id, selecting exactly id, email and emailVerified", async () => {
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue({
+      id: USER_ID,
+      email: EMAIL,
+      emailVerified: true,
+    });
+
+    await findVerifiedEmail(USER_ID);
+
+    expect(prisma.user.findUnique).toHaveBeenCalledWith({
+      where: { id: USER_ID },
+      select: { id: true, email: true, emailVerified: true },
+    });
+  });
+
+  it("returns the address when the User exists and the address is verified", async () => {
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue({
+      id: USER_ID,
+      email: EMAIL,
+      emailVerified: true,
+    });
+
+    const result = await findVerifiedEmail(USER_ID);
+
+    expect(result).toEqual({ ok: true, value: { id: USER_ID, email: EMAIL } });
+  });
+
+  it("refuses with user_not_found when there is no User row", async () => {
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue(null);
+
+    const result = await findVerifiedEmail(USER_ID);
+
+    expect(result).toEqual({ ok: false, reason: "user_not_found" });
+  });
+
+  it("refuses with email_unverified — and never yields the address — when the address is unverified", async () => {
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue({
+      id: USER_ID,
+      email: EMAIL,
+      emailVerified: false,
+    });
+
+    const result = await findVerifiedEmail(USER_ID);
+
+    expect(result).toEqual({ ok: false, reason: "email_unverified" });
+    expect(JSON.stringify(result)).not.toContain(EMAIL);
+  });
+});

package/templates/apps/api/src/services/abandon-email.ts

@@ -275,9 +275,15 @@ export async function runAbandonEmailSweep(
   if (dbError) return { ok: false, error: dbError };
 
   const now = opts.now ?? new Date();
+  // #4740: `||`, not `??` — an accidentally-set empty-string override
+  // (AILK_ABANDON_EMAIL_FROM="") is an env GAP, not a sender, so it falls
+  // through to the owner-wide default; both empty resolves to `undefined` and
+  // the `!fromAddress` guard leaves the candidate unstamped. The same shape
+  // is applied identically in waitlist-followup.ts's sibling sweep.
   const fromAddress =
-    process.env.AILK_ABANDON_EMAIL_FROM ??
-    process.env.AILK_LEAD_NOTIFICATION_FROM;
+    process.env.AILK_ABANDON_EMAIL_FROM ||
+    process.env.AILK_LEAD_NOTIFICATION_FROM ||
+    undefined;
 
   const summary: AbandonEmailSweepSummary = {
     scanned: 0,

package/templates/apps/api/src/services/aeo-score.ts

@@ -34,6 +34,20 @@ import type {
   AeoScoreResult,
 } from "@working-theory/validation";
 
+/**
+ * The readiness rules (#5949) are deliberately NOT in this set. They grade
+ * frontmatter and site-set facts (`AuditInput.readiness`); `buildAuditPayload`
+ * produces no frontmatter, so on a crawl input all three pass vacuously
+ * (packages/aeo FR5). Adding them would put three always-100 dimensions into a
+ * closed four-member public enum. `/v1/aeo/score` has no MCP twin
+ * (apps/api/CLAUDE.md § API ↔ MCP parity), so this is not a parity divergence.
+ */
+export const AEO_SCORE_EXCLUDED_READINESS_RULES = [
+  "policies-present",
+  "offer-on-priced-page",
+  "tax-code-when-stripe-tax",
+] as const;
+
 /** The service's fixed rule set — the four content rules only (§ 2.1 FR4). */
 export const AEO_SCORE_RULES: Rule[] = [
   schemaCoverage,
@@ -43,7 +57,10 @@ export const AEO_SCORE_RULES: Rule[] = [
 ];
 
 /** Severity table, verbatim from prospect-audit-site's "Compose the score-led sales report". */
-export const AEO_DIMENSION_SEVERITY: Record<AeoDimensionId, "high" | "medium" | "low"> = {
+export const AEO_DIMENSION_SEVERITY: Record<
+  AeoDimensionId,
+  "high" | "medium" | "low"
+> = {
   "schema-coverage": "high",
   "entity-markup": "high",
   "jsonld-validity": "medium",
@@ -77,7 +94,8 @@ export function resolveScoreBudgetMs(
 ): number {
   if (!rawEnv) return AEO_SCORE_DEFAULT_BUDGET_MS;
   const parsed = Number(rawEnv);
-  if (!Number.isFinite(parsed) || parsed <= 0) return AEO_SCORE_DEFAULT_BUDGET_MS;
+  if (!Number.isFinite(parsed) || parsed <= 0)
+    return AEO_SCORE_DEFAULT_BUDGET_MS;
   if (parsed > AEO_SCORE_MAX_BUDGET_MS) {
     log?.warn(
       `AEO_SCORE_BUDGET_MS=${rawEnv} exceeds the ${AEO_SCORE_MAX_BUDGET_MS}ms cap; falling back to the ${AEO_SCORE_DEFAULT_BUDGET_MS}ms default.`,
@@ -108,7 +126,10 @@ function faqHowtoOpportunityFinding(slug: string): string {
   return `${slug}: no FAQPage or HowTo structured data (a visibility opportunity, not a defect)`;
 }
 
-function buildDimension(ruleId: AeoDimensionId, report: AuditReport): AeoDimension {
+function buildDimension(
+  ruleId: AeoDimensionId,
+  report: AuditReport,
+): AeoDimension {
   const perRule = report.perRule.find((r) => r.id === ruleId) as PerRuleResult;
   const perPage = perRule.perPage ?? [];
   const fraction = perRule.score ?? (perRule.pass ? 1 : 0);
@@ -121,11 +142,20 @@ function buildDimension(ruleId: AeoDimensionId, report: AuditReport): AeoDimensi
   if (ruleId === FAQ_HOWTO_INCENTIVE_ID) {
     pagesPassing = perPage.filter((p) => p.bonus === true).length;
     const firstMissing = perPage.find((p) => p.bonus !== true);
-    finding = firstMissing ? faqHowtoOpportunityFinding(firstMissing.slug) : null;
+    finding = firstMissing
+      ? faqHowtoOpportunityFinding(firstMissing.slug)
+      : null;
   } else {
-    pagesPassing = perPage.length > 0 ? perPage.filter((p) => p.pass).length : (perRule.pass ? 1 : 0);
+    pagesPassing =
+      perPage.length > 0
+        ? perPage.filter((p) => p.pass).length
+        : perRule.pass
+          ? 1
+          : 0;
     const firstFailing = perPage.find((p) => !p.pass);
-    finding = firstFailing ? (firstFailing.evidence ?? perRule.evidence ?? null) : null;
+    finding = firstFailing
+      ? (firstFailing.evidence ?? perRule.evidence ?? null)
+      : null;
   }
 
   return {
@@ -168,11 +198,14 @@ const SSRF_GUARD_REASON_PATTERN =
  */
 function toClientSkippedEntry(entry: SkippedEntry): SkippedEntry {
   if (!SSRF_GUARD_REASON_PATTERN.test(entry.reason)) return entry;
-  console.warn("aeo-score: per-path SSRF-guard rejection (redacted on the wire)", {
-    path: entry.path,
-    url: entry.url,
-    reason: entry.reason,
-  });
+  console.warn(
+    "aeo-score: per-path SSRF-guard rejection (redacted on the wire)",
+    {
+      path: entry.path,
+      url: entry.url,
+      reason: entry.reason,
+    },
+  );
   return { ...entry, reason: "ssrf_blocked" };
 }
 
@@ -233,7 +266,11 @@ export async function scoreUrl(
     ...(deps.resolver !== undefined && { resolver: deps.resolver }),
   });
   if (!safe.ok) {
-    return { status: "unavailable", reason: "ssrf_blocked", message: safe.reason };
+    return {
+      status: "unavailable",
+      reason: "ssrf_blocked",
+      message: safe.reason,
+    };
   }
 
   const budgetMs = deps.budgetMs ?? AEO_SCORE_DEFAULT_BUDGET_MS;