@coralreefventures/site-tools 0.3.0 → 0.4.1

package/src/door/server.ts

@@ -5,6 +5,7 @@ import { fileURLToPath } from "node:url";
 import { sendFile, staticTarget } from "../serve.ts";
 import { type GateConfig, readGateConfig } from "./config.ts";
 import { canonicalNext, unsafe } from "./next.ts";
+import { comingSoon } from "./page.ts";
 import { verifyTicket } from "./verify.ts";
 
 // The gate is the one thing in a locked site's compute bundle, and the bundle carries no node_modules, so this file
@@ -15,6 +16,13 @@ export const sessionCookie = "__Host-crv_door";
 /** The nonce the gate sets before it sends a visitor to the door, which the ticket must name as `st`. */
 export const stateCookie = "__Host-crv_door_state";
 export const stateLifetimeSeconds = 600;
+/**
+ * A marker that this browser has held a session here, so that once the hour is up a page load bounces silently through
+ * the door (which issues a fresh ticket while its own sign-in lives) instead of meeting the coming-soon page. It holds
+ * no identity and opens nothing: without a valid session it changes only which way a page load is sent to sign in.
+ */
+export const seenCookie = "__Host-crv_door_seen";
+export const seenLifetimeSeconds = 30 * 24 * 60 * 60;
 
 const maxBodyBytes = 16 * 1024;
 const encodedUnsafe = /%(5c|[01][0-9a-f]|7f)/i;
@@ -32,6 +40,8 @@ const cookie = (name: string, value: string, maxAge: number, sameSite: "Lax" | "
   `${name}=${value}; Max-Age=${maxAge}; Path=/; Secure; HttpOnly; SameSite=${sameSite}`;
 const clearSession = cookie(sessionCookie, "", 0, "Lax");
 const clearState = cookie(stateCookie, "", 0, "None");
+const markSeen = cookie(seenCookie, "1", seenLifetimeSeconds, "Lax");
+const clearSeen = cookie(seenCookie, "", 0, "Lax");
 
 /** One value of a cookie, or undefined when it is absent or sent twice (which a `__Host-` cookie never is). */
 export const readCookie = (header: string | undefined, name: string): string | undefined => {
@@ -71,6 +81,15 @@ export const splitTarget = (target: string): { rawPath: string; rawQuery: string
 /** GET, HEAD and POST; the gate answers anything else with 405. */
 const isGatedMethod = (method: string | undefined) => method === "GET" || method === "HEAD" || method === "POST";
 
+/**
+ * The challenge every 401 carries, as RFC 9110 requires of one. No registered scheme describes a session cookie from a
+ * sign-in page, so this is the shape of the Cookie scheme drafted for exactly that (draft-broyer-http-cookie-auth):
+ * where the sign-in starts, and the cookie it ends in. Browsers prompt only for the schemes they implement (Basic,
+ * Digest, Negotiate, NTLM), so for this one they render the body, which for a page load is the coming-soon page.
+ */
+export const challenge = (site: string) =>
+  `Cookie realm="${site}", form-action="/_door/signin", cookie-name="${sessionCookie}"`;
+
 /** The paths the gate answers itself, with or without a session: robots.txt and its own /_door/ endpoints. */
 const isOwnPath = (path: string) => path === "/robots.txt" || path.startsWith("/_door/");
 
@@ -82,6 +101,16 @@ export const isDocumentRequest = (request: IncomingMessage): boolean => {
   return String(request.headers.accept ?? "").includes("text/html");
 };
 
+/**
+ * A page load in the window itself: a document request whose `Sec-Fetch-Dest`, when sent, is `document`. Only this
+ * may start a sign-in, so an image, a frame or a fetch from another site cannot overwrite a visitor's state cookie.
+ */
+export const isTopLevelNavigation = (request: IncomingMessage): boolean => {
+  if (!isDocumentRequest(request)) return false;
+  const dest = request.headers["sec-fetch-dest"];
+  return dest === undefined || dest === "document";
+};
+
 /**
  * The form body, or null once it passes 16 KB. The rest of an oversized body is read and thrown away rather than the
  * socket destroyed, so the visitor still gets the redirect back to the door; that response closes the connection.
@@ -124,9 +153,11 @@ export type GateOptions = {
  * The gate: every request to a locked site, in this order. (1) A path with a backslash, a control character or a dot
  * segment, raw or encoded, is a 400; a method other than GET, HEAD or POST is a 405. (2) A host not on the list is a
  * 403. (3) robots.txt disallows everything, and /_door/health answers ok. (4) POST /_door verifies a ticket from the
- * door and sets the session. (5) /_door/signout clears both cookies and walks a fixed map. (6) A request with a valid
- * session is served from the export. (7) Without one, a page load is sent to the door with a fresh state cookie and
- * anything else gets 401. (8) An exception is a 500 with nothing in it: the gate fails closed.
+ * door and sets the session; /_door/signin starts a sign-in at the door. (5) /_door/signout clears the door's cookies and walks
+ * a fixed map. (6) A request with a valid session is served from the export. (7) Without one, a page load gets the
+ * coming-soon page, a 401 whose sign-in link carries the canonical next (or, from a browser that has had a session
+ * here, a silent bounce through the door), and anything else gets an empty 401. (8) An
+ * exception is a 500 with nothing in it: the gate fails closed.
  */
 export const createGate = ({
   config,
@@ -149,6 +180,8 @@ export const createGate = ({
     response.end(request.method === "HEAD" ? undefined : body);
   };
   const doorSignout = `${config.door}/signout/`;
+  const page = comingSoon(config.page, config.door, config.site);
+  const unauthorized = challenge(config.site);
 
   /** Where `then` leads: the next stop's gate, or the door's sign-out page. Never a URL from the query. */
   const signoutTarget = (then: string | null): string => {
@@ -190,20 +223,60 @@ export const createGate = ({
     const claimNext = canonicalNext(verdict.claims.next, host);
     if (formNext === null || claimNext === null || formNext !== claimNext) return toDoorWithError(response);
     const maxAge = verdict.claims.exp - now();
-    return redirect(response, 303, claimNext, [cookie(sessionCookie, ticket ?? "", maxAge, "Lax"), clearState]);
+    return redirect(response, 303, claimNext, [
+      cookie(sessionCookie, ticket ?? "", maxAge, "Lax"),
+      clearState,
+      markSeen,
+    ]);
   };
 
-  /** Step 7: no session. A page load goes to the door with a fresh state; anything else is a bare 401. */
-  const refuse = (request: IncomingMessage, response: ServerResponse, target: string, host: string) => {
-    if (!isDocumentRequest(request)) return empty(response, 401);
+  /**
+   * Step 4's sign-in start, which the coming-soon page's button links to: a fresh state cookie and a 302 to the door,
+   * naming this site, this host and where to come back to. `next` is taken from the query only after *Canonical next*;
+   * one that fails, or is missing or sent twice, becomes `/`. Only a top-level navigation starts one; anything else
+   * gets an empty 401 and no cookie.
+   */
+  const startSignin = (request: IncomingMessage, response: ServerResponse, rawQuery: string, host: string) => {
+    if (!isTopLevelNavigation(request)) return empty(response, 401, { "WWW-Authenticate": unauthorized });
+    const asked = new URLSearchParams(rawQuery).getAll("next");
+    const next = (asked.length === 1 ? canonicalNext(asked[0], host) : null) ?? "/";
+    return toDoor(response, next, host);
+  };
+
+  /** A fresh state cookie and a 302 to the door, for an already canonical `next`. */
+  const toDoor = (response: ServerResponse, next: string, host: string) => {
     const nonce = randomBytes(32).toString("base64url");
-    const next = canonicalNext(target, host) ?? "/";
     const query = new URLSearchParams({ site: config.site, host, next, state: nonce });
     return redirect(response, 302, `${config.door}/?${query}`, [
       cookie(stateCookie, nonce, stateLifetimeSeconds, "None"),
     ]);
   };
 
+  /**
+   * Step 7: no session. A page load gets the coming-soon page, which is the gate's own and holds none of the site;
+   * its sign-in link carries the raw request target after *Canonical next*, or `/`. Anything else is a bare 401.
+   * Both are 401, so a request without a session never gets a 2xx with anything of the site's in it, and a probe can
+   * tell locked from open by the status alone. A page load from a browser that has held a session here (the seen
+   * cookie) is sent straight to the door instead, which renews the session silently while the door's sign-in lives.
+   */
+  const refuse = (request: IncomingMessage, response: ServerResponse, target: string, host: string) => {
+    if (!isDocumentRequest(request)) return empty(response, 401, { "WWW-Authenticate": unauthorized });
+    const next = canonicalNext(target, host) ?? "/";
+    if (readCookie(request.headers.cookie, seenCookie) === "1" && isTopLevelNavigation(request)) {
+      return toDoor(response, next, host);
+    }
+    const body = page.html(next);
+    response.writeHead(401, {
+      ...securityHeaders,
+      "Cache-Control": "no-store",
+      "Content-Type": "text/html; charset=utf-8",
+      "Content-Length": String(Buffer.byteLength(body)),
+      "Content-Security-Policy": page.csp,
+      "WWW-Authenticate": unauthorized,
+    });
+    response.end(request.method === "HEAD" ? undefined : body);
+  };
+
   /** Step 6: the export, as Amplify maps it, private to the browser that holds the session. */
   const serveSite = async (
     request: IncomingMessage,
@@ -229,13 +302,20 @@ export const createGate = ({
     return sendFile(request, response, found.file, 200, { ...securityHeaders, "Cache-Control": cacheControl });
   };
 
-  /** Steps 3 and 5: what the gate answers itself, which holds nothing of the site. */
-  const answerOwn = (request: IncomingMessage, response: ServerResponse, path: string, rawQuery: string) => {
+  /** Steps 3, 4's sign-in start and 5: what the gate answers itself, which holds nothing of the site. */
+  const answerOwn = (
+    request: IncomingMessage,
+    response: ServerResponse,
+    path: string,
+    rawQuery: string,
+    host: string,
+  ) => {
     if (path === "/robots.txt") return text(response, request, "User-agent: *\nDisallow: /\n");
     if (path === "/_door/health") return text(response, request, "ok");
+    if (path === "/_door/signin") return startSignin(request, response, rawQuery, host);
     if (path === "/_door/signout") {
       const then = new URLSearchParams(rawQuery).get("then");
-      return redirect(response, 303, signoutTarget(then), [clearSession, clearState]);
+      return redirect(response, 303, signoutTarget(then), [clearSession, clearState, clearSeen]);
     }
     return empty(response, 404);
   };
@@ -267,7 +347,7 @@ export const createGate = ({
 
     if (path === "/_door") return acceptTicket(request, response, host);
     if (request.method === "POST") return empty(response, 405, { Allow: "GET, HEAD" });
-    if (isOwnPath(path)) return answerOwn(request, response, path, rawQuery);
+    if (isOwnPath(path)) return answerOwn(request, response, path, rawQuery, host);
 
     if (!hasSession(request, host)) return refuse(request, response, target, host);
     return serveSite(request, response, path, { rawPath, rawQuery, host });

package/src/index.ts

@@ -10,6 +10,7 @@ export {
 export { canonicalNext } from "./door/next.ts";
 export {
   type BundleDoorOptions,
+  type BundlePageOptions,
   bundleDoor,
   checkDeployment,
   type DeployManifest,
@@ -17,10 +18,19 @@ export {
   gateFiles,
   maxBundleBytes,
 } from "./door/package.ts";
+export {
+  type ComingSoon,
+  comingSoon,
+  type PageConfig,
+  type PageConfigFile,
+  type PageImage,
+  parsePageConfig,
+} from "./door/page.ts";
 export {
   createGate,
   type GateOptions,
   type StartGateOptions,
+  seenCookie,
   sessionCookie,
   startGate,
   stateCookie,

package/src/lighthouse.ts

@@ -18,6 +18,12 @@ export type LighthouseOptions = {
   threshold?: number;
   /** The pages to audit; every page in the export's sitemap when none are given. */
   paths?: readonly string[];
+  /**
+   * How many more times a page under the threshold is measured; 2 by default, so a page gets three runs and the
+   * median of each category's scores. Performance on a shared runner swings a few points between runs of the same
+   * page, and one low run fails a gate that three agree would pass; a page every run finds low still fails.
+   */
+  retries?: number;
   /** The Lighthouse release `pnpm dlx` runs. */
   lighthouseVersion?: string;
   /** The Chrome binary; Playwright's Chromium when it is installed and nothing is given. */
@@ -28,10 +34,35 @@ export type LighthouseOptions = {
 
 export type PageResult = {
   path: string;
-  /** Each category's score, 0 to 1. */
+  /** Each category's score, 0 to 1: the median over the page's runs. */
   scores: Record<Category, number>;
   /** The categories under the threshold. */
   low: Category[];
+  /** How many times the page was measured. */
+  runs: number;
+};
+
+/** The median of the scores, which three runs with one low outlier put at the typical run. */
+export const median = (values: readonly number[]): number => {
+  const sorted = [...values].sort((left, right) => left - right);
+  const middle = Math.floor(sorted.length / 2);
+  if (sorted.length === 0) {
+    return 0;
+  }
+  return sorted.length % 2 === 1
+    ? (sorted[middle] as number)
+    : ((sorted[middle - 1] as number) + (sorted[middle] as number)) / 2;
+};
+
+/** The categories under the threshold, by the median of each one's scores over the runs so far. */
+export const judge = (
+  runs: readonly Record<Category, number>[],
+  threshold: number,
+): { scores: Record<Category, number>; low: Category[] } => {
+  const scores = Object.fromEntries(
+    categories.map((category) => [category, median(runs.map((run) => run[category]))]),
+  ) as Record<Category, number>;
+  return { scores, low: categories.filter((category) => scores[category] < threshold) };
 };
 
 type Report = { categories: Record<string, { score: number | null } | undefined> };
@@ -86,6 +117,39 @@ const audit = (url: string, base: string, version: string, chrome: string | unde
     run.on("exit", (code) => (code === 0 ? resolve() : reject(new Error(`Lighthouse exited with ${code} on ${url}`))));
   });
 
+type Measure = {
+  origin: string;
+  version: string;
+  chrome: string | undefined;
+  threshold: number;
+  retries: number;
+  log: (line: string) => void;
+};
+
+const shown = (scores: Record<Category, number>) =>
+  categories.map((category) => Math.round(scores[category] * 100)).join("  ");
+
+/** One page's verdict: measured again while under the threshold, up to `retries` more times; the median decides. */
+const measurePage = async (pagePath: string, base: string, measure: Measure): Promise<PageResult> => {
+  const runs: Record<Category, number>[] = [];
+  let verdict = judge(runs, measure.threshold);
+  while (runs.length === 0 || (verdict.low.length > 0 && runs.length <= measure.retries)) {
+    await audit(`${measure.origin}${pagePath}`, base, measure.version, measure.chrome);
+    const report = JSON.parse(await readFile(`${base}.report.json`, "utf8")) as Report;
+    const scores = Object.fromEntries(
+      categories.map((category) => [category, report.categories[category]?.score ?? 0]),
+    ) as Record<Category, number>;
+    runs.push(scores);
+    verdict = judge(runs, measure.threshold);
+    if (verdict.low.length > 0 && runs.length <= measure.retries) {
+      measure.log(`again ${pagePath.padEnd(28)} ${shown(scores)}   (run ${runs.length} of ${measure.retries + 1})`);
+    }
+  }
+  const over = runs.length > 1 ? `   (median of ${runs.length} runs)` : "";
+  measure.log(`${verdict.low.length ? "FAIL" : "ok  "} ${pagePath.padEnd(28)} ${shown(verdict.scores)}${over}`);
+  return { path: pagePath, scores: verdict.scores, low: verdict.low, runs: runs.length };
+};
+
 /**
  * The merge gate: Lighthouse on every page, each category at the threshold or above, with Lighthouse's default
  * mobile emulation and throttling, against the export served as the host serves it. A page under the threshold
@@ -95,6 +159,7 @@ export const runLighthouse = async (options: LighthouseOptions = {}): Promise<Pa
   const root = options.root ?? "out";
   const reportDir = options.reportDir ?? "lighthouse";
   const threshold = options.threshold ?? 0.9;
+  const retries = Math.max(0, options.retries ?? 2);
   const version = options.lighthouseVersion ?? "13.5.0";
   const log = options.log ?? console.log;
   const paths = options.paths?.length ? options.paths : await pagesFromSitemap(root);
@@ -105,16 +170,9 @@ export const runLighthouse = async (options: LighthouseOptions = {}): Promise<Pa
     await mkdir(reportDir, { recursive: true });
     for (const pagePath of paths) {
       const base = reportBase(reportDir, pagePath);
-      await audit(`${origin}${pagePath}`, base, version, chrome);
-      const report = JSON.parse(await readFile(`${base}.report.json`, "utf8")) as Report;
-      const scores = Object.fromEntries(
-        categories.map((category) => [category, report.categories[category]?.score ?? 0]),
-      ) as Record<Category, number>;
-      const low = categories.filter((category) => scores[category] < threshold);
-      results.push({ path: pagePath, scores, low });
-      const shown = categories.map((category) => Math.round(scores[category] * 100)).join("  ");
-      log(`${low.length ? "FAIL" : "ok  "} ${pagePath.padEnd(28)} ${shown}`);
-      if (low.length === 0) {
+      const result = await measurePage(pagePath, base, { origin, version, chrome, threshold, retries, log });
+      results.push(result);
+      if (result.low.length === 0) {
         await rm(`${base}.report.json`);
         await rm(`${base}.report.html`);
       }