create-ailk 0.1.0

package/templates/apps/api/src/services/__tests__/lead-routing.test.ts

@@ -0,0 +1,395 @@
+/**
+ * @file lead-routing.test.ts
+ * @description Unit tests for the lead-routing service (ADR 0009 D3 service-layer pattern).
+ *
+ * External dependency boundaries mocked:
+ *   - @working-theory/database (via moduleNameMapper → prisma-client.js mock; prisma singleton via __mocks__/prisma.ts)
+ *   - @working-theory/email sendLeadNotification
+ *
+ * Internal modules run real:
+ *   - apps/api/src/services/enrichment-shim — real; @working-theory/license catches + returns lead unchanged
+ *   - apps/api/src/lib/file-fallback — real; uses AILK_INBOX_FALLBACK_DIR temp dir set per test
+ *   - apps/api/src/lib/prisma — uses __mocks__/prisma.ts (manual mock via jest.mock without factory)
+ */
+
+import type { RouteLeadResult } from "../lead-routing";
+
+// ─── Mock: Prisma ─────────────────────────────────────────────────────────────
+// lib/prisma.ts is a thin wrapper that instantiates PrismaClient (external DB
+// boundary). The manual mock at src/lib/__mocks__/prisma.ts provides a full
+// in-memory stub — this call auto-resolves to that file.
+// eslint-disable-next-line no-restricted-syntax -- lib/prisma.ts wraps the external DB boundary (PrismaClient requires a live connection); __mocks__/prisma.ts is the repo-standard test double for this boundary.
+jest.mock("../../lib/prisma.js");
+
+// ─── Mock: email (external boundary) ─────────────────────────────────────────
+const mockSendLeadNotification = jest.fn();
+jest.mock("@working-theory/email", () => ({
+  sendLeadNotification: (...args: unknown[]) =>
+    mockSendLeadNotification(...args),
+}));
+
+// ─── Import after mocks ───────────────────────────────────────────────────────
+import * as fs from "fs/promises";
+import * as os from "os";
+import * as path from "path";
+
+import { prisma } from "../../lib/prisma.js";
+import { routeLead } from "../lead-routing";
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+const sourceMeta = {
+  ip: "127.0.0.1",
+  userAgent: "jest",
+  receivedAt: new Date().toISOString(),
+};
+
+const leadInput = {
+  kind: "lead" as const,
+  siteId: "site-abc",
+  source: "contact",
+  email: "test@example.com",
+  payload: { message: "hello" },
+};
+
+const subscribeInput = {
+  kind: "subscribe" as const,
+  siteId: "site-abc",
+  email: "subscriber@example.com",
+  source: "footer",
+};
+
+const callbackInput = {
+  kind: "callback" as const,
+  siteId: "site-abc",
+  name: "Alice",
+  phone: "+15551234567",
+  payload: { notes: "urgent" },
+};
+
+// ─── Tests ────────────────────────────────────────────────────────────────────
+describe("routeLead", () => {
+  let tmpDir: string;
+
+  beforeAll(async () => {
+    // Real file-fallback module uses AILK_INBOX_FALLBACK_DIR for writes.
+    // Point it at a temp dir so tests remain hermetic.
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "ailk-lead-test-"));
+    process.env.AILK_INBOX_FALLBACK_DIR = tmpDir;
+  });
+
+  afterAll(async () => {
+    delete process.env.AILK_INBOX_FALLBACK_DIR;
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    // Default: DB up, email up
+    (prisma.lead.create as jest.Mock).mockResolvedValue({
+      id: "cuid-lead-1",
+      siteId: "site-abc",
+      source: "contact",
+      email: "test@example.com",
+      payload: {},
+      createdAt: new Date(),
+    });
+    (prisma.subscriber.create as jest.Mock).mockResolvedValue({
+      id: "cuid-sub-1",
+      siteId: "site-abc",
+      email: "subscriber@example.com",
+      source: "footer",
+      createdAt: new Date(),
+    });
+    (prisma.callback.create as jest.Mock).mockResolvedValue({
+      id: "cuid-cb-1",
+      siteId: "site-abc",
+      name: "Alice",
+      phone: "+15551234567",
+      payload: {},
+      createdAt: new Date(),
+    });
+    mockSendLeadNotification.mockResolvedValue({
+      ok: true,
+      messageId: "msg-123",
+    });
+    // Set required env
+    process.env.AILK_LEAD_NOTIFICATION_TO = "owner@example.com";
+    process.env.AILK_LEAD_NOTIFICATION_FROM = "noreply@example.com";
+  });
+
+  afterEach(() => {
+    delete process.env.AILK_LEAD_NOTIFICATION_TO;
+    delete process.env.AILK_LEAD_NOTIFICATION_FROM;
+  });
+
+  // ── 1. Happy path lead — DB up, email up ──────────────────────────────────
+  it("happy path lead — returns ok:true with persisted:db and email:ok", async () => {
+    const result = await routeLead(leadInput, sourceMeta);
+
+    expect(result).toMatchObject({
+      ok: true,
+      id: "cuid-lead-1",
+      persisted: "db",
+      email: { ok: true, messageId: "msg-123" },
+    });
+    expect(prisma.lead.create).toHaveBeenCalledTimes(1);
+  });
+
+  // ── 2. DB down → fallback engages → persisted:file ───────────────────────
+  it("DB down → file fallback → persisted:file", async () => {
+    (prisma.lead.create as jest.Mock).mockRejectedValue(new Error("connection refused"));
+
+    const result = (await routeLead(leadInput, sourceMeta)) as Extract<
+      RouteLeadResult,
+      { ok: true }
+    >;
+
+    expect(result.ok).toBe(true);
+    expect(result.persisted).toBe("file");
+    // Verify a file was actually written to the temp dir
+    const files = await fs.readdir(tmpDir);
+    expect(files.length).toBeGreaterThan(0);
+  });
+
+  // ── 3. DB down + fallback fails → persist_failed ─────────────────────────
+  it("DB down + fallback fails → ok:false persist_failed", async () => {
+    (prisma.lead.create as jest.Mock).mockRejectedValue(new Error("db error"));
+    // Point fallback at a nonexistent dir so mkdir fails
+    process.env.AILK_INBOX_FALLBACK_DIR = "/nonexistent-ailk-test-dir/inbox";
+
+    const result = (await routeLead(leadInput, sourceMeta)) as Extract<
+      RouteLeadResult,
+      { ok: false }
+    >;
+
+    // Restore good temp dir for other tests
+    process.env.AILK_INBOX_FALLBACK_DIR = tmpDir;
+
+    expect(result.ok).toBe(false);
+    expect(result.error.kind).toBe("persist_failed");
+  });
+
+  // ── 4. Email down → persist succeeds, email error returned ───────────────
+  it("email failure does NOT roll back DB write — returns ok:true with email error", async () => {
+    mockSendLeadNotification.mockResolvedValue({
+      ok: false,
+      error: { kind: "send_failed", message: "timeout" },
+    });
+
+    const result = (await routeLead(leadInput, sourceMeta)) as Extract<
+      RouteLeadResult,
+      { ok: true }
+    >;
+
+    expect(result.ok).toBe(true);
+    expect(result.persisted).toBe("db");
+    expect(result.email).toMatchObject({
+      ok: false,
+      error: "send_failed: timeout",
+    });
+    expect(prisma.lead.create).toHaveBeenCalledTimes(1); // DB write happened
+  });
+
+  // ── 5. Resend env unset → email skipped ──────────────────────────────────
+  it("AILK_LEAD_NOTIFICATION_TO unset → email skipped with reason env_unset", async () => {
+    delete process.env.AILK_LEAD_NOTIFICATION_TO;
+
+    const result = (await routeLead(leadInput, sourceMeta)) as Extract<
+      RouteLeadResult,
+      { ok: true }
+    >;
+
+    expect(result.ok).toBe(true);
+    expect(result.email).toMatchObject({ skipped: true, reason: "env_unset" });
+    expect(mockSendLeadNotification).not.toHaveBeenCalled();
+  });
+
+  it("config_missing from Resend → email coerced to skipped:resend_key_unset", async () => {
+    mockSendLeadNotification.mockResolvedValue({
+      ok: false,
+      error: { kind: "config_missing", message: "RESEND_API_KEY not set" },
+    });
+
+    const result = (await routeLead(leadInput, sourceMeta)) as Extract<
+      RouteLeadResult,
+      { ok: true }
+    >;
+
+    expect(result.ok).toBe(true);
+    expect(result.email).toMatchObject({
+      skipped: true,
+      reason: "resend_key_unset",
+    });
+  });
+
+  // ── 6. Subscribe duplicate (P2002) → sentinel id, email skipped:duplicate ─
+  it("subscribe duplicate P2002 → ok:true with email.skipped.reason duplicate", async () => {
+    const p2002 = Object.assign(new Error("Unique constraint"), {
+      code: "P2002",
+    });
+    (prisma.subscriber.create as jest.Mock).mockRejectedValue(p2002);
+    (prisma.subscriber.findUnique as jest.Mock).mockResolvedValue({
+      id: "existing-sub-id",
+      siteId: "site-abc",
+      email: "subscriber@example.com",
+    });
+
+    const result = (await routeLead(subscribeInput, sourceMeta)) as Extract<
+      RouteLeadResult,
+      { ok: true }
+    >;
+
+    expect(result.ok).toBe(true);
+    expect(result.id).toBe("existing-sub-id");
+    expect(result.persisted).toBe("db");
+    expect(result.email).toMatchObject({ skipped: true, reason: "duplicate" });
+    expect(mockSendLeadNotification).not.toHaveBeenCalled();
+  });
+
+  it("subscribe duplicate P2002 with lookup miss → sentinel id duplicate-no-id", async () => {
+    const p2002 = Object.assign(new Error("Unique constraint"), {
+      code: "P2002",
+    });
+    (prisma.subscriber.create as jest.Mock).mockRejectedValue(p2002);
+    (prisma.subscriber.findUnique as jest.Mock).mockResolvedValue(null);
+
+    const result = (await routeLead(subscribeInput, sourceMeta)) as Extract<
+      RouteLeadResult,
+      { ok: true }
+    >;
+
+    expect(result.ok).toBe(true);
+    expect(result.id).toBe("duplicate-no-id");
+    expect(result.email).toMatchObject({ skipped: true, reason: "duplicate" });
+  });
+
+  // ── 7. Validation failure → invalid_input ────────────────────────────────
+  it("malformed input (missing email) → ok:false invalid_input", async () => {
+    const bad = {
+      kind: "lead" as const,
+      siteId: "site",
+      source: "contact",
+      email: "not-an-email",
+      payload: {},
+    };
+
+    const result = (await routeLead(bad, sourceMeta)) as Extract<
+      RouteLeadResult,
+      { ok: false }
+    >;
+
+    expect(result.ok).toBe(false);
+    expect(result.error.kind).toBe("invalid_input");
+  });
+
+  // ── 8. PII non-leak — log spy never sees email/phone/name/payload ─────────
+  it("PII non-leak — log output never contains email, phone, name, or payload values", async () => {
+    const logLines: string[] = [];
+    const infoSpy = jest
+      .spyOn(console, "info")
+      .mockImplementation((...args) => {
+        logLines.push(args.map(String).join(" "));
+      });
+    const warnSpy = jest
+      .spyOn(console, "warn")
+      .mockImplementation((...args) => {
+        logLines.push(args.map(String).join(" "));
+      });
+    const logSpy = jest.spyOn(console, "log").mockImplementation((...args) => {
+      logLines.push(args.map(String).join(" "));
+    });
+
+    await routeLead(leadInput, sourceMeta);
+    await routeLead(callbackInput, sourceMeta);
+
+    const combined = logLines.join("\n");
+
+    // PII values must not appear in any log output
+    expect(combined).not.toContain("test@example.com");
+    expect(combined).not.toContain("+15551234567");
+    expect(combined).not.toContain("Alice");
+    // payload values must not appear
+    expect(combined).not.toContain("hello");
+    expect(combined).not.toContain("urgent");
+
+    infoSpy.mockRestore();
+    warnSpy.mockRestore();
+    logSpy.mockRestore();
+  });
+
+  // ── Callback happy path ───────────────────────────────────────────────────
+  it("callback happy path → persisted:db", async () => {
+    const result = (await routeLead(callbackInput, sourceMeta)) as Extract<
+      RouteLeadResult,
+      { ok: true }
+    >;
+
+    expect(result.ok).toBe(true);
+    expect(result.id).toBe("cuid-cb-1");
+    expect(result.persisted).toBe("db");
+    expect(prisma.callback.create).toHaveBeenCalledTimes(1);
+  });
+
+  // ── routeLead never throws ────────────────────────────────────────────────
+  it("routeLead never throws even when all dependencies fail", async () => {
+    (prisma.lead.create as jest.Mock).mockRejectedValue(new Error("db down"));
+    // Point fallback at a bad dir so file write also fails
+    process.env.AILK_INBOX_FALLBACK_DIR = "/nonexistent-ailk-test-dir-2/inbox";
+
+    // Should not throw — returns ok:false instead
+    await expect(routeLead(leadInput, sourceMeta)).resolves.toBeDefined();
+
+    // Restore
+    process.env.AILK_INBOX_FALLBACK_DIR = tmpDir;
+  });
+
+  // ── Regression: HIGH-1 — extra field in input must not be passed through ──
+  // The route handler must NOT spread unknown fields from the request body into
+  // the service call. The service's Zod validation via .strict() must reject
+  // unknown keys; the id field is controlled server-side only.
+  it("regression HIGH-1: input with extra 'id' field is rejected by strict schema validation", async () => {
+    const inputWithExtraId = {
+      kind: "lead" as const,
+      siteId: "site-abc",
+      source: "contact",
+      email: "test@example.com",
+      payload: { message: "hello" },
+      id: "attacker-supplied-id", // extra field — must be rejected by .strict()
+    };
+
+    // .strict() on leadSubmitSchema rejects unknown keys → invalid_input
+    // Omit the extra `id` field from the type so only one cast is needed.
+    const { id: _id, ...inputWithoutId } = inputWithExtraId;
+    const inputForService = {
+      ...inputWithoutId,
+      // Re-attach as a plain unknown property so Zod's strict() can reject it.
+      ...({"id": inputWithExtraId.id} as Record<string, unknown>),
+    } as Parameters<typeof routeLead>[0];
+    const result = (await routeLead(inputForService, sourceMeta)) as Extract<RouteLeadResult, { ok: false }>;
+
+    expect(result.ok).toBe(false);
+    expect(result.error.kind).toBe("invalid_input");
+    // The DB must not have been called with an attacker-supplied id
+    expect(prisma.lead.create).not.toHaveBeenCalled();
+  });
+
+  // ── Regression: MEDIUM-4 — CRLF injection in siteId must be rejected ─────
+  // siteId is constrained to /^[a-zA-Z0-9._-]+$/ which excludes \r\n.
+  it("regression MEDIUM-4: CRLF injection in siteId returns invalid_input", async () => {
+    const inputWithCrlf = {
+      kind: "subscribe" as const,
+      siteId: "x\r\nBcc: attacker@x.com", // header injection attempt
+      email: "victim@example.com",
+      source: "footer",
+    };
+
+    const result = (await routeLead(inputWithCrlf, sourceMeta)) as Extract<
+      RouteLeadResult,
+      { ok: false }
+    >;
+
+    expect(result.ok).toBe(false);
+    expect(result.error.kind).toBe("invalid_input");
+    expect(prisma.subscriber.create).not.toHaveBeenCalled();
+  });
+});

package/templates/apps/api/src/services/enrichment-shim.ts

@@ -0,0 +1,53 @@
+/**
+ * @file enrichment-shim.ts
+ * @description License-gated lead enrichment stub.
+ *
+ * Today: checkLicense()-gated branch — log a deduped sentinel for pro tier, return
+ * lead unchanged. Phase 3: real enrichment replaces this file; the call site
+ * (B6 lead-routing pipeline) stays stable.
+ *
+ * ADR 0008: license key is never logged raw — only the SHA-256 hash prefix
+ * (first 8 chars) appears in log output.
+ * ADR 0009 §D3: service-layer placement at apps/api/src/services/.
+ * ADR 0014: license is a JWT verified locally; tier read via `result.tier`.
+ */
+
+import { createHash } from "crypto";
+
+import { checkLicense } from "@working-theory/license";
+import { logger } from "@working-theory/observability";
+// TODO(#214): swap to canonical Lead from @working-theory/validation when B1 lands.
+import type { CreateLead as Lead } from "@working-theory/validation";
+
+// Routes the once-per-process Pro sentinel through @working-theory/observability so it
+// shares the redact + entropy pipeline (S17). The signature stays unchanged.
+
+type EnrichedLead = Lead & { _enrichedAt?: string }; // type union shape; today equals Lead
+
+// Module-scoped sentinel flag — one log per process lifecycle. Process restart re-arms it.
+let proSentinelLogged = false;
+
+function hashPrefix(key: string): string {
+  return createHash("sha256").update(key).digest("hex").substring(0, 8);
+}
+
+export async function enrichLead(lead: Lead): Promise<EnrichedLead | Lead> {
+  let result;
+  try {
+    result = await checkLicense();
+  } catch {
+    return lead;
+  }
+
+  if (result.tier === "pro" && !proSentinelLogged) {
+    const key = process.env["AILK_LICENSE_KEY"];
+    const prefix = key ? hashPrefix(key) : "no-key";
+    logger.info(
+      { licensePrefix: prefix },
+      "[enrichment-shim] Pro server processing not yet operational — falling back to OSS path",
+    );
+    proSentinelLogged = true;
+  }
+
+  return lead;
+}