hecks 3.5.0 → 3.7.0

data/lib/hecks/projections/site/routes_ts/listings.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Projections
+    module Site
+      module RoutesTs
+        # The lists `routes.ts` derives from the rows for search engines and the content system:
+        # the sitemap and robots paths, and the content-system sources that name a page.
+        module Listings
+          module_function
+
+          def search(rows)
+            <<~TS.chomp
+              // The paths a sitemap lists: indexable pages with no parameter. A collection's pages are listed
+              // from its entries, through `collectionPages`.
+              export const SITEMAP_PATHS = #{RoutesTs.literal(sitemap_paths(rows))} as const;
+
+              // The routes a search engine is kept away from: every route that is not indexable.
+              export const NOT_FOR_SEARCH = #{RoutesTs.literal(hidden_paths(rows))} as const;
+
+              // robots.txt `Disallow` prefixes: each non-public route up to its first parameter.
+              export const ROBOTS_DISALLOW = #{RoutesTs.literal(robots(RoutesTs.live(rows)))} as const;
+            TS
+          end
+
+          def sitemap_paths(rows)
+            RoutesTs.live(rows).select { |row| row.indexable && !row.path.match?(/[:*]/) }.map(&:path).sort
+          end
+
+          def hidden_paths(rows)
+            hidden = rows.reject { |row| row.indexable || row.path == RoutesTs::CATCH_ALL }
+            hidden.flat_map { |row| [row.path, *row.aliases] }.sort
+          end
+
+          def robots(rows)
+            prefixes = rows.reject { |row| row.auth == "public" }.map { |row| robots_prefix(row.path) }
+            prefixes = (prefixes + ["#{RoutesTs::PREVIEW_PREFIX}/"]).uniq.sort
+            prefixes.reject { |prefix| prefixes.any? { |other| other != prefix && prefix.start_with?(other) } }
+          end
+
+          def robots_prefix(path)
+            head = path.split("/").take_while { |part| !part.match?(/\A[:*]/) }.join("/")
+            head == path ? path : "#{head}/"
+          end
+
+          def sources(rows)
+            <<~TS.chomp
+              // A CMS global's slug to the page that shows it.
+              export const globalPages = #{RoutesTs.literal(sourced(rows, "global:", &:path))} as const;
+
+              // A CMS collection's name to the page that shows one of its entries, and whether the sitemap lists them.
+              export const collectionPages = #{RoutesTs.literal(collection_pages(rows))} as const;
+
+              const PREVIEWS: Readonly<Record<string, { readonly path: string; readonly draft: boolean }>> = #{RoutesTs.literal(previews(rows))};
+            TS
+          end
+
+          def collection_pages(rows)
+            sourced(rows, "collection:") { |row| { path: row.path, indexable: row.indexable } }
+          end
+
+          def previews(rows)
+            rows.select { |row| row.source.match?(/\A(global|collection):/) }
+                .to_h { |row| [row.source, { path: row.path, draft: row.preview == "draft" }] }.sort.to_h
+          end
+
+          def sourced(rows, prefix)
+            rows.select { |row| row.source.start_with?(prefix) }
+                .to_h { |row| [row.source.delete_prefix(prefix), yield(row)] }.sort.to_h
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/routes_ts/navigation.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Projections
+    module Site
+      module RoutesTs
+        # The four navigation arrays of `routes.ts`: desktop, mobile, footer and admin.
+        #
+        # They hold every entry that has a slot, a switched-off page's too: an entry of an off page
+        # carries its `switch` and `on: false`, and the site drops it while `pageIsOn(switch)` is
+        # false. An entry of a page that is on carries neither.
+        module Navigation
+          module_function
+
+          # @param table [Table] a checked table
+          # @return [String] the four `NAV_*` constants, as TypeScript
+          def render(table)
+            items = table.rows + table.links
+            [nav_const("NAV_DESKTOP", "The desktop navigation: a page with no group is its own entry; a group holds its pages.",
+                       desktop(items)),
+             nav_const("NAV_MOBILE", "The mobile navigation, in its own order.", mobile(items)),
+             nav_const("NAV_FOOTER", "The footer columns, left to right, each with its links.", footer(items)),
+             nav_const("NAV_ADMIN", "The admin navigation: each admin page under its key.", admin(items))].join("\n\n")
+          end
+
+          def nav_const(name, comment, entries)
+            body = entries.map { |entry| "  #{RoutesTs.literal(entry)}," }
+            "// #{comment}\nexport const #{name} = #{body.empty? ? "[]" : "[\n#{body.join("\n")}\n]"} as const;"
+          end
+
+          # One link: a row's or a link's path and label, the fragment a link names, and for a page
+          # that is off the switch that turns it on.
+          def entry(item, **before)
+            link = { **before, path: item.path, label: item.label }
+            link[:fragment] = item.fragment if item.respond_to?(:fragment) && item.fragment
+            if item.off
+              link[:switch] = item.switch
+              link[:on] = false
+            end
+            link
+          end
+
+          def order_key(item, order) = [order, item.path, item.respond_to?(:fragment) ? item.fragment.to_s : ""]
+
+          def desktop(items)
+            entries = []
+            items.reject { |item| item.nav_order.nil? }.sort_by { |item| order_key(item, item.nav_order) }
+                 .each { |item| place(entries, item) }
+            entries
+          end
+
+          # Adds the item to its group's entry, opening the group's entry when it is the first.
+          def place(entries, item)
+            group = item.nav_group
+            slot = group && entries.find { |candidate| candidate[:group] == group }
+            slot ? slot[:items] << entry(item) : entries << { group: group, items: [entry(item)] }
+          end
+
+          def mobile(items)
+            items.reject { |item| item.mobile_order.nil? }.sort_by { |item| order_key(item, item.mobile_order) }
+                 .map { |item| item.mobile_heading ? entry(item, heading: item.mobile_heading) : entry(item) }
+          end
+
+          def footer(items)
+            ordered = items.select(&:footer_column).sort_by { |item| order_key(item, item.footer_order) }
+            columns = ordered.group_by(&:footer_column)
+            columns.sort_by { |name, group| [group.first.footer_order, name] }
+                   .map { |name, group| { column: name, items: group.map { |item| entry(item) } } }
+          end
+
+          def admin(items)
+            items.select(&:admin_key).sort_by { |item| [item.admin_order, item.admin_key] }
+                 .map { |item| entry(item, key: item.admin_key) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/routes_ts.rb

@@ -3,6 +3,9 @@
 require "json"
 require_relative "../../projector"
 require_relative "table"
+require_relative "routes_ts/helpers"
+require_relative "routes_ts/navigation"
+require_relative "routes_ts/listings"
 
 module Hecks
   module Projections
@@ -51,7 +54,7 @@ module Hecks
         def render(table)
           rows = table.rows
           [BANNER, header, routes(rows), types, switches(rows), redirects(rows), middleware(rows),
-           navigation(table), search(rows), sources(rows), helpers].join("\n\n") << "\n"
+           Navigation.render(table), Listings.search(rows), Listings.sources(rows), helpers].join("\n\n") << "\n"
         end
 
         # @param rows [Array<Table::Row>] the table's rows
@@ -77,14 +80,24 @@ module Hecks
         end
 
         def route_fields(row)
-          fields = { path: row.path, kind: row.kind, render: row.render, auth: row.auth, methods: row.verbs,
-                     cache: row.cache, origin: row.origin, source: row.source, indexable: row.indexable,
-                     switch: blank_to_nil(row.switch), off: row.off, preview: row.preview,
-                     label: blank_to_nil(row.label), seo: blank_to_nil(row.seo), redirectTo: row.redirect_to }
+          fields = { **route_identity(row), **route_serving(row), **route_page(row) }
           fields[:seoTitle] = row.seo_title if row.seo_title
           fields
         end
 
+        def route_identity(row)
+          { path: row.path, kind: row.kind, render: row.render, auth: row.auth, methods: row.verbs }
+        end
+
+        def route_serving(row)
+          { cache: row.cache, origin: row.origin, source: row.source, indexable: row.indexable }
+        end
+
+        def route_page(row)
+          { switch: blank_to_nil(row.switch), off: row.off, preview: row.preview,
+            label: blank_to_nil(row.label), seo: blank_to_nil(row.seo), redirectTo: row.redirect_to }
+        end
+
         def switches(rows)
           switched = rows.reject { |row| row.switch.empty? }.group_by(&:switch)
           ids = switched.sort.to_h { |id, group| [id.to_sym, group.none?(&:off)] }
@@ -114,186 +127,25 @@ module Hecks
           TS
         end
 
-        # The navigation arrays hold every entry that has a slot, a switched-off page's too: an
-        # entry of an off page carries its `switch` and `on: false`, and the site drops it while
-        # `pageIsOn(switch)` is false. An entry of a page that is on carries neither.
-        def navigation(table)
-          items = table.rows + table.links
-          [nav_const("NAV_DESKTOP", "The desktop navigation: a page with no group is its own entry; a group holds its pages.",
-                     desktop(items)),
-           nav_const("NAV_MOBILE", "The mobile navigation, in its own order.", mobile(items)),
-           nav_const("NAV_FOOTER", "The footer columns, left to right, each with its links.", footer(items)),
-           nav_const("NAV_ADMIN", "The admin navigation: each admin page under its key.", admin(items))].join("\n\n")
-        end
-
-        def nav_const(name, comment, entries)
-          body = entries.map { |entry| "  #{literal(entry)}," }
-          "// #{comment}\nexport const #{name} = #{body.empty? ? '[]' : "[\n#{body.join("\n")}\n]"} as const;"
-        end
-
-        # One link: a row's or a link's path and label, the fragment a link names, and for a page
-        # that is off the switch that turns it on.
-        def entry(item, **before)
-          link = { **before, path: item.path, label: item.label }
-          link[:fragment] = item.fragment if item.respond_to?(:fragment) && item.fragment
-          link.merge!(switch: item.switch, on: false) if item.off
-          link
-        end
-
-        def order_key(item, order) = [order, item.path, item.respond_to?(:fragment) ? item.fragment.to_s : ""]
-
-        def desktop(items)
-          entries = []
-          items.reject { |item| item.nav_order.nil? }.sort_by { |item| order_key(item, item.nav_order) }.each do |item|
-            group = item.nav_group
-            slot = group && entries.find { |candidate| candidate[:group] == group }
-            slot ? slot[:items] << entry(item) : entries << { group: group, items: [entry(item)] }
-          end
-          entries
-        end
-
-        def mobile(items)
-          items.reject { |item| item.mobile_order.nil? }.sort_by { |item| order_key(item, item.mobile_order) }
-               .map { |item| item.mobile_heading ? entry(item, heading: item.mobile_heading) : entry(item) }
-        end
-
-        def footer(items)
-          columns = items.select(&:footer_column).sort_by { |item| order_key(item, item.footer_order) }.group_by(&:footer_column)
-          columns.sort_by { |name, group| [group.first.footer_order, name] }
-                 .map { |name, group| { column: name, items: group.map { |item| entry(item) } } }
-        end
-
-        def admin(items)
-          items.select(&:admin_key).sort_by { |item| [item.admin_order, item.admin_key] }
-               .map { |item| entry(item, key: item.admin_key) }
-        end
-
-        def search(rows)
-          sitemap = live(rows).select { |row| row.indexable && !row.path.match?(/[:*]/) }.map(&:path).sort
-          hidden = rows.reject { |row| row.indexable || row.path == CATCH_ALL }.flat_map { |row| [row.path, *row.aliases] }.sort
-          <<~TS.chomp
-            // The paths a sitemap lists: indexable pages with no parameter. A collection's pages are listed
-            // from its entries, through `collectionPages`.
-            export const SITEMAP_PATHS = #{literal(sitemap)} as const;
-
-            // The routes a search engine is kept away from: every route that is not indexable.
-            export const NOT_FOR_SEARCH = #{literal(hidden)} as const;
-
-            // robots.txt `Disallow` prefixes: each non-public route up to its first parameter.
-            export const ROBOTS_DISALLOW = #{literal(robots(live(rows)))} as const;
-          TS
-        end
-
-        def robots(rows)
-          prefixes = rows.reject { |row| row.auth == "public" }.map { |row| robots_prefix(row.path) }
-          prefixes = (prefixes + ["#{PREVIEW_PREFIX}/"]).uniq.sort
-          prefixes.reject { |prefix| prefixes.any? { |other| other != prefix && prefix.start_with?(other) } }
-        end
-
-        def robots_prefix(path)
-          head = path.split("/").take_while { |part| !part.match?(/\A[:*]/) }.join("/")
-          head == path ? path : "#{head}/"
-        end
-
-        def sources(rows)
-          globals = sourced(rows, "global:", &:path)
-          collections = sourced(rows, "collection:") { |row| { path: row.path, indexable: row.indexable } }
-          previews = rows.select { |row| row.source.match?(/\A(global|collection):/) }
-                         .to_h { |row| [row.source, { path: row.path, draft: row.preview == "draft" }] }.sort.to_h
-          <<~TS.chomp
-            // A CMS global's slug to the page that shows it.
-            export const globalPages = #{literal(globals)} as const;
-
-            // A CMS collection's name to the page that shows one of its entries, and whether the sitemap lists them.
-            export const collectionPages = #{literal(collections)} as const;
-
-            const PREVIEWS: Readonly<Record<string, { readonly path: string; readonly draft: boolean }>> = #{literal(previews)};
-          TS
-        end
-
-        def sourced(rows, prefix)
-          rows.select { |row| row.source.start_with?(prefix) }
-              .to_h { |row| [row.source.delete_prefix(prefix), yield(row)] }.sort.to_h
-        end
-
-        def helpers = [path_helpers, page_helpers].join("\n\n")
-
-        def path_helpers
-          <<~'TS'.chomp
-            /** Drops a trailing `.html` and a trailing slash, so `/about.html`, `/about/` and `/about` are one path. */
-            export function stripHtml(pathname: string): string {
-              const bare = pathname.endsWith(".html") ? pathname.slice(0, -".html".length) : pathname;
-              return bare.length > 1 && bare.endsWith("/") ? bare.slice(0, -1) : bare;
-            }
-
-            function toRegExp(pattern: string): RegExp {
-              const source = stripHtml(pattern)
-                .split("/")
-                .map((part) =>
-                  part.startsWith(":")
-                    ? "[^/]+"
-                    : part
-                        .split("*")
-                        .map((piece) => piece.replace(/[.+?^${}()|[\]\\]/g, "\\$&"))
-                        .join(".*"),
-                )
-                .join("/");
-              return new RegExp("^" + source + "$");
-            }
-
-            /**
-             * Whether a pathname is one a route pattern describes, with or without `.html`. A `:name` is one
-             * segment; a `*` is any run of characters, `/` included, wherever it stands, as in a CDN's path
-             * pattern: `/pay/*` matches `/pay/7` and `/admin*` matches `/admin`, `/admin-inbox` and `/admin/x`.
-             */
-            export function matchesPath(pattern: string, pathname: string): boolean {
-              return toRegExp(pattern).test(stripHtml(pathname));
-            }
-          TS
-        end
-
-        def page_helpers
-          <<~'TS'.chomp
-            /** Whether a page is on: true for an id no row switches off, and for an id no row names. */
-            export function pageIsOn(id: string): boolean {
-              return Object.prototype.hasOwnProperty.call(SWITCHES, id) ? SWITCHES[id] : true;
-            }
-
-            /** Whether a pathname belongs to a switched-off page, with or without `.html`. */
-            export function isOffPath(pathname: string): boolean {
-              return MIDDLEWARE.off.paths.some((pattern) => matchesPath(pattern, pathname));
-            }
-
-            /** Whether a search engine is kept away from a pathname. */
-            export function notForSearch(pathname: string): boolean {
-              return NOT_FOR_SEARCH.some((pattern) => matchesPath(pattern, pathname));
-            }
-
-            /** The URL that previews a CMS source (`global:<slug>` or `collection:<name>`), under the preview prefix when it is a draft. */
-            export function previewUrl(source: string, slug?: string): string {
-              const entry = PREVIEWS[source];
-              if (entry === undefined) throw new Error(`no route has the source ${source}`);
-              let path = entry.path;
-              if (path.includes(":")) {
-                if (slug === undefined) throw new Error(`${source} previews one entry: pass its slug`);
-                path = path.replace(/:[A-Za-z_]\w*/, encodeURIComponent(slug));
-              }
-              return entry.draft ? MIDDLEWARE.preview.prefix + stripHtml(path) : path;
-            }
-          TS
-        end
+        def helpers = Helpers.text
 
         def blank_to_nil(text) = text.nil? || text.empty? ? nil : text
 
         # @param value [Object] a string, number, boolean, nil, array or hash
         # @return [String] the TypeScript literal for it: objects with bare keys, on one line
         def literal(value)
+          case value
+          when Array then "[#{value.map { |item| literal(item) }.join(", ")}]"
+          when Hash then "{ #{value.map { |key, item| "#{key_literal(key)}: #{literal(item)}" }.join(", ")} }".sub("{  }", "{}")
+          else scalar_literal(value)
+          end
+        end
+
+        def scalar_literal(value)
           case value
           when nil then "null"
           when true, false, Integer then value.to_s
           when String then JSON.generate(value)
-          when Array then "[#{value.map { |item| literal(item) }.join(', ')}]"
-          when Hash then "{ #{value.map { |key, item| "#{key_literal(key)}: #{literal(item)}" }.join(', ')} }".sub("{  }", "{}")
           else raise ArgumentError, "no TypeScript literal for #{value.inspect}"
           end
         end

data/lib/hecks/projections/site/site_admin/access.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Projections
+    module Site
+      module SiteAdmin
+        # The access half of the admin module: remembered verdicts, the hand-off to the content
+        # system, route matching and the gate.
+        module Access
+          # The TypeScript of `verdicts`.
+          VERDICTS = <<~TS.chomp
+            const accountEmails = remember(fetchAccountEmail);
+            const adminSessions = remember(fetchAdminSession);
+
+            /** Drops every remembered verdict, for after this process changes a member. */
+            export function forgetAdminSessions(): void {
+              accountEmails.forget();
+              adminSessions.forget();
+            }
+
+            /** The signed-in person's email, or null when the cookie is absent or the host does not know it. */
+            export async function currentAccountEmail(cookieValue: string | undefined): Promise<string | null> {
+              return cookieValue ? accountEmails.get(cookieValue) : null;
+            }
+
+            /** The signed-in person and the membership list when they hold an admin role, else null. */
+            export async function currentAdminSession(cookieValue: string | undefined): Promise<AdminSession | null> {
+              return cookieValue ? adminSessions.get(cookieValue) : null;
+            }
+
+            /** The signed-in person's email when they may use the admin pages, else null. */
+            export async function currentAdminEmail(cookieValue: string | undefined): Promise<string | null> {
+              return (await currentAdminSession(cookieValue))?.email ?? null;
+            }
+          TS
+
+          # The TypeScript of `handoff`.
+          HANDOFF = <<~TS.chomp
+            /**
+             * Where the hand-off to the CMS sends a person: the CMS's own sign-in endpoint with a short-lived
+             * token from the host, or the login page when there is no session or the host refuses the token.
+             * `to` is a path inside the CMS to open once signed in; the CMS checks it.
+             */
+            export async function ssoRedirect(cookieValue: string | undefined, to?: string | null): Promise<string> {
+              if (!cookieValue) return ADMIN.login;
+              const res = await askHost(ADMIN.ssoTokenPath, cookieValue);
+              if (!res.ok) return ADMIN.login;
+              const { token } = await res.json();
+              const params = new URLSearchParams({ token });
+              if (to) params.set("to", to);
+              return `${ADMIN.ssoTarget}?${params}`;
+            }
+          TS
+
+          # The TypeScript of `routing`.
+          ROUTING = <<~'TS'.chomp
+            /**
+             * How specific a route pattern is: the characters that are not a wildcard or a `:name` parameter,
+             * so `/admin-login` outranks `/admin*` and `/admin.html` outranks `/:slug.html`.
+             */
+            function specificity(pattern: string): number {
+              return pattern.replace(/:[A-Za-z_]\w*/g, "").replace(/\*/g, "").length;
+            }
+
+            /**
+             * The route that describes a path: the most specific match. Between routes equally specific the
+             * `admin` one wins, so a tie never lets a visitor through; after that, the first listed.
+             */
+            function routeFor(pathname: string): (typeof ROUTES)[number] | undefined {
+              let best: (typeof ROUTES)[number] | undefined;
+              for (const candidate of ROUTES) {
+                if (!matchesPath(candidate.path, pathname)) continue;
+                if (best === undefined) {
+                  best = candidate;
+                  continue;
+                }
+                const more = specificity(candidate.path) - specificity(best.path);
+                if (more > 0 || (more === 0 && candidate.auth === "admin" && best.auth !== "admin")) best = candidate;
+              }
+              return best;
+            }
+          TS
+
+          # The TypeScript of `gate`.
+          GATE = <<~TS.chomp
+            export type AdminGate = { allow: true } | { allow: false; status: 401 } | { allow: false; redirect: string };
+
+            /**
+             * Whether a request may go on. The most specific route that matches the path decides (see `routeFor`): an `admin`
+             * route, or any path under the draft-preview prefix, needs an admin session. A preview without
+             * one is refused with 401 and nothing else; any other admin path is sent to the login page.
+             */
+            export async function adminGate(pathname: string, cookieValue: string | undefined): Promise<AdminGate> {
+              const previewing = pathname.startsWith(MIDDLEWARE.preview.prefix + "/");
+              if (routeFor(pathname)?.auth !== "admin" && !previewing) return { allow: true };
+              if (await currentAdminEmail(cookieValue)) return { allow: true };
+              return previewing ? { allow: false, status: 401 } : { allow: false, redirect: ADMIN.login };
+            }
+          TS
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/site_admin/session.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Projections
+    module Site
+      module SiteAdmin
+        # The session half of the admin module: the memo that remembers verdicts, the settings, the
+        # membership test and the fetches that read the host.
+        module Session
+          # The TypeScript of `memo`.
+          MEMO = <<~TS.chomp
+            const MAX_REMEMBERED = 500;
+
+            /** Remembers each key's answer for the verdict TTL; callers that arrive while it loads share it, and a failure is never kept. */
+            function remember<V>(load: (key: string) => Promise<V>) {
+              const values = new Map<string, { at: number; value: V }>();
+              const running = new Map<string, Promise<V>>();
+              return {
+                get(key: string): Promise<V> {
+                  const hit = values.get(key);
+                  if (hit && Date.now() - hit.at < ADMIN.verdictTtlMs) return Promise.resolve(hit.value);
+                  const shared = running.get(key);
+                  if (shared) return shared;
+                  const started: Promise<V> = load(key)
+                    .then((value) => {
+                      if (running.get(key) === started) {
+                        values.delete(key);
+                        values.set(key, { at: Date.now(), value });
+                        if (values.size > MAX_REMEMBERED) values.delete(values.keys().next().value as string);
+                      }
+                      return value;
+                    })
+                    .finally(() => {
+                      if (running.get(key) === started) running.delete(key);
+                    });
+                  running.set(key, started);
+                  return started;
+                },
+                forget(): void {
+                  values.clear();
+                  running.clear();
+                },
+              };
+            }
+          TS
+
+          # The TypeScript of `configuration`.
+          CONFIGURATION = <<~'TS'.chomp
+            export interface AdminSettings {
+              /** The domain host's address, when not read from the environment variable the Admin row names. */
+              host?: string;
+              /** The fetch to use, for tests. */
+              fetch?: typeof fetch;
+            }
+
+            let settings: AdminSettings = {};
+
+            /** Sets the host or the fetch, and forgets every remembered verdict. */
+            export function configureAdmin(next: AdminSettings): void {
+              settings = next;
+              forgetAdminSessions();
+            }
+
+            function hostUrl(): string {
+              const named = settings.host ?? (typeof process !== "undefined" ? process.env[ADMIN.hostEnv] : undefined);
+              return (named || ADMIN.hostDefault).replace(/\/+$/, "");
+            }
+
+            function askHost(path: string, cookieValue: string): Promise<Response> {
+              return (settings.fetch ?? fetch)(`${hostUrl()}${path}`, {
+                headers: { Cookie: `${ADMIN.sessionCookie}=${cookieValue}` },
+                signal: AbortSignal.timeout(ADMIN.timeoutMs),
+              });
+            }
+          TS
+
+          # The TypeScript of `membership`.
+          MEMBERSHIP = <<~TS.chomp
+            export interface MemberRow {
+              email?: unknown;
+              role?: unknown;
+              disabled?: unknown;
+            }
+
+            /** True when `email` (any case) is a member holding one of the admin roles and not disabled. */
+            export function isActiveAdmin(members: MemberRow[], email: string): boolean {
+              const wanted = email.trim().toLowerCase();
+              return members.some(
+                (member) =>
+                  typeof member.email === "string" &&
+                  member.email.trim().toLowerCase() === wanted &&
+                  (ADMIN.roles as readonly unknown[]).includes(member.role) &&
+                  member.disabled !== true,
+              );
+            }
+          TS
+
+          # The TypeScript of `sessions`.
+          SESSIONS = <<~TS.chomp
+            /** A signed-in admin and the membership list that vouched for them. */
+            export interface AdminSession {
+              email: string;
+              members: unknown[];
+            }
+
+            async function fetchAccountEmail(cookieValue: string): Promise<string | null> {
+              const res = await askHost(ADMIN.accountPath, cookieValue);
+              if (!res.ok) return null;
+              const data = await res.json();
+              return typeof data.email === "string" ? data.email : null;
+            }
+
+            async function fetchAdminSession(cookieValue: string): Promise<AdminSession | null> {
+              const [email, membersRes] = await Promise.all([
+                fetchAccountEmail(cookieValue),
+                askHost(ADMIN.membersPath, cookieValue),
+              ]);
+              if (!email || !membersRes.ok) return null;
+              const members = await membersRes.json();
+              return Array.isArray(members) && isActiveAdmin(members, email) ? { email, members } : null;
+            }
+          TS
+        end
+      end
+    end
+  end
+end