create-ailk 0.27.0 → 0.28.0

package/templates/apps/web/lib/bot-check.ts

@@ -0,0 +1,138 @@
+/**
+ * The spoke edge's one bot check (#9889, #9255, spec
+ * docs/specs/9255-an-edge-bot-challenge-in-spec.md).
+ *
+ * Vercel BotID's verdict on a public write, asked on this site's own server
+ * before the hub is called: by the relay for its checked pairs (`relay.ts`'s
+ * `BOT_CHECKED_ROUTES`) and by each public lead, flow and checkout Server
+ * Action immediately before its hub call. MCP tools and key-bearing API calls
+ * never pass through a site, so they are never challenged.
+ *
+ * It fails closed (#9889 D3): only `isBot === false` passes. A bot is `bot`;
+ * a check that throws, answers no boolean or takes over 5 seconds is
+ * `unavailable`. It runs only on Vercel (`VERCEL=1`); `AILK_BOT_CHECK=off`
+ * turns every check off and `AILK_BOOKING_BOT_CHECK=off` the booking's alone.
+ *
+ * NO SECRET IS LOGGED. A refusal logs `{ path, outcome }` and, for a failed
+ * check, the error's name — never its message.
+ */
+import { checkBotId } from "botid/server";
+
+export type BotCheckScope = "write" | "booking";
+export type BotCheckOutcome = "pass" | "bot" | "unavailable";
+
+/**
+ * BotID's browser `protect` list: every same-origin POST. A Server Action
+ * posts to the URL of the page it was submitted from (the footer's newsletter
+ * signup is on every page), and a checked request the client did not protect
+ * carries no challenge header and is refused as a bot.
+ */
+export const BOT_CLIENT_PROTECT = Object.freeze([
+  Object.freeze({ path: "/*", method: "POST" }),
+]) as { path: string; method: string }[];
+
+/** The longest a check waits for a verdict; the library's own fetch has no bound. */
+const BOT_CHECK_TIMEOUT_MS = 5_000;
+
+/** Unset, empty or any other value leaves a check on, so a typo fails toward protection. */
+function isOff(value: string | undefined): boolean {
+  return value?.trim().toLowerCase() === "off";
+}
+
+function switchedOff(scope: BotCheckScope): boolean {
+  return (
+    isOff(process.env.AILK_BOT_CHECK) ||
+    (scope === "booking" && isOff(process.env.AILK_BOOKING_BOT_CHECK))
+  );
+}
+
+/** True when the check runs for `scope`. Read on every call, never cached. */
+export function botCheckOn(scope: BotCheckScope): boolean {
+  return process.env.VERCEL === "1" && !switchedOff(scope);
+}
+
+let warnedBotCheckInactive = false;
+
+/**
+ * Called when the check is off. Off Vercel it cannot run (#9889 D2): a
+ * production site whose switch is not `off` logs that once per process, so an
+ * owner who believes it is on can find out. It never refuses.
+ */
+function warnBotCheckInactiveOnce(scope: BotCheckScope): void {
+  if (warnedBotCheckInactive || process.env.NODE_ENV !== "production") return;
+  if (switchedOff(scope)) return;
+  warnedBotCheckInactive = true;
+  console.warn("[relay] booking bot check inactive", {
+    outcome: "not-on-vercel",
+  });
+}
+
+function namedError(name: string): Error {
+  const err = new Error(name);
+  err.name = name;
+  return err;
+}
+
+/**
+ * BotID's verdict on this request: `true` for a bot, `false` for a human.
+ * Throws `TimeoutError` past `BOT_CHECK_TIMEOUT_MS` and `InvalidVerdictError`
+ * when `isBot` is not a boolean, as `checkBotId` returns for an error answer
+ * from Vercel.
+ */
+async function isBotVerdict(): Promise<boolean> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const verdict = await Promise.race([
+      checkBotId(),
+      new Promise<never>((_resolve, reject) => {
+        timer = setTimeout(
+          () => reject(namedError("TimeoutError")),
+          BOT_CHECK_TIMEOUT_MS,
+        );
+      }),
+    ]);
+    const isBot = (verdict as { isBot?: unknown } | undefined)?.isBot;
+    if (typeof isBot !== "boolean") throw namedError("InvalidVerdictError");
+    return isBot;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * The check for one write. `source` names the log prefix and `target` the
+ * relayed path or the action's name — never a field value. Never throws.
+ */
+export async function runBotCheck({
+  source,
+  target,
+  scope,
+}: {
+  source: string;
+  target: string;
+  scope: BotCheckScope;
+}): Promise<BotCheckOutcome> {
+  if (!botCheckOn(scope)) {
+    warnBotCheckInactiveOnce(scope);
+    return "pass";
+  }
+  let isBot: boolean;
+  try {
+    isBot = await isBotVerdict();
+  } catch (err) {
+    console.error(`[${source}] bot check failed`, {
+      path: target,
+      outcome: "bot-check-failed",
+      error: err instanceof Error ? err.name : "unknown",
+    });
+    return "unavailable";
+  }
+  if (isBot) {
+    console.warn(`[${source}] bot refused`, {
+      path: target,
+      outcome: "bot-detected",
+    });
+    return "bot";
+  }
+  return "pass";
+}

package/templates/apps/web/lib/consent-visitor.ts

@@ -10,9 +10,43 @@
  *
  * httpOnly, `Secure` in production, `SameSite=Lax`, path `/`, one year — a
  * Server Action can read and mint it; client script never sees its value.
+ *
+ * The cookie is `<uuid>.<sig>`, signed by this site (#8556, spec
+ * docs/specs/9965-sweep-a-trust-or-authz-spec.md D7): `sig` is the base64url
+ * HMAC-SHA256 of the UUID under a subkey derived from the site's own secret
+ * with a fixed label, so that secret is never used raw for a second purpose.
+ * A read returns the bare UUID only when the signature verifies, so a visitor
+ * id the browser made up is never forwarded as `x-ailk-consent-visitor`.
+ *
+ * The secret is one the site already holds, taken in this fixed order
+ * (operator decision on #9965, option (b)):
+ *
+ *   1. `BETTER_AUTH_SECRET`, via `resolveSecret()` — a hub, or any site that
+ *      builds Better Auth;
+ *   2. `AILK_HUB_SESSION_SECRET` — a spoke that signs in through its hub;
+ *   3. `AILK_SPOKE_KEY` — any other spoke;
+ *
+ * each of 2 and 3 only at 32 characters or more once trimmed (the floor
+ * `hub-session/config.ts` sets; a minted spoke key is longer), so a short
+ * value a visitor could brute-force from their own cookie is never a key;
+ *   4. otherwise `resolveSecret()` again, which is the development fallback
+ *      outside production and THROWS in a production process.
+ *
+ * So a production spoke, which create-ailk deliberately gives no
+ * `BETTER_AUTH_SECRET`, still signs and verifies its own ids. With none of
+ * the three set a read is `undefined` and a mint throws, so nothing unsigned
+ * is ever written or forwarded (fail closed). A verifier recomputes the
+ * signature under its own secret, so it accepts only what its own site signed.
  */
 
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+import { resolveSecret } from "./auth-secret";
+
 const CONSENT_VISITOR_COOKIE_NAME = "ailk-vid";
+const SIGNING_LABEL = "ailk-consent-visitor-v1";
+/** The shortest spoke-held secret this module signs with. */
+const MIN_FALLBACK_SECRET_LENGTH = 32;
 const ONE_YEAR_SECONDS = 60 * 60 * 24 * 365;
 
 const V4_UUID =
@@ -23,6 +57,42 @@ export function isValidConsentVisitorId(value: string): boolean {
   return V4_UUID.test(value);
 }
 
+/** The site's own signing secret, in the order the header documents. */
+function signingSecret(): string {
+  if (process.env.BETTER_AUTH_SECRET) return resolveSecret();
+  const fallback = [process.env.AILK_HUB_SESSION_SECRET, process.env.AILK_SPOKE_KEY]
+    .map((value) => value?.trim() ?? "")
+    .find((value) => value.length >= MIN_FALLBACK_SECRET_LENGTH);
+  return fallback ?? resolveSecret();
+}
+
+/** The base64url signature of `id`. Throws when no secret is set in production. */
+function sign(id: string): string {
+  const subkey = createHmac("sha256", signingSecret()).update(SIGNING_LABEL).digest();
+  return createHmac("sha256", subkey).update(id).digest("base64url");
+}
+
+/**
+ * The UUID a signed cookie value carries, or `undefined` for a bare UUID, a
+ * bad or wrong-length signature, or a secret that cannot be resolved.
+ */
+function verifiedId(value: string): string | undefined {
+  const dot = value.indexOf(".");
+  if (dot === -1) return undefined;
+  const id = value.slice(0, dot);
+  if (!isValidConsentVisitorId(id)) return undefined;
+  let expected: Buffer;
+  try {
+    expected = Buffer.from(sign(id));
+  } catch {
+    return undefined;
+  }
+  const presented = Buffer.from(value.slice(dot + 1));
+  // timingSafeEqual throws on unequal lengths, so that is checked first.
+  if (presented.length !== expected.length) return undefined;
+  return timingSafeEqual(presented, expected) ? id : undefined;
+}
+
 /** The subset of Next's `cookies()` jar a read needs. */
 export interface ConsentVisitorCookieReader {
   get(name: string): { value: string } | undefined;
@@ -50,16 +120,21 @@ export interface ConsentVisitorCookieWriter extends ConsentVisitorCookieReader {
   set(name: string, value: string, options: ConsentVisitorCookieOptions): void;
 }
 
-/** The existing visitor id, or `undefined` with none set or an invalid value. */
+/**
+ * The existing visitor id, or `undefined` with none set or a value whose
+ * signature does not verify.
+ */
 export function readConsentVisitor(
   cookies: ConsentVisitorCookieReader,
 ): string | undefined {
   const value = cookies.get(CONSENT_VISITOR_COOKIE_NAME)?.value;
-  return value !== undefined && isValidConsentVisitorId(value) ? value : undefined;
+  return value !== undefined ? verifiedId(value) : undefined;
 }
 
 /**
- * The visitor id, minting and setting a fresh one when absent or invalid.
+ * The visitor id, minting and setting a fresh signed one when absent or when
+ * the stored value does not verify (a cookie minted before signing included).
+ * Throws, setting nothing, when a production site holds none of the secrets.
  * Server Actions only — Next refuses a cookie write outside one (the same
  * posture `hub-session/reseal.ts` documents).
  */
@@ -67,7 +142,7 @@ export function ensureConsentVisitor(cookies: ConsentVisitorCookieWriter): strin
   const existing = readConsentVisitor(cookies);
   if (existing !== undefined) return existing;
   const id = crypto.randomUUID();
-  cookies.set(CONSENT_VISITOR_COOKIE_NAME, id, {
+  cookies.set(CONSENT_VISITOR_COOKIE_NAME, `${id}.${sign(id)}`, {
     httpOnly: true,
     secure: process.env.NODE_ENV === "production",
     sameSite: "lax",
@@ -85,7 +160,7 @@ export function consentVisitorHeader(id: string): Record<string, string> {
 /**
  * The visitor id out of a raw `Cookie:` header string (the relay's own
  * `Request`, which carries no Next `cookies()` jar). `undefined` with no
- * header, no matching cookie, or a value that fails the UUID shape.
+ * header, no matching cookie, or a value whose signature does not verify.
  */
 export function readConsentVisitorFromCookieHeader(
   header: string | null | undefined,
@@ -96,8 +171,7 @@ export function readConsentVisitorFromCookieHeader(
     if (eq === -1) continue;
     const name = part.slice(0, eq).trim();
     if (name !== CONSENT_VISITOR_COOKIE_NAME) continue;
-    const value = part.slice(eq + 1).trim();
-    return isValidConsentVisitorId(value) ? value : undefined;
+    return verifiedId(part.slice(eq + 1).trim());
   }
   return undefined;
 }

package/templates/apps/web/lib/deck-page.ts

@@ -42,11 +42,14 @@ export const DECK_ROUTES = [
   "/faq",
   "/launch-service",
   "/pricing",
+  "/pricing/:slug",
   "/privacy",
   "/projects",
   "/projects/:slug",
   "/purchase-policy",
   "/reports",
+  "/templates",
+  "/templates/:slug",
   "/terms",
   "/thanks/:slug",
   "/working-agreement",
@@ -65,7 +68,7 @@ function routeSegments(route: string): string[] {
   return route.split("/").filter((segment) => segment.length > 0);
 }
 
-function matchesRoute(routeDef: string, pathSegments: readonly string[]): boolean {
+export function matchesRoute(routeDef: string, pathSegments: readonly string[]): boolean {
   const defSegments = routeSegments(routeDef);
   if (defSegments.length !== pathSegments.length) return false;
   return defSegments.every(
@@ -74,7 +77,7 @@ function matchesRoute(routeDef: string, pathSegments: readonly string[]): boolea
 }
 
 /** The type and slug a matched routes-map row resolves to for this request. */
-function resolveTypeAndSlug(
+export function resolveTypeAndSlug(
   row: RouteRow,
   routeDef: string,
   pathSegments: readonly string[],
@@ -94,7 +97,7 @@ function resolveTypeAndSlug(
 }
 
 /** Whether a routes-map row at this exact route is always scaffolded (never absent from a site). */
-function isAlwaysScaffolded(path: string): boolean {
+export function isAlwaysScaffolded(path: string): boolean {
   const row = ROUTES.find((candidate) => candidate.route === path);
   return row !== undefined && row.gateable !== true && row.module === "marketing";
 }

package/templates/apps/web/lib/docs-index.ts

@@ -0,0 +1,100 @@
+// docs-index.ts — the docs list `/sitemap.xml` and `/llms.txt` read (#10041 D8).
+//
+// A base file: it reads the docs directory itself rather than `docsSource`,
+// which only a docs-blog site carries, so the sitemap and llms routes stay in
+// the Free template and list the docs on any site that has them. It imports
+// no docs-blog owned file (a relative import of one would drop it, and every
+// file importing it, from the Free template).
+//
+// Default locale only: the docs exist in one locale (`source.config.ts` reads
+// `content/en/docs`).
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { parse as parseYaml } from "yaml";
+
+import { DOCS_PATH } from "./docs-path";
+
+export interface DocsIndexPage {
+  url: string;
+  title: string;
+  description?: string;
+}
+
+/** The two content-adapter types the docs route reads under the database adapter. */
+const DOCS_TYPES = new Set(["DocsList", "DocsDetail"]);
+
+export function isDocsType(type: string): boolean {
+  return DOCS_TYPES.has(type);
+}
+
+/** An adapter docs row's URL: the index at `DOCS_PATH`, a doc under it. */
+export function adapterDocsUrl(type: string, slug: string): string {
+  return type === "DocsList" || slug === "index"
+    ? DOCS_PATH
+    : `${DOCS_PATH}/${slug}`;
+}
+
+function frontmatterOf(raw: string): Record<string, unknown> | null {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(raw);
+  if (!match) return null;
+  const parsed: unknown = parseYaml(match[1]!);
+  return parsed && typeof parsed === "object"
+    ? (parsed as Record<string, unknown>)
+    : null;
+}
+
+/**
+ * Fumadocs' slug rule: the path segments without the extension, a trailing
+ * `index` dropped, a `(group)` segment dropped.
+ */
+function urlFor(segments: string[]): string {
+  const slugs = segments.filter((s) => !/^\(.+\)$/.test(s));
+  if (slugs.at(-1) === "index") slugs.pop();
+  return slugs.length === 0 ? DOCS_PATH : `${DOCS_PATH}/${slugs.join("/")}`;
+}
+
+function walk(dir: string, segments: string[], out: DocsIndexPage[]): void {
+  const entries = readdirSync(dir, { withFileTypes: true }).sort((a, b) =>
+    a.name.localeCompare(b.name),
+  );
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      walk(join(dir, entry.name), [...segments, entry.name], out);
+      continue;
+    }
+    if (!entry.isFile() || !entry.name.endsWith(".mdx")) continue;
+    const data = frontmatterOf(readFileSync(join(dir, entry.name), "utf8"));
+    if (!data || typeof data.title !== "string" || data.title === "") continue;
+    out.push({
+      url: urlFor([...segments, entry.name.slice(0, -".mdx".length)]),
+      title: data.title,
+      ...(typeof data.description === "string" && data.description !== ""
+        ? { description: data.description }
+        : {}),
+    });
+  }
+}
+
+/**
+ * Every titled `*.mdx` page under `dir` (default: this app's
+ * `content/<default locale>/docs`), at the docs' public path. An absent
+ * directory — every Free site — is `[]`; a page with no `title` is skipped.
+ */
+export function listDocsPages(
+  dir: string = join(
+    process.cwd(),
+    "content",
+    process.env.NEXT_PUBLIC_DEFAULT_LOCALE ?? "en",
+    "docs",
+  ),
+): DocsIndexPage[] {
+  const pages: DocsIndexPage[] = [];
+  try {
+    walk(dir, [], pages);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw error;
+  }
+  return pages;
+}

package/templates/apps/web/lib/docs-path.ts

@@ -0,0 +1,94 @@
+// docs-path.ts — where the docs live (#10041 D2).
+//
+// A site sets `docsPath` in `content/_site.mdx` (e.g. `/working-theory/docs`);
+// `next.config.mjs` parses it at build and bakes it into
+// `NEXT_PUBLIC_AILK_DOCS_PATH`. The docs route itself never moves — it stays
+// at `app/[locale]/docs/` (`DOCS_ROUTE`) — and the middleware maps the public
+// path onto it. Every surface that names a docs URL reads `DOCS_PATH` here.
+//
+// Edge-safe and client-safe: this file imports nothing at runtime (the
+// `NavItem` import is type-only), so the middleware and the client signed-in
+// nav can both read it. It is a base file: it must never import a docs-blog
+// owned file, or it would leave the Free template.
+import type { NavItem } from "@working-theory/ui";
+
+/** The internal docs route — the directory under `app/[locale]/`. Always `/docs`. */
+export const DOCS_ROUTE = "/docs";
+
+/** The docs' public base: the site's `docsPath`, or `/docs` when it sets none. */
+export const DOCS_PATH: string =
+  process.env.NEXT_PUBLIC_AILK_DOCS_PATH || DOCS_ROUTE;
+
+/**
+ * `href` at the internal docs route — `/docs`, or starting `/docs/`, `/docs?`
+ * or `/docs#` — with that prefix replaced by `DOCS_PATH`. Anything else
+ * (absolute URLs, `/docsets`, a locale-prefixed path) is returned unchanged.
+ * The identity on a site with no `docsPath`.
+ */
+export function toPublicDocsHref(href: string): string {
+  if (DOCS_PATH === DOCS_ROUTE) return href;
+  const rest = href.slice(DOCS_ROUTE.length);
+  if (href.startsWith(DOCS_ROUTE) && (rest === "" || /^[/?#]/.test(rest))) {
+    return DOCS_PATH + rest;
+  }
+  return href;
+}
+
+/**
+ * A locale-less pathname at or under `DOCS_PATH`, mapped onto the internal
+ * route (`/docs` + the rest); `null` for anything else, and always `null` on a
+ * site with no `docsPath`.
+ */
+export function toInternalDocsPath(bare: string): string | null {
+  if (DOCS_PATH === DOCS_ROUTE) return null;
+  if (bare === DOCS_PATH) return DOCS_ROUTE;
+  if (bare.startsWith(`${DOCS_PATH}/`)) {
+    return DOCS_ROUTE + bare.slice(DOCS_PATH.length);
+  }
+  return null;
+}
+
+type NavFlyout = NonNullable<NavItem["flyout"]>;
+
+function mapPath<T extends { path: string }>(entry: T): T {
+  return { ...entry, path: toPublicDocsHref(entry.path) };
+}
+
+function mapFlyout(flyout: NavFlyout): NavFlyout {
+  return {
+    ...flyout,
+    features: flyout.features.map(mapPath),
+    ...(flyout.groups
+      ? {
+          groups: flyout.groups.map((group) => ({
+            ...group,
+            items: group.items.map(mapPath),
+          })),
+        }
+      : {}),
+    actions: flyout.actions.map(mapPath),
+  };
+}
+
+/**
+ * Copies of the nav items with every docs path mapped onto `DOCS_PATH` — the
+ * item's own `path` and each flyout feature, group item and action. Every
+ * other field (icons are functions) is carried by reference.
+ */
+export function withPublicDocsPaths(items: NavItem[]): NavItem[] {
+  return items.map((item) => ({
+    ...item,
+    ...(item.path !== undefined ? { path: toPublicDocsHref(item.path) } : {}),
+    ...(item.flyout ? { flyout: mapFlyout(item.flyout) } : {}),
+  }));
+}
+
+/** Copies of the footer columns with every item's docs path mapped onto `DOCS_PATH`. */
+export function withPublicDocsColumns<C extends { items: { path: string }[] }>(
+  columns: C[],
+): C[] {
+  return columns.map((column) => ({
+    ...column,
+    items: column.items.map(mapPath),
+  }));
+}