create-ailk 0.14.0 → 0.16.0

package/templates/apps/web/lib/hub-session/seal.ts

@@ -0,0 +1,82 @@
+/**
+ * Sealed cookie values for the spoke's hub session (#7894 D7).
+ *
+ * AES-256-GCM with a fresh 12-byte IV per seal. The key is HKDF-SHA256 of
+ * `AILK_HUB_SESSION_SECRET` with one info string per cookie purpose, so the
+ * session cookie and the flow cookie never share a key, and the cookie's NAME
+ * is the additional authenticated data, so a value sealed for one cookie never
+ * opens as the other. The key never derives from the client secret: a leaked
+ * client secret forges no spoke session.
+ *
+ * Wire form: base64url(iv ‖ tag ‖ ciphertext). Anything that does not open —
+ * a wrong key, a wrong name, a truncated or altered value — reads as `null`,
+ * never a throw. Node `crypto` only; no dependency.
+ */
+
+import {
+  createCipheriv,
+  createDecipheriv,
+  hkdfSync,
+  randomBytes,
+} from "node:crypto";
+
+/** The two things this module seals, each under its own derived key. */
+export type SealPurpose = "session" | "flow";
+
+const INFO: Record<SealPurpose, string> = {
+  session: "ailk-hub-session/v1",
+  flow: "ailk-hub-flow/v1",
+};
+
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+
+function deriveKey(secret: string, purpose: SealPurpose): Buffer {
+  return Buffer.from(
+    hkdfSync("sha256", secret, Buffer.alloc(0), INFO[purpose], 32),
+  );
+}
+
+/** `value` as JSON, sealed for the cookie `name`. */
+export function seal(
+  value: unknown,
+  secret: string,
+  purpose: SealPurpose,
+  name: string,
+): string {
+  const iv = randomBytes(IV_BYTES);
+  const cipher = createCipheriv("aes-256-gcm", deriveKey(secret, purpose), iv);
+  cipher.setAAD(Buffer.from(name, "utf8"));
+  const body = Buffer.concat([
+    cipher.update(JSON.stringify(value), "utf8"),
+    cipher.final(),
+  ]);
+  return Buffer.concat([iv, cipher.getAuthTag(), body]).toString("base64url");
+}
+
+/** The JSON value `sealed` holds for the cookie `name`, or `null` when it does not open. */
+export function unseal(
+  sealed: string,
+  secret: string,
+  purpose: SealPurpose,
+  name: string,
+): unknown {
+  try {
+    const raw = Buffer.from(sealed, "base64url");
+    if (raw.length <= IV_BYTES + TAG_BYTES) return null;
+    const decipher = createDecipheriv(
+      "aes-256-gcm",
+      deriveKey(secret, purpose),
+      raw.subarray(0, IV_BYTES),
+    );
+    decipher.setAAD(Buffer.from(name, "utf8"));
+    decipher.setAuthTag(raw.subarray(IV_BYTES, IV_BYTES + TAG_BYTES));
+    const text = Buffer.concat([
+      decipher.update(raw.subarray(IV_BYTES + TAG_BYTES)),
+      decipher.final(),
+    ]).toString("utf8");
+    return JSON.parse(text) as unknown;
+  } catch {
+    return null;
+  }
+}

package/templates/apps/web/lib/hub-session/session.ts

@@ -0,0 +1,180 @@
+/**
+ * The spoke's hub session (#7894 D7, D12, D13) — read, forwarded, never stored.
+ *
+ * A spoke that signs in through its hub has no database: after the callback
+ * route exchanges a code, the hub-issued credential and the person it names
+ * live in ONE sealed, `HttpOnly` cookie. This module is everything that reads
+ * it:
+ *
+ *   - `readHubSession(headers)` — the web seam's `readSession` on a hub-mode
+ *     spoke: unseals the cookie from the `Cookie` header, no network. Expired,
+ *     unreadable or sealed under another key ⇒ `null`.
+ *   - `hubSessionInit()` — what `forwardedCookieInit()` returns on such a
+ *     spoke: the credential as `Authorization: Bearer`, the ONE request-init
+ *     re-target the account area reads the hub through (D12). The api-client
+ *     adds the spoke key itself; the hub admits the credential only beside it.
+ *   - `hubSessionBuyer(request)` — a customer the hub vouches for at buy time
+ *     (D13): read live from `GET /v1/hub-sign-in/me`, never from the cookie.
+ *
+ * Nothing here logs a credential, a cookie value or an email.
+ */
+
+import { hubSignIn } from "@working-theory/api-client";
+import { headers as requestHeaders } from "next/headers";
+
+import { resolveNextPath } from "../next-path";
+
+import { type HubSessionConfig, hubSessionConfig } from "./config";
+import { unseal } from "./seal";
+
+/** The session cookie: `__Host-` on an https site, plain on a loopback one. */
+export function sessionCookieName(config: Pick<HubSessionConfig, "secure">): string {
+  return config.secure ? "__Host-ailk-hub-session" : "ailk-hub-session";
+}
+
+/** The flow cookie that carries state, verifier and `next` across the hub hop. */
+export function flowCookieName(config: Pick<HubSessionConfig, "secure">): string {
+  return config.secure ? "__Host-ailk-hub-flow" : "ailk-hub-flow";
+}
+
+/** The person a hub session names — the fields the account area reads. */
+export interface HubSessionUser {
+  name: string | null;
+  email: string;
+  emailVerified: boolean;
+  createdAt: string;
+}
+
+/** What the session cookie holds (sealed). */
+export interface HubSessionPayload {
+  v: 1;
+  accessToken: string;
+  /** Epoch milliseconds; the cookie's own `Max-Age` ends at the same time. */
+  expiresAt: number;
+  user: HubSessionUser;
+}
+
+/** The value of cookie `name` in a `Cookie` header, or `undefined`. */
+export function readCookie(header: string | null, name: string): string | undefined {
+  if (header === null) return undefined;
+  for (const part of header.split(";")) {
+    const at = part.indexOf("=");
+    if (at === -1) continue;
+    if (part.slice(0, at).trim() === name) return part.slice(at + 1).trim();
+  }
+  return undefined;
+}
+
+/**
+ * A `Set-Cookie` value for one of this module's cookies — always `HttpOnly`,
+ * `SameSite=Lax` (the hub's top-level redirect back must carry the flow
+ * cookie) and `Path=/`; `Secure` on an https site. `maxAge` 0 clears it.
+ */
+export function cookieHeader(
+  name: string,
+  value: string,
+  maxAge: number,
+  config: Pick<HubSessionConfig, "secure">,
+): string {
+  return [
+    `${name}=${value}`,
+    "Path=/",
+    "HttpOnly",
+    "SameSite=Lax",
+    `Max-Age=${Math.max(0, Math.floor(maxAge))}`,
+    ...(config.secure ? ["Secure"] : []),
+  ].join("; ");
+}
+
+function isPayload(value: unknown): value is HubSessionPayload {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  const user = v["user"] as Record<string, unknown> | null | undefined;
+  return (
+    v["v"] === 1 &&
+    typeof v["accessToken"] === "string" &&
+    typeof v["expiresAt"] === "number" &&
+    typeof user === "object" &&
+    user !== null &&
+    typeof user["email"] === "string" &&
+    typeof user["emailVerified"] === "boolean" &&
+    (user["name"] === null || typeof user["name"] === "string") &&
+    typeof user["createdAt"] === "string"
+  );
+}
+
+/** The sealed session in `headers`, or `null` — not configured, absent, expired or unreadable. */
+export function readHubSessionPayload(headers: Headers): HubSessionPayload | null {
+  const config = hubSessionConfig();
+  if (config === null) return null;
+  const name = sessionCookieName(config);
+  const sealed = readCookie(headers.get("cookie"), name);
+  if (sealed === undefined || sealed === "") return null;
+  const value = unseal(sealed, config.sessionSecret, "session", name);
+  if (!isPayload(value) || value.expiresAt <= Date.now()) return null;
+  return value;
+}
+
+/** The web seam's `readSession` on a hub-mode spoke: the person, or `null`. */
+export function readHubSession(
+  headers: Headers,
+): Promise<{ user: HubSessionUser } | null> {
+  const payload = readHubSessionPayload(headers);
+  return Promise.resolve(payload === null ? null : { user: payload.user });
+}
+
+/**
+ * `forwardedCookieInit()` on a hub-mode spoke (D12): the credential as a
+ * Bearer header signed in, no header at all signed out. Never the visitor's
+ * cookie — the hub has no session for it.
+ */
+export async function hubSessionInit(): Promise<{ headers: Record<string, string> }> {
+  const payload = readHubSessionPayload(await requestHeaders());
+  return payload === null
+    ? { headers: {} }
+    : { headers: { authorization: `Bearer ${payload.accessToken}` } };
+}
+
+/**
+ * The customer the hub vouches for, for a spoke's buy route (D13): read live
+ * from `GET /v1/hub-sign-in/me` with the person's credential (the api-client
+ * adds the spoke key). `null` with no session, when the hub refuses the
+ * credential (a revoked one reads as signed out here), when it names no
+ * customer, or on any failure — a buyer is never taken from the cookie.
+ */
+export async function hubSessionBuyer(
+  request: Request,
+): Promise<{ customerId: string } | null> {
+  const payload = readHubSessionPayload(request.headers);
+  if (payload === null) return null;
+  try {
+    const res = await hubSignIn.me({
+      headers: { authorization: `Bearer ${payload.accessToken}` },
+    });
+    if (!res.ok) return null;
+    const customerId = res.body.billingCustomerId;
+    return typeof customerId === "string" && customerId !== ""
+      ? { customerId }
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Where to land after signing in, when `next` is missing or refused. */
+export const HUB_SESSION_FALLBACK_PATH = "/account";
+
+/**
+ * The post-sign-in path for `raw`: `resolveNextPath`'s same-origin rule,
+ * printable ASCII only (it becomes a `Location` header), and never a path
+ * that resolves under `/api` — dot segments included — so a sign-in lands on
+ * a page and never re-enters a route handler.
+ */
+export function hubNextPath(raw: unknown): string {
+  const next = resolveNextPath(raw, HUB_SESSION_FALLBACK_PATH);
+  if (!/^[\x21-\x7e]+$/.test(next)) return HUB_SESSION_FALLBACK_PATH;
+  const path = new URL(next, "http://site.invalid").pathname;
+  return path === "/api" || path.startsWith("/api/")
+    ? HUB_SESSION_FALLBACK_PATH
+    : next;
+}

package/templates/apps/web/lib/hub-session/sign-in-gate.tsx

@@ -0,0 +1,79 @@
+/**
+ * HubSignInGate — the signed-out account gate of a spoke that signs in
+ * through its hub (#7894 D10).
+ *
+ * A Server Component, rendered by the `(authed)` layout through the generated
+ * gate seam (`signed-out-gate.generated.tsx`, its `signIn: "hub"` render). It
+ * offers ONE action: a link to this site's own `/api/hub-session/sign-in`,
+ * carrying the requested path as `next`, which starts the hub sign-in. The
+ * link is a plain anchor (the `Link` primitive), so nothing prefetches the
+ * route and starts a flow the visitor did not ask for.
+ *
+ * Not configured (`hubSessionConfig()` is `null`: a client id, secret or
+ * session secret missing), it renders the account area's existing "sign-in
+ * isn't available yet" state, whose one action leads back to the site.
+ */
+
+import { localeHref } from "@working-theory/ui";
+import { Button, Heading, Link, Text } from "@working-theory/ui/primitives";
+import { getTranslations } from "next-intl/server";
+import type { ReactElement } from "react";
+
+import { hubSessionConfig } from "./config";
+import { HUB_SESSION_FALLBACK_PATH } from "./session";
+
+/** The route that starts the hub sign-in. */
+const HUB_SIGN_IN_ROUTE = "/api/hub-session/sign-in";
+
+export interface HubSignInGateProps {
+  locale: string;
+  /** The incoming request's headers; `x-pathname` is the page to return to. */
+  requestHeaders: Headers;
+}
+
+export async function HubSignInGate({
+  locale,
+  requestHeaders,
+}: HubSignInGateProps): Promise<ReactElement> {
+  const t = await getTranslations({ locale, namespace: "account.gate" });
+  const configured = hubSessionConfig() !== null;
+  const next =
+    requestHeaders.get("x-pathname") ??
+    localeHref(locale, HUB_SESSION_FALLBACK_PATH);
+
+  return (
+    <div
+      className="flex min-h-screen flex-col items-center justify-center gap-4 py-section text-center"
+      data-testid="account-sign-in-gate"
+    >
+      <Heading level={1} visual={4}>
+        {configured ? t("hubHeadline") : t("emptyHeadline")}
+      </Heading>
+      <Text variant="body-sm" tone="muted" className="max-w-xs">
+        {configured ? t("hubDescription") : t("emptyDescription")}
+      </Text>
+      {configured ? (
+        // The primary action: 44px on a phone, 36px from md up.
+        <Button asChild className="max-md:min-h-11">
+          <Link
+            href={`${HUB_SIGN_IN_ROUTE}?next=${encodeURIComponent(next)}`}
+            variant="bare"
+            data-testid="account-hub-sign-in"
+          >
+            {t("hubSignIn")}
+          </Link>
+        </Button>
+      ) : (
+        <Button asChild variant="secondary" className="max-md:min-h-11">
+          <Link
+            href={localeHref(locale, "/")}
+            variant="bare"
+            data-testid="account-sign-in-gate-home"
+          >
+            {t("homeLink")}
+          </Link>
+        </Button>
+      )}
+    </div>
+  );
+}

package/templates/apps/web/lib/listings-config.ts

@@ -0,0 +1,31 @@
+/**
+ * The listing site key — the ONE reader (#7872 D8).
+ *
+ * The listicle directory (`./listings.tsx`, #7521) switches on this key:
+ * declared, it renders; absent, it is off and makes no read. Every reader of
+ * the key goes through here, so two copies cannot drift.
+ *
+ *   1. `NEXT_PUBLIC_AILK_LISTING_SITE_KEY` — the name the spoke roadmap fixes
+ *      (§7.3). The value names a site and grants nothing (#5048 D2), so it is
+ *      public by design, and a client consumer gets it inlined at build.
+ *   2. `AILK_LISTING_PUBLIC_KEY` — the server-only name every site
+ *      configured since create-ailk 0.12.0 already sets, kept as a fallback
+ *      so an upgrade does not switch a working directory off.
+ *
+ * An empty or whitespace value counts as unset. Both reads use dot access, so
+ * Next inlines the public name at build: changing or rotating it needs a
+ * rebuild, and while it is set a runtime change to the fallback has no effect.
+ */
+
+/** The site's listing key, trimmed, or `undefined` when neither name holds one. */
+export function listingSiteKey(): string | undefined {
+  const declared = process.env.NEXT_PUBLIC_AILK_LISTING_SITE_KEY?.trim();
+  if (declared) return declared;
+  const fallback = process.env.AILK_LISTING_PUBLIC_KEY?.trim();
+  return fallback ? fallback : undefined;
+}
+
+/** Whether the listicle directory is switched on for this site. */
+export function listingsEnabled(): boolean {
+  return listingSiteKey() !== undefined;
+}

package/templates/apps/web/lib/listings.tsx

@@ -20,8 +20,11 @@
  * BASE TREE, and inert without two things (D7). It ships in every scaffold,
  * Free included, and is never slice-owned — the layout imports it, so owning
  * it would strip every page from a keyless scaffold. Each member answers
- * `null` with NO read when `AILK_LISTING_PUBLIC_KEY` is unset or the paid
- * `@working-theory/ui-signal-collectors` package is absent. The package is
+ * `null` with NO read when the site's listing key is unset or the paid
+ * `@working-theory/ui-signal-collectors` package is absent. The key is the
+ * switch: `./listings-config.ts` is its one reader
+ * (`NEXT_PUBLIC_AILK_LISTING_SITE_KEY`, falling back to
+ * `AILK_LISTING_PUBLIC_KEY`, #7872 D8). The package is
  * reached the way `src/lib/commerce-sections.ts` reaches its own: through
  * `loadUiSignalCollectors()` in the generated paid-sections registry (#7536),
  * a bundled `import()` where the site carries the package and a stub that
@@ -64,6 +67,7 @@ import { cache, type ComponentType, type ReactElement, type ReactNode } from "re
 
 import { resolveBaseUrl } from "../src/lib/routes";
 
+import { listingSiteKey } from "./listings-config";
 import { loadUiSignalCollectors } from "./paid-sections.generated";
 
 // ── The paid sections, through the generated registry ──────────────────────
@@ -252,7 +256,7 @@ export function entryJsonLd(entry: ListingEntryPublic, entryType: string, url: s
 // ── The extension ───────────────────────────────────────────────────────────
 
 export function createListingExtension(deps: ListingExtensionDeps = {}): ListingExtension {
-  const siteKey = deps.siteKey ?? (() => process.env["AILK_LISTING_PUBLIC_KEY"]);
+  const siteKey = deps.siteKey ?? listingSiteKey;
   const pathname =
     deps.pathname ?? (async () => (await headers()).get("x-pathname"));
   const locales = deps.locales ?? (() => readLocales());

package/templates/apps/web/lib/meeting-slugs.ts

@@ -17,10 +17,18 @@
  * A duplicated inline call in both pages is how the two would drift, and
  * it is also how one of them would forget the fail-closed arm — this is
  * the ONE place that reasoning lives (D5).
+ *
+ * ON A SPOKE (#7872 D4), `null` means `[]`: the `SCHEDULING_CAL_LINK`
+ * fallback is not consulted. The hub books a spoke's slug only when that
+ * spoke's workspace has stored it (`spokeMayBook`), so a fallback slug would
+ * advertise a meeting whose every booking fails with `event_not_found`. The
+ * other arms are the same on both topologies.
  */
 import { schedule } from "@working-theory/api-client";
 import { MeetingSlugSchema } from "@working-theory/site-config/schema";
 
+import { TOPOLOGY } from "./topology.generated";
+
 /**
  * The D4 row-1 fallback: the slug half of the env-configured booker's own
  * calLink (`"<owner>/<slug>"`), or `[]` when the env var is unset. This is
@@ -49,5 +57,7 @@ function derivedFallbackSlugs(): string[] {
 export async function enabledMeetingSlugs(): Promise<string[]> {
   const res = await schedule.meetingTypes();
   if (!res.ok) return [];
-  return res.body.slugs ?? derivedFallbackSlugs();
+  const { slugs } = res.body;
+  if (slugs) return slugs;
+  return TOPOLOGY === "spoke" ? [] : derivedFallbackSlugs();
 }

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

@@ -0,0 +1,35 @@
+/**
+ * `?next=` sanitizer for the /sign-in page (#4984) and the hub-session
+ * callback (#7894 D7 — moved here from `app/[locale]/(auth)/sign-in/`, which
+ * re-exports it, so a spoke that drops the `(auth)` group keeps it).
+ *
+ * The post-sign-in `callbackURL` handed to Better Auth is caller-controlled
+ * via the `next` search param, so it must be a SAME-ORIGIN, SAME-APP path —
+ * never a foreign origin (open redirect), a protocol-relative URL, a
+ * backslash trick browsers normalise to `//`, or a control character that
+ * could split a header. Anything that fails falls back to `fallback`.
+ */
+
+// U+0000–U+001F and U+007F — the header-splitting / URL-mangling range.
+// eslint-disable-next-line no-control-regex -- the control range is the thing being rejected
+const CONTROL_CHARS = /[\x00-\x1f\x7f]/;
+
+/**
+ * Returns `raw` when it is a safe in-app path, else `fallback`.
+ *
+ * Accepts: a string starting with a single "/" (e.g. `/account`,
+ * `/en/account?tab=x`, `/waitlist#a`).
+ * Rejects: non-strings (incl. Next's `string[]` for a repeated param), "",
+ * `//host` (protocol-relative), `/\host` (backslash normalised to `//`),
+ * any backslash anywhere, whitespace, control characters, and anything not
+ * starting with "/" (`https://…`, `host.tld`).
+ */
+export function resolveNextPath(raw: unknown, fallback: string): string {
+  if (typeof raw !== "string") return fallback;
+  if (!raw.startsWith("/")) return fallback;
+  if (raw.startsWith("//")) return fallback;
+  if (raw.includes("\\")) return fallback;
+  if (/\s/.test(raw)) return fallback;
+  if (CONTROL_CHARS.test(raw)) return fallback;
+  return raw;
+}