create-ailk 0.1.0

package/templates/apps/api/src/routes/checkout/sessions.ts

@@ -0,0 +1,185 @@
+/**
+ * POST /api/checkout/sessions
+ *
+ * Generic Stripe checkout primitive. Resolves a productCode to a Stripe
+ * hosted-page checkout session and returns the session ID + URL.
+ *
+ * Security invariants:
+ *   - Sandbox-only: live Stripe keys are rejected at runtime before any Stripe call.
+ *   - No PII in logs: successUrl/cancelUrl and full session IDs are never logged.
+ *     Only the first 8 chars of the session ID appear in log lines.
+ *   - Error responses never echo user input (productCode, URLs).
+ *   - No DB write: this unit creates a Stripe session only; webhook-driven
+ *     persistence is a follow-up issue.
+ *   - X-Internal-Auth gate: when OSS_API_INTERNAL_SECRET env var is set,
+ *     the X-Internal-Auth header must match; requests without a matching header
+ *     are rejected with 401. When the env var is unset, no gate is applied
+ *     (backward-compat for OSS standalone deployments). See #935.
+ *
+ * Error mapping:
+ *   401 internal-auth-required — X-Internal-Auth missing/mismatch (only when env var set)
+ *   400 validation-error  — Zod validation failed (missing/invalid fields)
+ *   404 unknown-product-code — no active Stripe price for the given productCode
+ *   500 live-mode-forbidden  — STRIPE_SECRET_KEY is a live key
+ *   500 config-error         — STRIPE_SECRET_KEY missing or invalid configuration
+ *   502 checkout-unavailable — Stripe SDK threw an unexpected error
+ */
+import { timingSafeEqual } from "node:crypto";
+
+import type { FastifyReply, FastifyRequest } from "fastify";
+import { z } from "zod";
+
+import {
+  assertSandboxKey,
+  createCheckoutSession,
+  StripeConfigError,
+  UnknownProductCodeError,
+} from "../../lib/stripe.js";
+
+// ── Input validation schema ───────────────────────────────────────────────────
+
+/**
+ * Validates a redirect URL: must parse and must use http: or https: scheme.
+ * All other schemes (javascript:, ftp:, data:, file:, etc.) are rejected.
+ * Accepts http: for dev flexibility; Stripe enforces https: on production
+ * hosted-page redirects at their end.
+ */
+function isValidRedirectUrl(raw: string): boolean {
+  let parsed: URL;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    return false;
+  }
+  return parsed.protocol === "https:" || parsed.protocol === "http:";
+}
+
+const PRODUCT_CODE_REGEX = /^[A-Za-z0-9._-]{1,200}$/;
+
+const CheckoutSessionRequestSchema = z.object({
+  productCode: z
+    .string()
+    .regex(
+      PRODUCT_CODE_REGEX,
+      "productCode must match /^[A-Za-z0-9._-]{1,200}$/",
+    ),
+  successUrl: z.string().refine(isValidRedirectUrl, {
+    message:
+      "successUrl must be a valid URL with a non-empty host and not use javascript: scheme",
+  }),
+  cancelUrl: z.string().refine(isValidRedirectUrl, {
+    message:
+      "cancelUrl must be a valid URL with a non-empty host and not use javascript: scheme",
+  }),
+  quantity: z.number().int().min(1).max(999).optional(),
+});
+
+// ── Internal-auth gate ────────────────────────────────────────────────────────
+
+/**
+ * Enforce the X-Internal-Auth gate when OSS_API_INTERNAL_SECRET is configured.
+ *
+ * Gate is env-var-conditional:
+ *   - env var SET → header must be present and must match exactly
+ *   - env var UNSET → no gate applied (OSS standalone backward-compat)
+ *
+ * Returns true if the request should be allowed through; false if it must be
+ * rejected with 401.
+ *
+ * Uses a constant-time string comparison to prevent timing attacks on the
+ * secret value. Node's `crypto.timingSafeEqual` requires equal-length Buffers,
+ * so we compare lengths first (short-circuit is safe — length mismatch reveals
+ * no information about the secret's content beyond its length, which is
+ * acceptable for a shared internal secret).
+ */
+function passesInternalAuthGate(request: FastifyRequest): boolean {
+  const expectedSecret = process.env["OSS_API_INTERNAL_SECRET"];
+  // Gate is disabled when env var is not set — OSS standalone backward-compat.
+  if (!expectedSecret) return true;
+
+  const provided = request.headers["x-internal-auth"];
+  if (typeof provided !== "string" || !provided) return false;
+
+  // Constant-time comparison.
+  const expectedBuf = Buffer.from(expectedSecret, "utf8");
+  const providedBuf = Buffer.from(provided, "utf8");
+  if (expectedBuf.length !== providedBuf.length) return false;
+
+  return timingSafeEqual(expectedBuf, providedBuf);
+}
+
+// ── Handler ───────────────────────────────────────────────────────────────────
+
+export async function checkoutSessionsHandler(
+  request: FastifyRequest,
+  reply: FastifyReply,
+): Promise<void> {
+  // ── X-Internal-Auth gate (env-var-conditional) ────────────────────────────
+  if (!passesInternalAuthGate(request)) {
+    return reply.status(401).send({ error: "internal-auth-required" });
+  }
+
+  try {
+    assertSandboxKey(process.env["STRIPE_SECRET_KEY"] ?? "");
+  } catch {
+    return reply.status(500).send({ error: "live-mode-forbidden" });
+  }
+
+  const parsed = CheckoutSessionRequestSchema.safeParse(request.body);
+  if (!parsed.success) {
+    return reply.status(400).send({
+      error: "validation-error",
+      details: parsed.error.issues,
+    });
+  }
+
+  const { productCode, successUrl, cancelUrl, quantity } = parsed.data;
+
+  try {
+    const { sessionId, url } = await createCheckoutSession({
+      productCode,
+      successUrl,
+      cancelUrl,
+      quantity: quantity ?? 1,
+    });
+
+    request.log.info(
+      {
+        method: request.method,
+        path: request.url,
+        sessionIdPrefix: sessionId.substring(0, 8),
+        status: 201,
+      },
+      "[checkout] session created",
+    );
+
+    return reply.status(201).send({ sessionId, url });
+  } catch (err) {
+    if (err instanceof UnknownProductCodeError) {
+      // 404 — do NOT echo productCode in the response body
+      return reply.status(404).send({ error: "unknown-product-code" });
+    }
+    if (err instanceof StripeConfigError) {
+      // 500 — misconfiguration; log message (no PII) but never echo in response
+      request.log.error(
+        {
+          method: request.method,
+          path: request.url,
+          errName: err.name,
+          message: err.message,
+        },
+        "[checkout] config error",
+      );
+      return reply.status(500).send({ error: "config-error" });
+    }
+    request.log.error(
+      {
+        method: request.method,
+        path: request.url,
+        errName: err instanceof Error ? err.name : "unknown",
+      },
+      "[checkout] stripe error; checkout-unavailable",
+    );
+    return reply.status(502).send({ error: "checkout-unavailable" });
+  }
+}

package/templates/apps/api/src/routes/content/__tests__/create.test.ts

@@ -0,0 +1,239 @@
+/**
+ * @file create.test.ts
+ * POST /api/content/:type — D14a Stage 1 Unit B.
+ *
+ * Covers: Pro-tier gating (402), validation (400), slug allowlist (400),
+ * happy path (201 with {page, version}), slug-already-exists conflict (409
+ * with existing version echoed), and unknown :type (400).
+ *
+ * Issue #398 follow-up: the route no longer pre-checks slug existence; the
+ * adapter throws `AdapterWriteError("conflict", ..., {version})` and the
+ * hoisted `mapAdapterError` translates it. Tests construct real
+ * `AdapterWriteError` instances accordingly.
+ *
+ * Uses the real content adapter backed by a per-test temp dir (Issue #507).
+ * @working-theory/license stays mocked — it is an external package boundary.
+ */
+
+import type { FastifyInstance } from "fastify";
+
+const mockCheckLicense = jest.fn();
+
+// @working-theory/license is an external package boundary — stays mocked.
+jest.mock("@working-theory/license", () => ({
+  checkLicense: (...args: unknown[]) => mockCheckLicense(...args),
+}));
+
+import { AdapterWriteError } from "@working-theory/content-adapters";
+
+import { setupContentFixture } from "../../../__tests__/factories/content-fixture";
+import { contentRoutes } from "../index";
+
+const fixture = setupContentFixture();
+
+function proLicense() {
+  return {
+    tier: "pro",
+    plan: "pro",
+    features: [],
+    expiresAt: null,
+    revoked: false,
+  };
+}
+
+function freeLicense() {
+  return {
+    tier: "free",
+    plan: null,
+    features: [],
+    expiresAt: null,
+    revoked: false,
+  };
+}
+
+const validBody = {
+  type: "HomePage",
+  slug: "new-page",
+  title: "New Page",
+  description: "A new page description",
+  body: "New page body content",
+};
+
+describe("POST /api/content/:type", () => {
+  let app: FastifyInstance;
+
+  beforeEach(async () => {
+    app = require("fastify")();
+    await app.register(contentRoutes);
+    jest.clearAllMocks();
+    mockCheckLicense.mockReset();
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+
+  it("returns 201 with {page, version} on success", async () => {
+    mockCheckLicense.mockResolvedValue(proLicense());
+
+    // Use a unique slug so there's no conflict with fixture pages.
+    const body = { ...validBody, slug: "brand-new-page" };
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/content/HomePage",
+      payload: body,
+    });
+
+    expect(res.statusCode).toBe(201);
+    const resBody = JSON.parse(res.body);
+    expect(resBody).toHaveProperty("page");
+    expect(resBody).toHaveProperty("version");
+    expect(resBody.page).toMatchObject({ type: "HomePage", slug: "brand-new-page" });
+  });
+
+  it("returns 402 payment_required on free tier", async () => {
+    mockCheckLicense.mockResolvedValue(freeLicense());
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/content/HomePage",
+      payload: validBody,
+    });
+
+    expect(res.statusCode).toBe(402);
+    expect(JSON.parse(res.body)).toMatchObject({ error: "payment_required" });
+  });
+
+  it("returns 402 payment_required when license is revoked even at pro tier", async () => {
+    mockCheckLicense.mockResolvedValue({
+      tier: "pro",
+      plan: "pro",
+      features: [],
+      expiresAt: null,
+      revoked: true,
+    });
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/content/HomePage",
+      payload: validBody,
+    });
+
+    expect(res.statusCode).toBe(402);
+    expect(JSON.parse(res.body)).toMatchObject({ error: "payment_required" });
+  });
+
+  it("returns 409 conflict with existing version when slug already exists (adapter throws)", async () => {
+    mockCheckLicense.mockResolvedValue(proLicense());
+
+    // The fixture writes "home" in beforeEach — POST to the same slug triggers conflict.
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/content/HomePage",
+      payload: { ...validBody, slug: "home" },
+    });
+
+    // The real adapter throws AdapterWriteError("conflict") on duplicate slug.
+    expect(res.statusCode).toBe(409);
+    const body = JSON.parse(res.body);
+    expect(body).toMatchObject({ error: "conflict" });
+  });
+
+  it("does not pre-check slug existence — adapter is the sole authority (V2-H2 TOCTOU closed)", async () => {
+    mockCheckLicense.mockResolvedValue(proLicense());
+
+    // The route should NOT call getPageBySlug before createPage.
+    // We verify by checking that a slug that doesn't exist succeeds with 201.
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/content/HomePage",
+      payload: { ...validBody, slug: "toctou-test-unique-slug" },
+    });
+
+    // Route went straight to adapter.createPage — no pre-check needed.
+    expect([201, 409]).toContain(res.statusCode);
+  });
+
+  it("returns 400 validation_failed when body missing required field", async () => {
+    mockCheckLicense.mockResolvedValue(proLicense());
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/content/HomePage",
+      payload: { type: "HomePage", slug: "home", title: "T" }, // missing description, body
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(JSON.parse(res.body)).toMatchObject({ error: "validation_failed" });
+  });
+
+  it("returns 400 validation_failed when body is empty string", async () => {
+    mockCheckLicense.mockResolvedValue(proLicense());
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/content/HomePage",
+      payload: { ...validBody, body: "" },
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(JSON.parse(res.body)).toMatchObject({ error: "validation_failed" });
+  });
+
+  it("returns 400 validation_failed on unknown :type param", async () => {
+    mockCheckLicense.mockResolvedValue(proLicense());
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/content/Bogus",
+      payload: validBody,
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(JSON.parse(res.body)).toMatchObject({ error: "validation_failed" });
+  });
+
+  it("returns 400 when path :type does not match body type", async () => {
+    mockCheckLicense.mockResolvedValue(proLicense());
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/content/HomePage",
+      payload: { ...validBody, type: "AboutPage" },
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(JSON.parse(res.body)).toMatchObject({ error: "validation_failed" });
+  });
+
+  it("returns 400 validation_failed on disallowed slug shape", async () => {
+    mockCheckLicense.mockResolvedValue(proLicense());
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/content/HomePage",
+      payload: { ...validBody, slug: "../etc/passwd" },
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(JSON.parse(res.body)).toMatchObject({ error: "validation_failed" });
+  });
+
+  it("merged-error-array: invalid frontmatter AND empty body → 400 with issues from both validations surfaced", async () => {
+    mockCheckLicense.mockResolvedValue(proLicense());
+
+    const res = await app.inject({
+      method: "POST",
+      url: "/v1/content/HomePage",
+      payload: { type: "HomePage", slug: "home", title: "T", body: "" },
+    });
+
+    expect(res.statusCode).toBe(400);
+    const body = JSON.parse(res.body);
+    expect(body).toMatchObject({ error: "validation_failed" });
+
+    const issues: Array<{ path: unknown[] }> = body.details?.issues ?? [];
+    const paths = issues.map((i) => i.path.join("."));
+    expect(paths).toEqual(expect.arrayContaining(["description", "body"]));
+  });
+});

package/templates/apps/api/src/routes/content/__tests__/delete.test.ts

@@ -0,0 +1,201 @@
+/**
+ * @file delete.test.ts
+ * DELETE /api/content/:type/:slug — D14a Stage 1 Unit B.
+ *
+ * Covers: Pro-tier gating (402), missing/stale If-Match (409), happy path
+ * (204 no body), not-found (404), unknown :type (400).
+ *
+ * Issue #398 follow-up: bespoke version-probe + getPageBySlug pre-check
+ * removed; the adapter throws `AdapterWriteError("not_found" | "conflict")`
+ * and the hoisted `mapAdapterError` translates it.
+ *
+ * Uses the real content adapter backed by a per-test temp dir (Issue #507).
+ * @working-theory/license stays mocked — it is an external package boundary.
+ */
+
+import type { FastifyInstance } from "fastify";
+
+const mockCheckLicense = jest.fn();
+
+// @working-theory/license is an external package boundary — stays mocked.
+jest.mock("@working-theory/license", () => ({
+  checkLicense: (...args: unknown[]) => mockCheckLicense(...args),
+}));
+
+import { setupContentFixture } from "../../../__tests__/factories/content-fixture";
+import { contentRoutes } from "../index";
+
+const fixture = setupContentFixture();
+
+function proLicense() {
+  return {
+    tier: "pro",
+    plan: "pro",
+    features: [],
+    expiresAt: null,
+    revoked: false,
+  };
+}
+
+function freeLicense() {
+  return {
+    tier: "free",
+    plan: null,
+    features: [],
+    expiresAt: null,
+    revoked: false,
+  };
+}
+
+describe("DELETE /api/content/:type/:slug", () => {
+  let app: FastifyInstance;
+
+  beforeEach(async () => {
+    app = require("fastify")();
+    await app.register(contentRoutes);
+    jest.clearAllMocks();
+    mockCheckLicense.mockReset();
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+
+  it("returns 204 with no body on success", async () => {
+    mockCheckLicense.mockResolvedValue(proLicense());
+
+    // First create the page, get its version, then delete it.
+    const createRes = await app.inject({
+      method: "POST",
+      url: "/v1/content/HomePage",
+      payload: {
+        type: "HomePage",
+        slug: "page-to-delete",
+        title: "Page To Delete",
+        description: "This page will be deleted",
+        body: "Goodbye",
+      },
+    });
+    expect(createRes.statusCode).toBe(201);
+    const { version } = JSON.parse(createRes.body);
+
+    const res = await app.inject({
+      method: "DELETE",
+      url: "/v1/content/HomePage/page-to-delete",
+      headers: { "if-match": version },
+    });
+
+    expect(res.statusCode).toBe(204);
+    expect(res.body).toBe("");
+  });
+
+  it("returns 402 payment_required on free tier", async () => {
+    mockCheckLicense.mockResolvedValue(freeLicense());
+
+    const res = await app.inject({
+      method: "DELETE",
+      url: "/v1/content/HomePage/home",
+      headers: { "if-match": "v1" },
+    });
+
+    expect(res.statusCode).toBe(402);
+  });
+
+  it("returns 402 payment_required when license is revoked even at pro tier", async () => {
+    mockCheckLicense.mockResolvedValue({
+      tier: "pro",
+      plan: "pro",
+      features: [],
+      expiresAt: null,
+      revoked: true,
+    });
+
+    const res = await app.inject({
+      method: "DELETE",
+      url: "/v1/content/HomePage/home",
+      headers: { "if-match": "v1" },
+    });
+
+    expect(res.statusCode).toBe(402);
+    expect(JSON.parse(res.body)).toMatchObject({ error: "payment_required" });
+  });
+
+  it("returns 409 conflict when If-Match header is missing", async () => {
+    mockCheckLicense.mockResolvedValue(proLicense());
+
+    const res = await app.inject({
+      method: "DELETE",
+      url: "/v1/content/HomePage/home",
+    });
+
+    expect(res.statusCode).toBe(409);
+    expect(JSON.parse(res.body)).toMatchObject({ error: "conflict" });
+  });
+
+  it("returns 409 conflict when If-Match is empty string", async () => {
+    mockCheckLicense.mockResolvedValue(proLicense());
+
+    const res = await app.inject({
+      method: "DELETE",
+      url: "/v1/content/HomePage/home",
+      headers: { "if-match": "" },
+    });
+
+    expect(res.statusCode).toBe(409);
+  });
+
+  it("returns 409 conflict with currentVersion echoed when adapter signals stale If-Match", async () => {
+    mockCheckLicense.mockResolvedValue(proLicense());
+
+    // Pass a stale version — the real adapter will reject it with conflict.
+    const res = await app.inject({
+      method: "DELETE",
+      url: "/v1/content/HomePage/home",
+      headers: { "if-match": "stale-version-that-does-not-match" },
+    });
+
+    expect(res.statusCode).toBe(409);
+    const body = JSON.parse(res.body);
+    expect(body).toMatchObject({ error: "conflict" });
+    if (body.details) {
+      expect(body.details).toHaveProperty("currentVersion");
+    }
+  });
+
+  it("returns 404 not_found when adapter signals page missing", async () => {
+    mockCheckLicense.mockResolvedValue(proLicense());
+
+    const res = await app.inject({
+      method: "DELETE",
+      url: "/v1/content/HomePage/slug-that-does-not-exist",
+      headers: { "if-match": "any-version" },
+    });
+
+    expect(res.statusCode).toBe(404);
+    expect(JSON.parse(res.body)).toMatchObject({ error: "not_found" });
+  });
+
+  it("returns 400 validation_failed on unknown :type", async () => {
+    mockCheckLicense.mockResolvedValue(proLicense());
+
+    const res = await app.inject({
+      method: "DELETE",
+      url: "/v1/content/Bogus/home",
+      headers: { "if-match": "v1" },
+    });
+
+    expect(res.statusCode).toBe(400);
+  });
+
+  it("returns 400 validation_failed on disallowed slug shape", async () => {
+    mockCheckLicense.mockResolvedValue(proLicense());
+
+    const res = await app.inject({
+      method: "DELETE",
+      url: "/v1/content/HomePage/..%2Fetc%2Fpasswd",
+      headers: { "if-match": "v1" },
+    });
+
+    expect(res.statusCode).toBe(400);
+  });
+});