create-ailk 0.24.0 → 0.25.1

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

@@ -1,141 +0,0 @@
-/**
- * Webhooks route group.
- *
- * Routes:
- *   POST /v1/webhooks/stripe — verify Stripe signature, dispatch event,
- *                               fire telemetry, respond 200.
- *   POST /v1/webhooks/stripe/:connectionToken — the per-Organization
- *                               receiver (#8932 D1): the token names ONE
- *                               Organization's StripeConnection, whose own
- *                               secret verifies the delivery and whose
- *                               recorded Offerings sessions it fulfils.
- *                               Base tree like the legacy receiver — the
- *                               commerce claim is read at call time — with
- *                               its own rate-limit bucket.
- *   POST /v1/webhooks/calcom — verify the scheduling provider's signature,
- *                               normalize a booking event into an
- *                               Appointment row (#6085, brief H7).
- *                               Module-conditional (`scheduling`, § D1) —
- *                               reached through an indirect dynamic import
- *                               so a keyless scaffold never resolves
- *                               `calcom.ts`, which it does not have.
- *   POST /v1/webhooks/calcom/:connectionToken — the same receiver for ONE
- *                               workspace's own scheduling connection
- *                               (#7533 D6): the token names the connection,
- *                               whose own secret verifies the delivery and
- *                               whose workspace receives the Appointment.
- *                               Same module gate, same `loadSlice` call,
- *                               its own rate-limit bucket.
- *
- * Rate limit: each receiver carries its OWN 100 req/min/IP bucket, from the
- * ONE plugin-level `rateLimit` registration below (a second plugin-level
- * registration in this same scope would fail — § D3). Above either
- * provider's actual retry cadence but tight enough to make replay-flood
- * DoS unattractive. Encapsulated to the webhooks scope so the global
- * content limit (60/min) doesn't bleed in.
- */
-import rateLimit from "@fastify/rate-limit";
-import type { FastifyPluginAsync, FastifyReply, FastifyRequest } from "fastify";
-
-import { isModuleEnabled } from "../../config/modules.js";
-import { loadSlice } from "../../lib/slice-load.js";
-
-import { stripeOfferingsWebhookHandler } from "./stripe-offerings.js";
-import { stripeWebhookHandler } from "./stripe.js";
-
-export const STRIPE_WEBHOOK_RATE_LIMIT_PER_MIN = 100;
-export const STRIPE_OFFERINGS_WEBHOOK_RATE_LIMIT_PER_MIN = 100;
-export const CALCOM_WEBHOOK_RATE_LIMIT_PER_MIN = 100;
-
-// Kept off the `import()` call site so `tsc` never resolves it and the OSS
-// strip stays green on a keyless scaffold (#5182 D1); traced to
-// `@vercel/nft` by staying a module-level constant read at THIS call site
-// (#5304 D3) — the `routes/project-listings/index.ts:135` in-route-index
-// shape (§ D1), applied here because `webhooks/index.ts` is NOT itself a
-// scheduling-owned file (it also registers the Stripe receiver, a base-tree
-// commerce primitive, so it ships to every scaffold) while `calcom.ts` IS
-// (`packages/create-ailk/src/module-architecture.ts`'s scheduling
-// `ownedFiles`) and does not exist on a keyless one.
-const CALCOM_HANDLER = "./calcom.js";
-
-export const webhooksRoutes: FastifyPluginAsync = async (fastify) => {
-  // Register rate-limit at this scope so the webhook gets its own bucket
-  // distinct from the public content API's global limiter.
-  await fastify.register(rateLimit, {
-    global: false,
-    max: STRIPE_WEBHOOK_RATE_LIMIT_PER_MIN,
-    timeWindow: "1 minute",
-  });
-
-  fastify.post(
-    "/v1/webhooks/stripe",
-    {
-      config: {
-        rateLimit: {
-          max: STRIPE_WEBHOOK_RATE_LIMIT_PER_MIN,
-          timeWindow: "1 minute",
-        },
-      },
-    },
-    stripeWebhookHandler,
-  );
-
-  fastify.post(
-    "/v1/webhooks/stripe/:connectionToken",
-    {
-      config: {
-        rateLimit: {
-          max: STRIPE_OFFERINGS_WEBHOOK_RATE_LIMIT_PER_MIN,
-          timeWindow: "1 minute",
-        },
-      },
-    },
-    stripeOfferingsWebhookHandler,
-  );
-
-  if (isModuleEnabled("scheduling")) {
-    const mod = (await loadSlice(CALCOM_HANDLER, () => import(CALCOM_HANDLER))) as {
-      calcomWebhookHandler?: (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
-      calcomConnectionWebhookHandler?: (
-        request: FastifyRequest,
-        reply: FastifyReply,
-      ) => Promise<void>;
-    };
-    const handler = mod.calcomWebhookHandler;
-    if (!handler) {
-      throw new Error(
-        `AILK slice drift: '${CALCOM_HANDLER}' does not export 'calcomWebhookHandler'`,
-      );
-    }
-    const connectionHandler = mod.calcomConnectionWebhookHandler;
-    if (!connectionHandler) {
-      throw new Error(
-        `AILK slice drift: '${CALCOM_HANDLER}' does not export 'calcomConnectionWebhookHandler'`,
-      );
-    }
-    fastify.post(
-      "/v1/webhooks/calcom",
-      {
-        config: {
-          rateLimit: {
-            max: CALCOM_WEBHOOK_RATE_LIMIT_PER_MIN,
-            timeWindow: "1 minute",
-          },
-        },
-      },
-      handler,
-    );
-    fastify.post(
-      "/v1/webhooks/calcom/:connectionToken",
-      {
-        config: {
-          rateLimit: {
-            max: CALCOM_WEBHOOK_RATE_LIMIT_PER_MIN,
-            timeWindow: "1 minute",
-          },
-        },
-      },
-      connectionHandler,
-    );
-  }
-};

package/templates/apps/api/src/routes/webhooks/stripe-offerings.ts

@@ -1,384 +0,0 @@
-/**
- * POST /v1/webhooks/stripe/:connectionToken — the per-Organization Stripe
- * webhook (#8932; spec docs/specs/8932-the-per-organization-stripe-webhook-spec.md;
- * contract docs/specs/8879-the-offerings-security-contract-key-spec.md W1,
- * W3–W11, G5, T8).
- *
- * The token names ONE StripeConnection row (#8907 D11): that row's decrypted
- * secret verifies the signature, with no env key (W3, the key-less verify),
- * and its `organizationId` is the only Organization the event can act for —
- * nothing in the body, query or headers changes it. The event acts only for a
- * Checkout Session the hub's own checkout recorded (#8930's record, A11) for
- * that Organization, whose signed `metadata.site` is the record's workspace
- * (W5), whose paid line item is the record's Price (W6), once per session, as
- * one lead whose offering is the record's FULL lookup key (G5) and which — for
- * a live session — carries the held-plan marker #8793's release reads (W7).
- *
- * THE LADDER (D2). One handler; the first step that answers ends the request:
- *
- *    1  token lookup `not-found` (or a non-string param) → 404, no line
- *   1a  token lookup rejects                → 503 webhook-unavailable
- *    2  `not-configured` / `unreadable`     → 503 webhook-not-configured
- *    3  settle the signature (held as a value, as the legacy route does)
- *    4  commerce claim `undetermined`       → 503 + Retry-After
- *    5  `unclaimed`: signed → 200 dropped; unsigned → the module-disabled 404
- *    6  the held rejection                  → 400
- *    7  W4 livemode ≠ the row's mode        → 200 livemode_mismatch
- *    8  W5 not a completed / async-paid session → 200 ignored_type
- *  9–11 W5 the record: rejects → 503, `"unreadable"` → 500, none → 200 unrecorded
- *   12  another Organization's record, or `metadata.site` ≠ the record's
- *       workspace                          → 200 foreign_organization
- *   13  the record's mode ≠ the row's      → 200 livemode_mismatch
- *   14  W10 seen for this Organization     → 200 duplicate
- *   15  W6 a completed session not paid   → 200 unpaid (seen)
- *   16  W6 the line items cannot be read   → 503 stripe-unavailable
- *   17  W6 not exactly the record's Price  → 200 offering_mismatch (seen)
- *   18  W7 fulfil through `routeLead`      → 200 fulfilled / already_fulfilled /
- *       unfulfillable (seen), else 503 fulfilment-unavailable
- *
- * Every 200 body is `{ received: true }` — the outcome is the log line's,
- * never the body's, because Stripe shows the seller every response body
- * (C1, SEC-8932-13). No non-2xx answer is ever marked seen, so Stripe's retry
- * reaches a corrected deployment (SEC-8930-1). Dedup is this endpoint's own
- * per-Organization store (D8), checked after attribution, so a foreign or
- * unrecorded event is in no store at all (W10).
- *
- * LOGGING (W9, C6). Each line carries exactly the keys D2 names for its step:
- * `organizationId`, `eventType`, an 8-character `eventIdPrefix` and `outcome`
- * — never the token, the secret, a full Stripe id, the buyer's email, the
- * lookup key, a metadata value, line-item text or an error message. Every
- * rejection the handler awaits is caught here, so none reaches Fastify's
- * error handler. The token never reaches a request line either: the shared
- * path redactor (`lib/error-serializer.ts`'s `redactLogPath`, D10) replaces
- * it whole.
- *
- * W11. No billing identity is bound from a connection's event: this file
- * imports none of the legacy route's billing functions and its only write is
- * the one lead.
- */
-import type { FastifyReply, FastifyRequest } from "fastify";
-
-import {
-  commerceDisabledResponse,
-  LICENSE_UNDETERMINED_BODY,
-  LICENSE_UNDETERMINED_RETRY_AFTER_SECONDS,
-  LICENSE_UNDETERMINED_STATUS,
-  resolveCommerceClaim,
-} from "../../lib/require-commerce-claim.js";
-import {
-  StripeWebhookSignatureError,
-  verifyWebhookSignatureKeyless,
-} from "../../lib/stripe.js";
-import {
-  hasSeenForOrganization,
-  markSeenForOrganization,
-} from "../../lib/webhook-idempotency.js";
-import { routeLead, type RouteLeadResult } from "../../services/lead-routing.js";
-import {
-  readCheckoutSessionRecord,
-  type CheckoutSessionRecord,
-} from "../../services/offerings/checkout-session-record.js";
-import {
-  findStripeConnectionByWebhookToken,
-  stripeClientForOrganization,
-  type StripeWebhookConnection,
-} from "../../services/offerings/connection.js";
-
-/** A space: no `Idempotency-Key` header can carry one, so no request can pre-seed this key (NFR6). */
-const OFFERINGS_LEAD_KEY_PREFIX = "stripe-offerings ";
-
-/** The two session events that can fulfil (W5). */
-const FULFILLING_EVENT_TYPES = new Set([
-  "checkout.session.completed",
-  "checkout.session.async_payment_succeeded",
-]);
-
-/** The server-written terms stamp the hub's checkout puts in `metadata` (#8765 D14). */
-const TERMS_STAMP_KEY = "ailk_terms";
-
-type VerifiedEvent = ReturnType<typeof verifyWebhookSignatureKeyless>;
-type Connection = Extract<StripeWebhookConnection, { kind: "ok" }>;
-
-type SettledSignature =
-  | { ok: true; event: VerifiedEvent }
-  | { ok: false; status: number; body: { error: string }; verifyThrew: boolean };
-
-/** The fields of a signed Checkout Session this route reads — read, never trusted beyond the signature. */
-type SessionObject = {
-  object?: unknown;
-  id?: unknown;
-  payment_status?: unknown;
-  amount_total?: unknown;
-  currency?: unknown;
-  customer_details?: { email?: unknown } | null;
-  consent?: { terms_of_service?: unknown } | null;
-  metadata?: Record<string, unknown> | null;
-};
-
-/** Step 3: the signature as a value, so the claim can be read before any rejection is sent (D-64). */
-function settleSignature(request: FastifyRequest, secret: string): SettledSignature {
-  const rawBody = request.body;
-  if (!Buffer.isBuffer(rawBody)) {
-    return { ok: false, status: 400, body: { error: "invalid-request" }, verifyThrew: false };
-  }
-  const signature = request.headers["stripe-signature"];
-  if (typeof signature !== "string" || signature.length === 0) {
-    return { ok: false, status: 400, body: { error: "signature-missing" }, verifyThrew: false };
-  }
-  try {
-    return { ok: true, event: verifyWebhookSignatureKeyless(rawBody, signature, secret) };
-  } catch (err) {
-    if (err instanceof StripeWebhookSignatureError) {
-      return { ok: false, status: 400, body: { error: "signature-invalid" }, verifyThrew: true };
-    }
-    throw err;
-  }
-}
-
-/** The event keys every line from step 7 on carries (W9). */
-function eventKeys(organizationId: string, event: VerifiedEvent) {
-  return {
-    organizationId,
-    eventType: event.type,
-    eventIdPrefix: event.id.slice(0, 8),
-  };
-}
-
-function objectOf(value: unknown): Record<string, unknown> | null {
-  return typeof value === "object" && value !== null
-    ? (value as Record<string, unknown>)
-    : null;
-}
-
-export const stripeOfferingsWebhookHandler = async (
-  request: FastifyRequest,
-  reply: FastifyReply,
-): Promise<void> => {
-  // ── Steps 1, 1a, 2 — the token selects the connection (W1, W2) ───────────
-  const token = (request.params as { connectionToken?: unknown } | undefined)
-    ?.connectionToken;
-  let connection: StripeWebhookConnection;
-  try {
-    connection =
-      typeof token === "string"
-        ? await findStripeConnectionByWebhookToken(token)
-        : { kind: "not-found" };
-  } catch {
-    request.log.error(
-      { outcome: "connection_unavailable" },
-      "stripe offerings webhook: the connection store could not be read",
-    );
-    await reply.code(503).send({ error: "webhook-unavailable" });
-    return;
-  }
-  if (connection.kind === "not-found") {
-    await reply.code(404).send({ error: "not-found" });
-    return;
-  }
-  if (connection.kind !== "ok") {
-    request.log.warn(
-      { organizationId: connection.organizationId, outcome: "webhook_not_configured" },
-      "stripe offerings webhook: the connection has no usable webhook secret",
-    );
-    await reply.code(503).send({ error: "webhook-not-configured" });
-    return;
-  }
-  const { organizationId } = connection;
-
-  // ── Steps 3–6 — signature first, claim second (D-64) ─────────────────────
-  const settled = settleSignature(request, connection.webhookSecret);
-  const claim = await resolveCommerceClaim();
-
-  if (claim === "undetermined") {
-    request.log.warn(
-      settled.ok
-        ? { ...eventKeys(organizationId, settled.event), outcome: "license_undetermined" }
-        : { organizationId, outcome: "license_undetermined" },
-      "stripe offerings webhook held: the commerce licence could not be read",
-    );
-    await reply
-      .code(LICENSE_UNDETERMINED_STATUS)
-      .header("Retry-After", String(LICENSE_UNDETERMINED_RETRY_AFTER_SECONDS))
-      .send(LICENSE_UNDETERMINED_BODY);
-    return;
-  }
-
-  if (claim === "unclaimed") {
-    if (settled.ok) {
-      request.log.warn(
-        { ...eventKeys(organizationId, settled.event), outcome: "dropped_no_commerce_claim" },
-        "stripe offerings webhook event dropped: no commerce claim",
-      );
-      await reply.code(200).send({ received: true });
-      return;
-    }
-    const err = commerceDisabledResponse();
-    await reply.code(err.status).send(err.body);
-    return;
-  }
-
-  if (!settled.ok) {
-    if (settled.verifyThrew) {
-      request.log.warn(
-        { organizationId, outcome: "signature_invalid" },
-        "stripe offerings webhook signature verification failed",
-      );
-    }
-    await reply.code(settled.status).send(settled.body);
-    return;
-  }
-
-  await processVerifiedEvent(request, reply, connection, settled.event);
-};
-
-/** Steps 7–18, for an event signed with the connection's own secret. */
-async function processVerifiedEvent(
-  request: FastifyRequest,
-  reply: FastifyReply,
-  connection: Connection,
-  event: VerifiedEvent,
-): Promise<void> {
-  const { organizationId } = connection;
-  const keys = eventKeys(organizationId, event);
-  const ack = async (
-    level: "info" | "warn",
-    outcome: string,
-    message: string,
-    seen: boolean,
-  ): Promise<void> => {
-    if (seen) markSeenForOrganization(organizationId, event.id);
-    request.log[level]({ ...keys, outcome }, message);
-    await reply.code(200).send({ received: true });
-  };
-  const fail = async (status: number, error: string, outcome: string, message: string) => {
-    request.log.error({ ...keys, outcome }, message);
-    await reply.code(status).send({ error });
-  };
-
-  // ── Step 7 — W4 ──────────────────────────────────────────────────────────
-  if ((event.livemode === true) !== (connection.mode === "live")) {
-    await ack("warn", "livemode_mismatch", "stripe offerings webhook event dropped: livemode differs from the connection", false);
-    return;
-  }
-
-  // ── Step 8 — W5, the type ────────────────────────────────────────────────
-  const session = objectOf(objectOf(event.data)?.["object"]) as SessionObject | null;
-  if (!FULFILLING_EVENT_TYPES.has(event.type) || session?.object !== "checkout.session") {
-    await ack("info", "ignored_type", "stripe offerings webhook event ignored", false);
-    return;
-  }
-
-  // ── Steps 9–11 — W5, the hub's own record (A11) ──────────────────────────
-  let record: CheckoutSessionRecord | "unreadable" | null;
-  try {
-    record = await readCheckoutSessionRecord(session.id);
-  } catch {
-    await fail(503, "record-unavailable", "record_unavailable", "stripe offerings webhook: the session record could not be read");
-    return;
-  }
-  if (record === "unreadable") {
-    await fail(500, "record-unreadable", "record_unreadable", "stripe offerings webhook: the session record is unreadable");
-    return;
-  }
-  if (record === null) {
-    await ack("info", "unrecorded", "stripe offerings webhook: no hub record for the session", false);
-    return;
-  }
-
-  // ── Step 12 — W5, this Organization and this workspace (C2) ──────────────
-  const site = session.metadata?.["site"];
-  if (record.organizationId !== organizationId || typeof site !== "string" || site !== record.workspaceId) {
-    await ack("warn", "foreign_organization", "stripe offerings webhook: the session is not this Organization's", false);
-    return;
-  }
-
-  // ── Step 13 — the record's mode ──────────────────────────────────────────
-  if (record.mode !== connection.mode) {
-    await ack("warn", "livemode_mismatch", "stripe offerings webhook event dropped: the record's mode differs from the connection", false);
-    return;
-  }
-
-  // ── Step 14 — W10, per-Organization dedup ────────────────────────────────
-  if (hasSeenForOrganization(organizationId, event.id)) {
-    await ack("info", "duplicate", "stripe offerings webhook: duplicate event", false);
-    return;
-  }
-
-  // ── Step 15 — W6, payment ────────────────────────────────────────────────
-  if (
-    event.type === "checkout.session.completed" &&
-    session.payment_status !== "paid" &&
-    session.payment_status !== "no_payment_required"
-  ) {
-    await ack("info", "unpaid", "stripe offerings webhook: the session is not paid", true);
-    return;
-  }
-
-  // ── Steps 16–17 — W6, the paid Price is the record's (D5) ────────────────
-  let paidPriceIds: unknown[];
-  try {
-    const resolved = await stripeClientForOrganization(organizationId);
-    if (resolved.kind !== "ok") throw new Error("connection unusable");
-    const items = await resolved.client.checkout.sessions.listLineItems(record.sessionId, { limit: 2 });
-    paidPriceIds = items.data.map((item) => item.price?.id);
-  } catch {
-    await fail(503, "stripe-unavailable", "stripe_unavailable", "stripe offerings webhook: the line items could not be read");
-    return;
-  }
-  if (paidPriceIds.length !== 1 || paidPriceIds[0] !== record.priceId) {
-    await ack("warn", "offering_mismatch", "stripe offerings webhook: the paid Price is not the recorded one", true);
-    return;
-  }
-
-  // ── Step 18 — W7, one held lead per session (D6) ─────────────────────────
-  const metadata = session.metadata ?? {};
-  const terms = metadata[TERMS_STAMP_KEY];
-  let result: RouteLeadResult;
-  try {
-    result = await routeLead(
-      {
-        kind: "submit",
-        siteId: record.workspaceId,
-        source: "web",
-        email: typeof session.customer_details?.email === "string" ? session.customer_details.email : "",
-        payload: {
-          page: "checkout",
-          // The record's full key (G5) — never `metadata.ailk_offering`.
-          offering: record.lookupKey,
-          site: record.workspaceId,
-          amountTotal: typeof session.amount_total === "number" ? session.amount_total : null,
-          currency: typeof session.currency === "string" ? session.currency : null,
-          termsAccepted:
-            session.consent?.terms_of_service === "accepted" && typeof terms === "string" ? terms : null,
-        },
-      },
-      {
-        ip: request.ip,
-        userAgent: request.headers["user-agent"],
-        receivedAt: new Date().toISOString(),
-      },
-      { idempotencyKey: OFFERINGS_LEAD_KEY_PREFIX + record.sessionId, offeringsCheckout: true },
-    );
-  } catch {
-    await fail(503, "fulfilment-unavailable", "fulfilment_unavailable", "stripe offerings webhook: the lead could not be written");
-    return;
-  }
-
-  if (result.ok && result.persisted === "db") {
-    if (result.replayed === true) {
-      await ack("info", "already_fulfilled", "stripe offerings webhook: the session was already fulfilled", true);
-    } else {
-      await ack("info", "fulfilled", "stripe offerings webhook: the session was fulfilled", true);
-    }
-    return;
-  }
-  if (!result.ok && result.error.kind === "idempotency_conflict") {
-    await ack("info", "already_fulfilled", "stripe offerings webhook: the session was already fulfilled", true);
-    return;
-  }
-  if (!result.ok && result.error.kind === "invalid_input") {
-    await ack("warn", "unfulfillable", "stripe offerings webhook: the session has no storable email", true);
-    return;
-  }
-  await fail(503, "fulfilment-unavailable", "fulfilment_unavailable", "stripe offerings webhook: the lead could not be written");
-}