create-ailk 0.24.0 → 0.25.1

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

@@ -1,235 +0,0 @@
-/**
- * @file revalidation.ts
- * @description The signed webhook `apps/api` fires at the site's
- * `/api/revalidate` on publish and unpublish (#5851, roadmap D6). One POST of
- * `{ workspaceId, type, slug, locale }` to `CONTENT_REVALIDATE_URL`, signed
- * HMAC-SHA256 with `CONTENT_REVALIDATE_SECRET` over the base string
- * `v0:{timestamp}:{event}:{body}` (#5902) — the Slack shape
- * (`routes/slack/actions.ts:56`) with the event folded in, so neither a replay
- * outside the receiver's 5-minute window nor an in-flight event flip verifies.
- *
- * `type`, `slug` and `locale` are validated against bounded Zod shapes FIRST,
- * before the config check and before any outbound call; an invalid value
- * throws. That is the one way this function rejects, and it is a programmer
- * error rather than a delivery failure: the publish routes already hold these
- * values to the same shapes.
- *
- * Either var absent means "revalidation off": one `warn` and return. Both set
- * means three bounded attempts (500 ms then 2000 ms backoff, 10 s per-attempt
- * timeout — 32.5 s worst case), every attempt logged, and a final failure
- * LOGGED rather than thrown. Delivery never rejects, which is what lets the
- * publish path `await` it and still always complete.
- *
- * PII boundary: log lines carry only
- * `{ event, workspaceId, type, slug, locale, attempt/attempts, status/lastStatus, errName }`.
- * Never the secret, never the signature, never a response body, never page
- * content.
- *
- * The publish and unpublish handlers in `routes/workspaces/content.ts` call
- * this; the receiver is `apps/web/app/api/revalidate/route.ts`. This module
- * fixes the wire contract that receiver implements: method POST; the four-key
- * JSON body; headers `content-type: application/json`,
- * `x-ailk-revalidate-timestamp: <unix seconds>`,
- * `x-ailk-revalidate-event: publish | unpublish` and
- * `x-ailk-revalidate-signature: sha256=<lowercase hex>`. A receiver rejects a
- * timestamp more than 5 minutes from its own clock, then recomputes the HMAC
- * over `v0:{timestamp}:{event}:` + the RAW request body and compares in
- * constant time.
- */
-import { createHmac } from "node:crypto";
-
-import {
-  SCHEMA_ORG_TYPES,
-  SLUG_PATTERN,
-} from "@working-theory/content-adapters";
-import { createLogger } from "@working-theory/observability";
-import { localeSchema } from "@working-theory/validation";
-import { z } from "zod";
-
-import { config } from "../config/index.js";
-import { outboundFetch } from "../lib/outbound-http.js";
-
-// The environment is the api's own NODE_ENV, as the observability `logger`
-// singleton reads it. Omitted, createLogger assumes development and asks for a
-// pino-pretty transport a production install does not carry — a throw at load
-// that took the whole api down once content-write was enabled (#7502).
-const log = createLogger({
-  service: "revalidation",
-  environment: config.NODE_ENV,
-});
-
-const SIGNATURE_HEADER = "x-ailk-revalidate-signature";
-const EVENT_HEADER = "x-ailk-revalidate-event";
-const TIMESTAMP_HEADER = "x-ailk-revalidate-timestamp";
-
-/**
- * The bounds on the three fields that become the site's cache tags
- * (`content:{workspace}:{type}:{slug}:{locale}`). `type` and `slug` are exactly
- * the content routes' `addressParamsSchema` shapes and `locale` is the BCP-47
- * subset `resolveLocale` produces, so the publish path can never trip this
- * after its write has committed. None admits a `:`, which is what stops a
- * crafted `type` colliding with another page's tag (#6005 M3); the receiver
- * applies the same shapes.
- */
-const targetFieldsSchema = z.object({
-  type: z.enum(SCHEMA_ORG_TYPES),
-  slug: z.string().regex(SLUG_PATTERN),
-  locale: localeSchema,
-});
-
-/**
- * Backoff before attempt 2 and attempt 3. Three attempts total, no fourth:
- * 3 × the wrapper's 10 s timeout plus these two sleeps is 32.5 s worst case,
- * which fits inside the PRD's 60 s publish-to-live budget.
- */
-const RETRY_BACKOFF_MS = [500, 2000];
-const MAX_ATTEMPTS = RETRY_BACKOFF_MS.length + 1;
-
-export interface RevalidateTarget {
-  workspaceId: string;
-  type: string;
-  slug: string;
-  locale: string;
-}
-
-export interface RevalidateOptions {
-  event: "publish" | "unpublish";
-  /**
-   * Waits out one backoff. A test seam (#8418): the publish routes never pass
-   * it, so production always waits on the real timer. A test passes one that
-   * records the delay and resolves at once, so the retry schedule is asserted
-   * as scheduled rather than measured against a loaded runner's clock.
-   *
-   * @internal
-   */
-  sleep?: (ms: number) => Promise<void>;
-}
-
-function realSleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-/**
- * 429 and 5xx are worth another attempt. Every other non-2xx is terminal — a
- * 401 from a wrong secret or a 404 from a wrong path will not succeed on a
- * second try, and retrying it triples the log noise for a misconfiguration.
- */
-function isRetryableStatus(status: number): boolean {
-  return status === 429 || status >= 500;
-}
-
-/**
- * Tells the site to revalidate one piece of content. Resolves on success,
- * exhausted retries, or unconfigured, so an `await` in the publish path cannot
- * fail the publish it follows. Rejects only when `type`, `slug` or `locale` is
- * out of bounds, before anything is signed or sent.
- */
-export async function notifyRevalidate(
-  target: RevalidateTarget,
-  options: RevalidateOptions,
-): Promise<void> {
-  targetFieldsSchema.parse({
-    type: target.type,
-    slug: target.slug,
-    locale: target.locale,
-  });
-
-  const { sleep = realSleep } = options;
-  const url = config.CONTENT_REVALIDATE_URL;
-  const secret = config.CONTENT_REVALIDATE_SECRET;
-
-  // The PII-safe key set every line in this module carries.
-  const base = { event: options.event, ...target };
-
-  if (!url || !secret) {
-    // Signing with an empty key would be worse than skipping: every delivery
-    // would be rejected by the receiver with no local signal.
-    const reason = !url ? "url_unset" : "secret_unset";
-    log.warn({ ...base, reason }, "revalidate.skipped");
-    return;
-  }
-
-  // ONE serialization: this exact string is both signed and sent, so a
-  // key-order or whitespace drift between signer and sender is impossible by
-  // construction.
-  const body = JSON.stringify({
-    workspaceId: target.workspaceId,
-    type: target.type,
-    slug: target.slug,
-    locale: target.locale,
-  });
-  // Taken once per call and shared by every attempt: the retry schedule's
-  // 32.5 s worst case sits well inside the receiver's 5-minute tolerance.
-  const timestamp = String(Math.floor(Date.now() / 1000));
-  const signature = createHmac("sha256", secret)
-    .update(`v0:${timestamp}:${options.event}:${body}`, "utf8")
-    .digest("hex");
-
-  let attempt = 0;
-  let lastStatus: number | undefined;
-  let errName: string | undefined;
-
-  while (attempt < MAX_ATTEMPTS) {
-    attempt++;
-    let retryable: boolean;
-
-    try {
-      const res = await outboundFetch(url, {
-        method: "POST",
-        headers: {
-          "content-type": "application/json",
-          [TIMESTAMP_HEADER]: timestamp,
-          [EVENT_HEADER]: options.event,
-          [SIGNATURE_HEADER]: `sha256=${signature}`,
-        },
-        body,
-        // The SSRF gate is waived deliberately and narrowly: this URL comes
-        // from deployment environment, never from a request body or a
-        // database row. Leaving it on would break local development (the site
-        // is http://localhost:3000) and any single-host deployment.
-        allowPrivate: true,
-      });
-
-      if (res.ok) {
-        log.info({ ...base, attempt, status: res.status }, "revalidate.sent");
-        return;
-      }
-
-      lastStatus = res.status;
-      errName = undefined;
-      retryable = isRetryableStatus(res.status);
-    } catch (err) {
-      lastStatus = undefined;
-      errName = err instanceof Error ? err.name : "UnknownError";
-      retryable = true;
-    }
-
-    log.warn(
-      {
-        ...base,
-        attempt,
-        ...(lastStatus !== undefined && { status: lastStatus }),
-        ...(errName !== undefined && { errName }),
-      },
-      "revalidate.failed",
-    );
-
-    if (!retryable) break;
-
-    // Undefined on the last attempt — the schedule has one entry fewer than
-    // MAX_ATTEMPTS, so running out of backoffs IS the "no fourth attempt" bound.
-    const backoffMs = RETRY_BACKOFF_MS[attempt - 1];
-    if (backoffMs === undefined) break;
-    await sleep(backoffMs);
-  }
-
-  log.error(
-    {
-      ...base,
-      attempts: attempt,
-      ...(lastStatus !== undefined && { lastStatus }),
-      ...(errName !== undefined && { errName }),
-    },
-    "revalidate.failed",
-  );
-}

package/templates/apps/api/src/services/slack-notify.ts

@@ -1,291 +0,0 @@
-/**
- * @file slack-notify.ts
- * @description The operator's one free action per application (#4999): post
- * a new `ProjectListing` to the site's Slack channel with Approve/Reject
- * buttons, then update that SAME message in place once a decision lands.
- *
- * A thin `fetch` client over the Slack Web API — no Slack SDK (this
- * environment's contract). `AILK_SLACK_BOT_TOKEN`/`AILK_SLACK_CHANNEL_ID`
- * absent means Slack is off: both exports become no-ops that log
- * `slack-skipped` (id only) and never throw — a create must never fail
- * because Slack is unconfigured (or down), and a decision must always be
- * appliable even if the outcome can't be posted back.
- *
- * PII boundary: only `listingId` (plus a Slack API `error` code, never a
- * response body) ever reaches a log line here — never `founderEmail`,
- * `founderName`, `oneLiner`, `problem`, or any other applicant-authored text.
- * The Block Kit body sent TO Slack necessarily carries that text (that's the
- * point of the notification) — Slack, not this process's own logs, is the
- * destination for it.
- *
- * Security note (PR #4999 review): every applicant-authored string
- * (`oneLiner`/`problem`/`founderName`/`founderCompany`/`url`) is
- * submitted by an ANONYMOUS, unauthenticated caller (`POST
- * /v1/project-listings`) and lands in `mrkdwn` fields, which Slack parses for
- * `<!channel>`/`<!here>`/`<@U…>` mentions and `<url|label>` masked links — an
- * applicant could otherwise mass-ping the channel or mask a phishing link
- * behind innocuous-looking text. `escapeMrkdwn` (Slack's own documented
- * escaping: `&` -> `&amp;`, `<` -> `&lt;`, `>` -> `&gt;`, in that order) runs
- * on every such string, and on the Slack-supplied `decidedByName` too (lower
- * risk — only a member of the notified channel controls it — but the same
- * fix applies for defense in depth).
- *
- * Tenant binding (#7522): the posted actions block's `block_id` names the
- * listing's own workspace (`listing_decision:<workspaceId>`), and
- * `POST /v1/slack/actions` reads it back through `parseListingDecisionBlockId`
- * — the producer and the parser live side by side here so the format cannot
- * drift. Button `value`s stay the bare listing id.
- */
-import { zWorkspaceId } from "@working-theory/ids";
-import { logger } from "@working-theory/observability";
-
-import { config } from "../config/index.js";
-import { prisma } from "../lib/prisma.js";
-
-const SLACK_API_BASE = "https://slack.com/api";
-
-/** The subset of a ProjectListing this module ever renders into a Slack message. */
-export type ProjectListingSlackInfo = {
-  id: string;
-  /**
-   * Nullable since #5036 D1: every application field is nullable at rest so a
-   * half-filled draft is storable. A listing only reaches Slack once it has
-   * been SUBMITTED, so in practice these are set — the nulls are rendered as
-   * an em dash rather than asserted away, because a `!` here would turn a data
-   * surprise into a crash inside a notifier that is not allowed to throw.
-   */
-  name: string | null;
-  oneLiner: string | null;
-  problem: string | null;
-  url: string | null;
-  /** The six-rung product ladder that replaced `stage` (#5036 D2). */
-  product: string | null;
-  founderName: string;
-  founderCompany: string | null;
-};
-
-/** What an absent field renders as in a Slack field. */
-const ABSENT = "—";
-
-/** The Approve/Reject actions block's `block_id` stem — declared once (#7522 D1). */
-const LISTING_DECISION_BLOCK = "listing_decision";
-const LISTING_DECISION_BLOCK_PREFIX = `${LISTING_DECISION_BLOCK}:`;
-
-/**
- * The instant (Unix seconds, a whole UTC hour) from which every posted
- * Approve/Reject message names its workspace in `block_id` (#7522 D4). A
- * click that names no workspace is honoured only for a listing whose message
- * was posted before it (`slackTs` below it) or that has no message at all —
- * a legacy-shaped click on a newer message cannot be a real click.
- */
-export const LISTING_DECISION_BLOCK_NAMED_SINCE_SECONDS = 1791000000; // 2026-10-03T04:00:00Z
-
-/** The actions block's `block_id` for a listing in `workspaceId` (#7522 D1). */
-export function listingDecisionBlockId(workspaceId: string): string {
-  return `${LISTING_DECISION_BLOCK_PREFIX}${workspaceId}`;
-}
-
-export type ListingDecisionBlock =
-  | { kind: "legacy" }
-  | { kind: "named"; workspaceId: string }
-  | { kind: "invalid" };
-
-/**
- * Reads a clicked action's `block_id` back (#7522 D2). Absent or the bare
- * stem is the pre-#7522 message shape (`legacy`); the stem plus a valid
- * workspace id is `named`; anything else — a malformed suffix included — is
- * `invalid`, never `legacy`, so a bad workspace name cannot widen the scope.
- */
-export function parseListingDecisionBlockId(blockId: string | undefined): ListingDecisionBlock {
-  if (blockId === undefined || blockId === LISTING_DECISION_BLOCK) return { kind: "legacy" };
-  // The payload is JSON — a non-string `block_id` is possible on the wire.
-  if (typeof blockId !== "string" || !blockId.startsWith(LISTING_DECISION_BLOCK_PREFIX)) {
-    return { kind: "invalid" };
-  }
-  const workspaceId = blockId.slice(LISTING_DECISION_BLOCK_PREFIX.length);
-  return zWorkspaceId.safeParse(workspaceId).success
-    ? { kind: "named", workspaceId }
-    : { kind: "invalid" };
-}
-
-type SlackApiResult = {
-  ok: boolean;
-  error?: string;
-  ts?: string;
-  channel?: string;
-};
-
-/**
- * Slack's own documented `mrkdwn` escaping — `&` first, then `<`/`>` — so an
- * applicant-authored string can never open a `<!channel>`/`<@U…>` mention or
- * a `<url|label>` masked link inside a `mrkdwn` field.
- */
-function escapeMrkdwn(value: string): string {
-  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
-}
-
-async function callSlackApi(
-  token: string,
-  method: "chat.postMessage" | "chat.update",
-  body: Record<string, unknown>,
-): Promise<SlackApiResult> {
-  const res = await fetch(`${SLACK_API_BASE}/${method}`, {
-    method: "POST",
-    headers: {
-      "content-type": "application/json; charset=utf-8",
-      authorization: `Bearer ${token}`,
-    },
-    body: JSON.stringify(body),
-  });
-  return (await res.json()) as SlackApiResult;
-}
-
-/**
- * The header + info-fields blocks shared by the initial post and the decided
- * update. Every applicant-authored string is `escapeMrkdwn`-ed before it
- * enters a `mrkdwn` field (see the module doc's security note) — an
- * anonymous applicant's `oneLiner`/`problem`/`founderName`/
- * `founderCompany`/`url` can otherwise inject a Slack mention or a masked
- * phishing link. `listing.name` is NOT escaped here — it renders in the
- * `header` block as `plain_text`, which Slack never interprets as markup.
- */
-function infoBlocks(listing: ProjectListingSlackInfo): unknown[] {
-  const fields = [
-    { type: "mrkdwn", text: `*One-liner:*\n${escapeMrkdwn(listing.oneLiner ?? ABSENT)}` },
-    { type: "mrkdwn", text: `*Problem:*\n${escapeMrkdwn(listing.problem ?? ABSENT)}` },
-    { type: "mrkdwn", text: `*Product:*\n${escapeMrkdwn(listing.product ?? ABSENT)}` },
-    ...(listing.url ? [{ type: "mrkdwn", text: `*URL:*\n${escapeMrkdwn(listing.url)}` }] : []),
-    {
-      type: "mrkdwn",
-      text: `*Founder:*\n${escapeMrkdwn(listing.founderName)}${
-        listing.founderCompany ? ` (${escapeMrkdwn(listing.founderCompany)})` : ""
-      }`,
-    },
-  ];
-
-  return [
-    { type: "header", text: { type: "plain_text", text: listing.name ?? ABSENT, emoji: true } },
-    { type: "section", fields },
-  ];
-}
-
-/**
- * Posts the new application to Slack (`chat.postMessage`) with Approve/Reject
- * buttons carrying the listing id as `value`, in an actions block whose
- * `block_id` names the listing's workspace (#7522 D5). On success, stamps the
- * returned `channel`/`ts` onto the row so `updateListingMessage` can later
- * target the same message. No-op (logs `slack-skipped`) when Slack env is
- * absent; never throws — a Slack failure (missing config, API error, network
- * error) never fails the create that already succeeded.
- */
-export async function postListingApplication(
-  listing: ProjectListingSlackInfo & { workspaceId: string },
-): Promise<void> {
-  const token = config.AILK_SLACK_BOT_TOKEN;
-  const channel = config.AILK_SLACK_CHANNEL_ID;
-  if (!token || !channel) {
-    logger.info({ listingId: listing.id }, "slack-skipped");
-    return;
-  }
-
-  try {
-    const result = await callSlackApi(token, "chat.postMessage", {
-      channel,
-      // `text:` is mrkdwn-parsed and is what Slack shows in the notification
-      // fallback, so the applicant-authored name is escaped here even though
-      // the same value is safe unescaped in the `plain_text` header block
-      // (PR #5042 security review, finding 5).
-      text: `New project application: ${escapeMrkdwn(listing.name ?? ABSENT)}`,
-      blocks: [
-        ...infoBlocks(listing),
-        {
-          type: "actions",
-          block_id: listingDecisionBlockId(listing.workspaceId),
-          elements: [
-            {
-              type: "button",
-              text: { type: "plain_text", text: "Approve", emoji: true },
-              style: "primary",
-              action_id: "listing_approve",
-              value: listing.id,
-            },
-            {
-              type: "button",
-              text: { type: "plain_text", text: "Reject", emoji: true },
-              style: "danger",
-              action_id: "listing_reject",
-              value: listing.id,
-            },
-          ],
-        },
-      ],
-    });
-
-    if (!result.ok) {
-      logger.warn({ listingId: listing.id, slackError: result.error }, "slack post failed");
-      return;
-    }
-
-    await prisma.projectListing.update({
-      where: { id: listing.id },
-      data: { slackChannel: result.channel ?? channel, slackTs: result.ts ?? null },
-    });
-  } catch (err) {
-    logger.warn(
-      { listingId: listing.id, errName: err instanceof Error ? err.name : "UnknownError" },
-      "slack post threw",
-    );
-  }
-}
-
-/**
- * Replaces the posted message's actions block with an outcome line
- * (`chat.update`) — same header + info fields, Approve/Reject buttons gone.
- * No-op (logs `slack-skipped`) when Slack env is absent OR the row never
- * carries `slackChannel`/`slackTs` (the post was skipped or failed); never
- * throws — the decision has already been applied by the time this runs.
- */
-export async function updateListingMessage(
-  listing: ProjectListingSlackInfo & { slackChannel: string | null; slackTs: string | null },
-  /** The stored decision status (#5033 — `active` is the approved state). */
-  outcome: "active" | "rejected",
-  decidedByName: string,
-): Promise<void> {
-  const token = config.AILK_SLACK_BOT_TOKEN;
-  if (!token || !listing.slackChannel || !listing.slackTs) {
-    logger.info({ listingId: listing.id }, "slack-skipped");
-    return;
-  }
-
-  // decidedByName is Slack-supplied (payload.user.username/name) — escaped
-  // for the same reason applicant text is (see the module doc's security
-  // note), even though only a member of the notified channel controls it.
-  const safeDecidedByName = escapeMrkdwn(decidedByName);
-  // The operator-facing copy stays "Approved" — the vocabulary change is in
-  // the stored status, not in what a human reads in the channel.
-  const outcomeLine =
-    outcome === "active"
-      ? `:white_check_mark: Approved by ${safeDecidedByName}`
-      : `:x: Rejected by ${safeDecidedByName}`;
-
-  try {
-    const result = await callSlackApi(token, "chat.update", {
-      channel: listing.slackChannel,
-      ts: listing.slackTs,
-      text: `${escapeMrkdwn(listing.name ?? ABSENT)} — ${outcomeLine}`,
-      blocks: [
-        ...infoBlocks(listing),
-        { type: "section", text: { type: "mrkdwn", text: outcomeLine } },
-      ],
-    });
-
-    if (!result.ok) {
-      logger.warn({ listingId: listing.id, slackError: result.error }, "slack update failed");
-    }
-  } catch (err) {
-    logger.warn(
-      { listingId: listing.id, errName: err instanceof Error ? err.name : "UnknownError" },
-      "slack update threw",
-    );
-  }
-}