@design.estate/wcctools 6.2.0 → 7.0.0

package/ts/capture/request.ts

@@ -0,0 +1,304 @@
+import * as plugins from '../plugins.js';
+import { WccCaptureRequestError } from './errors.js';
+
+type IWccCaptureSubject = plugins.interfaces.IWccCaptureSubject;
+type TWccCaptureFraming = plugins.interfaces.TWccCaptureFraming;
+type TWccInteractionStep = plugins.interfaces.TWccInteractionStep;
+
+/** The limits every capture request is held to. */
+export const captureLimits = {
+  minWidth: 200,
+  maxWidth: 3840,
+  minHeight: 200,
+  maxHeight: 4320,
+  defaultHeight: 800,
+  /** Full-page captures are cut at this height in CSS pixels. */
+  maxFullPageHeight: 10_000,
+  defaultJpegQuality: 80,
+  maxSteps: 20,
+  stepTimeoutMs: 5_000,
+  maxWaitMs: 3_000,
+  defaultObserveMs: 500,
+  maxObserveMs: 5_000,
+  defaultMaxFrames: 12,
+  maxMaxFrames: 40,
+  defaultFrameQuality: 70,
+  maxSelectorLength: 500,
+  maxTextLength: 2_000,
+  maxKeyLength: 32,
+  maxSubjectLength: 200,
+} as const;
+
+/** The capture widths of the named viewports: the dees-domtools breakpoints. */
+export const captureViewportWidths: Readonly<Record<plugins.interfaces.TWccCaptureViewportPreset, number>> = {
+  phone: plugins.deesDomtools.breakpoints.phone,
+  phablet: plugins.deesDomtools.breakpoints.phablet,
+  tablet: plugins.deesDomtools.breakpoints.tablet,
+  desktop: plugins.deesDomtools.breakpoints.desktop,
+};
+
+const isViewportPreset = (valueArg: unknown): valueArg is plugins.interfaces.TWccCaptureViewportPreset => {
+  return typeof valueArg === 'string' && Object.hasOwn(captureViewportWidths, valueArg);
+};
+
+const framings: readonly TWccCaptureFraming[] = ['element', 'viewport', 'fullpage'];
+
+/** The preview set-up of a capture, validated and with its defaults applied. */
+export interface IWccResolvedView {
+  width: number;
+  height: number;
+  theme: plugins.interfaces.TWccTheme;
+  scale: 1 | 2;
+}
+
+export interface IWccResolvedImageOptions {
+  /** Undefined: the default framing of what the demo rendered. */
+  framing?: TWccCaptureFraming;
+  format: 'png' | 'jpeg';
+  /** JPEG quality; undefined for PNG. */
+  quality?: number;
+}
+
+export interface IWccResolvedScreenshotRequest {
+  subject: IWccCaptureSubject;
+  view: IWccResolvedView;
+  image: IWccResolvedImageOptions;
+}
+
+export interface IWccResolvedInteractionRequest {
+  subject: IWccCaptureSubject;
+  view: IWccResolvedView;
+  steps: TWccInteractionStep[];
+  observeMs: number;
+  maxFrames: number;
+  frameQuality: number;
+  finalScreenshot: IWccResolvedImageOptions | null;
+}
+
+const isInteger = (valueArg: unknown): valueArg is number => typeof valueArg === 'number' && Number.isInteger(valueArg);
+
+const requireIntegerIn = (valueArg: unknown, minArg: number, maxArg: number, nameArg: string): number => {
+  if (!isInteger(valueArg) || valueArg < minArg || valueArg > maxArg) {
+    throw new WccCaptureRequestError(`wcctools: ${nameArg} must be a whole number from ${minArg} to ${maxArg}.`);
+  }
+  return valueArg;
+};
+
+const requireText = (valueArg: unknown, maxLengthArg: number, nameArg: string, allowEmptyArg = false): string => {
+  if (typeof valueArg !== 'string' || (!allowEmptyArg && valueArg.trim() === '') || valueArg.length > maxLengthArg) {
+    throw new WccCaptureRequestError(`wcctools: ${nameArg} must be ${allowEmptyArg ? 'a' : 'a non-empty'} string of at most ${maxLengthArg} characters.`);
+  }
+  return valueArg;
+};
+
+const resolveSubject = (subjectArg: unknown): IWccCaptureSubject => {
+  if (typeof subjectArg !== 'object' || subjectArg === null) {
+    throw new WccCaptureRequestError('wcctools: a capture needs a subject: the catalog entry to render.');
+  }
+  const subject = subjectArg as Partial<IWccCaptureSubject>;
+  const resolved: IWccCaptureSubject = {
+    itemName: requireText(subject.itemName, captureLimits.maxSubjectLength, 'the subject\'s itemName'),
+    demoIndex: subject.demoIndex === undefined ? 0 : requireIntegerIn(subject.demoIndex, 0, 1_000, 'the demo index'),
+  };
+  if (subject.sectionName !== undefined) {
+    resolved.sectionName = requireText(subject.sectionName, captureLimits.maxSubjectLength, 'the subject\'s sectionName');
+  }
+  return resolved;
+};
+
+/** Reads a viewport: a named one, or a width in CSS pixels. */
+export const resolveViewportWidth = (viewportArg: unknown): number => {
+  if (viewportArg === undefined) {
+    return captureViewportWidths.desktop;
+  }
+  if (isViewportPreset(viewportArg)) {
+    return captureViewportWidths[viewportArg];
+  }
+  if (isInteger(viewportArg)) {
+    return requireIntegerIn(viewportArg, captureLimits.minWidth, captureLimits.maxWidth, 'the viewport width');
+  }
+  throw new WccCaptureRequestError(
+    `wcctools: the viewport must be one of ${Object.keys(captureViewportWidths).join(', ')} or a width from ${captureLimits.minWidth} to ${captureLimits.maxWidth}.`,
+  );
+};
+
+const resolveView = (requestArg: plugins.interfaces.IWccCaptureView): IWccResolvedView => {
+  const theme = requestArg.theme ?? 'dark';
+  if (theme !== 'dark' && theme !== 'bright') {
+    throw new WccCaptureRequestError('wcctools: the theme must be dark or bright.');
+  }
+  const scale = requestArg.scale ?? 1;
+  if (scale !== 1 && scale !== 2) {
+    throw new WccCaptureRequestError('wcctools: the scale must be 1 or 2.');
+  }
+  return {
+    width: resolveViewportWidth(requestArg.viewport),
+    height: requestArg.height === undefined
+      ? captureLimits.defaultHeight
+      : requireIntegerIn(requestArg.height, captureLimits.minHeight, captureLimits.maxHeight, 'the height'),
+    theme,
+    scale,
+  };
+};
+
+const resolveImageOptions = (
+  optionsArg: { framing?: unknown; format?: unknown; quality?: unknown },
+): IWccResolvedImageOptions => {
+  const framing = optionsArg.framing;
+  if (framing !== undefined && !framings.includes(framing as TWccCaptureFraming)) {
+    throw new WccCaptureRequestError(`wcctools: the framing must be one of ${framings.join(', ')}.`);
+  }
+  const format = optionsArg.format ?? 'png';
+  if (format !== 'png' && format !== 'jpeg') {
+    throw new WccCaptureRequestError('wcctools: the format must be png or jpeg.');
+  }
+  if (format === 'png' && optionsArg.quality !== undefined) {
+    throw new WccCaptureRequestError('wcctools: a quality applies to jpeg only.');
+  }
+  return {
+    framing: framing as TWccCaptureFraming | undefined,
+    format,
+    quality: format === 'jpeg'
+      ? (optionsArg.quality === undefined ? captureLimits.defaultJpegQuality : requireIntegerIn(optionsArg.quality, 1, 100, 'the quality'))
+      : undefined,
+  };
+};
+
+/** Validates a screenshot request and applies its defaults. */
+export const resolveScreenshotRequest = (requestArg: plugins.interfaces.IWccScreenshotRequest): IWccResolvedScreenshotRequest => {
+  if (typeof requestArg !== 'object' || requestArg === null) {
+    throw new WccCaptureRequestError('wcctools: the screenshot request is missing.');
+  }
+  return {
+    subject: resolveSubject(requestArg.subject),
+    view: resolveView(requestArg),
+    image: resolveImageOptions(requestArg),
+  };
+};
+
+const resolveStep = (stepArg: unknown, indexArg: number): TWccInteractionStep => {
+  const name = `step ${indexArg}`;
+  if (typeof stepArg !== 'object' || stepArg === null) {
+    throw new WccCaptureRequestError(`wcctools: ${name} must be an object with an action.`);
+  }
+  const step = stepArg as Record<string, unknown>;
+  const selector = (requiredArg: boolean) => {
+    if (!requiredArg && step.selector === undefined) {
+      return undefined;
+    }
+    return requireText(step.selector, captureLimits.maxSelectorLength, `the selector of ${name}`);
+  };
+  switch (step.action) {
+    case 'click':
+    case 'hover':
+      return { action: step.action, selector: selector(true) };
+    case 'fill':
+      return {
+        action: 'fill',
+        selector: selector(true),
+        text: requireText(step.text, captureLimits.maxTextLength, `the text of ${name}`, true),
+      };
+    case 'press': {
+      const pressStep: TWccInteractionStep = {
+        action: 'press',
+        key: requireText(step.key, captureLimits.maxKeyLength, `the key of ${name}`),
+      };
+      const pressSelector = selector(false);
+      return pressSelector === undefined ? pressStep : { ...pressStep, selector: pressSelector };
+    }
+    case 'waitFor': {
+      const state = step.state ?? 'visible';
+      if (state !== 'visible' && state !== 'hidden') {
+        throw new WccCaptureRequestError(`wcctools: the state of ${name} must be visible or hidden.`);
+      }
+      return { action: 'waitFor', selector: selector(true), state };
+    }
+    case 'wait':
+      return { action: 'wait', ms: requireIntegerIn(step.ms, 0, captureLimits.maxWaitMs, `the time of ${name}`) };
+    default:
+      throw new WccCaptureRequestError(`wcctools: the action of ${name} must be one of click, hover, fill, press, waitFor, wait.`);
+  }
+};
+
+/** Validates an interaction request and applies its defaults. */
+export const resolveInteractionRequest = (requestArg: plugins.interfaces.IWccInteractionRequest): IWccResolvedInteractionRequest => {
+  if (typeof requestArg !== 'object' || requestArg === null) {
+    throw new WccCaptureRequestError('wcctools: the interaction request is missing.');
+  }
+  if (!Array.isArray(requestArg.steps) || requestArg.steps.length > captureLimits.maxSteps) {
+    throw new WccCaptureRequestError(`wcctools: an interaction has a list of at most ${captureLimits.maxSteps} steps.`);
+  }
+  if (requestArg.finalScreenshot !== undefined && (typeof requestArg.finalScreenshot !== 'object' || requestArg.finalScreenshot === null)) {
+    throw new WccCaptureRequestError('wcctools: finalScreenshot must be an object.');
+  }
+  return {
+    subject: resolveSubject(requestArg.subject),
+    view: resolveView(requestArg),
+    steps: requestArg.steps.map((stepArg, indexArg) => resolveStep(stepArg, indexArg)),
+    observeMs: requestArg.observeMs === undefined
+      ? captureLimits.defaultObserveMs
+      : requireIntegerIn(requestArg.observeMs, 0, captureLimits.maxObserveMs, 'observeMs'),
+    maxFrames: requestArg.maxFrames === undefined
+      ? captureLimits.defaultMaxFrames
+      : requireIntegerIn(requestArg.maxFrames, 1, captureLimits.maxMaxFrames, 'maxFrames'),
+    frameQuality: requestArg.frameQuality === undefined
+      ? captureLimits.defaultFrameQuality
+      : requireIntegerIn(requestArg.frameQuality, 1, 100, 'frameQuality'),
+    finalScreenshot: requestArg.finalScreenshot ? resolveImageOptions(requestArg.finalScreenshot) : null,
+  };
+};
+
+const describeEntry = (sectionNameArg: string, entryNameArg: string) => `${sectionNameArg}/${entryNameArg}`;
+
+const listSome = (namesArg: string[]): string => {
+  const shown = namesArg.slice(0, 20).join(', ');
+  return namesArg.length > 20 ? `${shown}, … (${namesArg.length} in all)` : shown;
+};
+
+/**
+ * Resolves a subject to one demo of the catalog: an entry named by its name or its element's tag,
+ * in the named section or, without one, in exactly one section.
+ */
+export const resolveSelection = (
+  manifestArg: plugins.interfaces.IWccCatalogManifest,
+  subjectArg: IWccCaptureSubject,
+): plugins.interfaces.IWccSelection => {
+  const sections = subjectArg.sectionName === undefined
+    ? manifestArg.sections
+    : manifestArg.sections.filter((sectionArg) => sectionArg.name === subjectArg.sectionName);
+  if (sections.length === 0) {
+    throw new WccCaptureRequestError(
+      `wcctools: the catalog has no section "${subjectArg.sectionName}". Sections: ${listSome(manifestArg.sections.map((sectionArg) => sectionArg.name))}.`,
+    );
+  }
+  const wanted = subjectArg.itemName;
+  const matchesName = (entryArg: { name: string; tagName: string | null }) => {
+    return entryArg.name === wanted || (entryArg.tagName !== null && entryArg.tagName === wanted.toLowerCase());
+  };
+  const matches = sections.flatMap((sectionArg) => sectionArg.entries
+    .filter(matchesName)
+    .map((entryArg) => ({ section: sectionArg, entry: entryArg })));
+  if (matches.length === 0) {
+    const withoutDemo = sections.flatMap((sectionArg) => sectionArg.entriesWithoutDemo
+      .filter(matchesName)
+      .map((entryArg) => describeEntry(sectionArg.name, entryArg.name)));
+    if (withoutDemo.length > 0) {
+      throw new WccCaptureRequestError(`wcctools: ${listSome(withoutDemo)} has no demo to capture.`);
+    }
+    const known = sections.flatMap((sectionArg) => sectionArg.entries.map((entryArg) => describeEntry(sectionArg.name, entryArg.name)));
+    throw new WccCaptureRequestError(`wcctools: the catalog has no entry "${wanted}". Entries: ${listSome(known)}.`);
+  }
+  if (matches.length > 1) {
+    throw new WccCaptureRequestError(
+      `wcctools: "${wanted}" names ${matches.length} entries (${listSome(matches.map((matchArg) => describeEntry(matchArg.section.name, matchArg.entry.name)))}); name its section.`,
+    );
+  }
+  const [{ section, entry }] = matches;
+  const demoIndex = subjectArg.demoIndex ?? 0;
+  if (demoIndex >= entry.demoCount) {
+    throw new WccCaptureRequestError(
+      `wcctools: ${describeEntry(section.name, entry.name)} has ${entry.demoCount} demo${entry.demoCount === 1 ? '' : 's'}; demo ${demoIndex} does not exist (demos count from 0).`,
+    );
+  }
+  return { sectionName: section.name, itemName: entry.name, demoIndex };
+};

package/ts/classes.devserver.ts

@@ -2,6 +2,8 @@ import * as plugins from './plugins.js';
 import * as paths from './paths.js';
 import { commitinfo } from './00_commitinfo_data.js';
 import { WccDevApi } from './classes.devapi.js';
+import { WccHostPolicy, defaultListenHost, formatUrlHost } from './classes.hostpolicy.js';
+import { WccCaptureService } from './capture/index.js';
 import { loadShellContent, shellPathPrefix } from './shellcontent.js';
 
 export interface IWccDevServerOptions {
@@ -12,12 +14,23 @@ export interface IWccDevServerOptions {
    * tswatch bundles and watches in it (default: `process.cwd()` when the server is constructed).
    */
   cwd?: string;
+  /**
+   * The interface address to listen on (default `127.0.0.1`, this machine only). `0.0.0.0` or
+   * `::` listen on every interface; the machine's interface addresses are then allowed hosts.
+   */
+  host?: string;
+  /** Further hostnames or addresses the server answers, besides localhost and the listen address. */
+  allowedHosts?: readonly string[];
 }
 
 export interface IWccDevServerAddress {
   port: number;
   /** The shell's address. */
   url: string;
+  /** The interface address the server listens on. */
+  host: string;
+  /** The hostnames the server answers; requests for any other Host are refused. */
+  allowedHosts: string[];
 }
 
 /** tswatch's default port and serve directory, used when the configuration names none. */
@@ -30,6 +43,7 @@ const securityHeaders: plugins.typedserver.ISecurityHeaders = {
   crossOriginEmbedderPolicy: 'require-corp',
 };
 
+/** Every surface takes every hostname: the server-wide Host admission refuses the ones it does not serve. */
 const acceptAnyHostname = () => true;
 
 /**
@@ -39,7 +53,12 @@ const acceptAnyHostname = () => true;
  * - the shell on `/wcctools/` (`/` redirects there) and its routes `/wcctools-route/...`,
  * - the typed API on `/wcctools/typedrequest`, including the bundles' status,
  * - the catalog's preview document and bundle from the tswatch serve directory on every other
- *   path, with live reload that reloads only the preview document.
+ *   path, with live reload that reloads only the preview document,
+ * - captures of single demos in a headless browser (`capture`, also on the typed API).
+ *
+ * It listens on loopback unless told otherwise and admits requests as its `WccHostPolicy`
+ * describes: only the hosts it serves, and state-changing requests and WebSockets only from its
+ * own origin.
  *
  * The server owns no process lifecycle: while it runs, a process shutdown through smartexit's
  * `ProcessLifecycle` stops it. The entry point installs that lifecycle with
@@ -48,6 +67,10 @@ const acceptAnyHostname = () => true;
 export class WccDevServer {
   /** The typed API on `/wcctools/typedrequest`; register further handlers before `start()`. */
   public readonly api = new WccDevApi();
+  /** Screenshots and interaction captures of the served catalog; available while the server runs. */
+  public readonly capture: WccCaptureService;
+  /** Who may talk to the server: the hosts it answers and the origin of its requests. */
+  public readonly hostPolicy: WccHostPolicy;
   /** The project directory everything resolves against. */
   public readonly cwd: string;
   /** The project's tswatch configuration, or the `element` preset; read once, on construction. */
@@ -67,6 +90,9 @@ export class WccDevServer {
     const configHandler = new plugins.tswatch.ConfigHandler(this.cwd);
     this.config = configHandler.loadConfig() ?? this.getElementPreset(configHandler);
     this.tsWatch = new plugins.tswatch.TsWatch({ ...this.config, server: { enabled: false } }, { cwd: this.cwd });
+    this.hostPolicy = new WccHostPolicy({ listenHost: options.host ?? defaultListenHost, allowedHosts: options.allowedHosts });
+    this.capture = new WccCaptureService(this.api.bundleStatus);
+    this.capture.addTypedHandlers(this.api.typedrouter);
   }
 
   /**
@@ -134,8 +160,11 @@ export class WccDevServer {
     // requests until the server stops listening are refused too: the shell backs off
     this.api.bundleStatus.close();
     try {
+      // Captures end and the capture browser closes before the server stops answering its pages
+      await this.capture.close();
       await typedServer?.stop();
     } finally {
+      this.hostPolicy.setPort(null);
       try {
         await this.tsWatch.stop();
       } finally {
@@ -156,7 +185,15 @@ export class WccDevServer {
       projectName: await this.readProjectName(),
     });
     const surfaces = [await this.createShellSurface(), this.createPreviewSurface(serveDir)];
-    const typedServer = new plugins.typedserver.TypedServer({ cors: false, port, surfaces });
+    const typedServer = new plugins.typedserver.TypedServer({
+      cors: false,
+      port,
+      listenHostname: this.hostPolicy.listenHost,
+      // Requests and WebSocket upgrades for a Host the server does not serve are refused
+      requestAdmission: this.hostPolicy.admitHost,
+      websocketAdmission: this.hostPolicy.admitHost,
+      surfaces,
+    });
     this.typedServer = typedServer;
 
     this.api.bundleStatus.open();
@@ -166,7 +203,14 @@ export class WccDevServer {
     await this.tsWatch.start();
     await typedServer.start();
     const boundPort = typedServer.listeningPort ?? port;
-    return { port: boundPort, url: `http://localhost:${boundPort}${shellPathPrefix}/` };
+    this.hostPolicy.setPort(boundPort);
+    this.capture.open(`http://${formatUrlHost(this.hostPolicy.getLocalHost())}:${boundPort}`);
+    return {
+      port: boundPort,
+      url: `http://${formatUrlHost(this.hostPolicy.getDisplayHost())}:${boundPort}${shellPathPrefix}/`,
+      host: this.hostPolicy.listenHost,
+      allowedHosts: [...this.hostPolicy.allowedHostnames],
+    };
   }
 
   private getElementPreset(configHandlerArg: plugins.tswatch.ConfigHandler): plugins.tswatch.ITswatchConfig {
@@ -178,14 +222,8 @@ export class WccDevServer {
   }
 
   /**
-   * The shell: the prebuilt shell bundle and the typed API.
-   *
-   * Seam for side-effecting APIs (assistant, capture, standards fixes): before any handler with
-   * side effects is registered here, the server binds to localhost by default (another interface
-   * only on explicit request), validates the Host header against the addresses it serves instead
-   * of accepting any hostname, and admits typedsocket connections and typed requests only from the
-   * shell's own origin (a `websocketAdmission`/`requestAdmission`), keeping surface mode's strict
-   * authority validation. Until then every handler here is read-only.
+   * The shell: the prebuilt shell bundle and the typed API, whose requests (captures among them)
+   * are admitted only from the server's own origin.
    */
   private async createShellSurface(): Promise<plugins.typedserver.ITypedServerSurface> {
     return {
@@ -198,6 +236,8 @@ export class WccDevServer {
       spaFallback: true,
       httpTypedRouter: this.api.typedrouter,
       typedRequestPath: `${shellPathPrefix}/typedrequest`,
+      requestAdmission: this.hostPolicy.admitRequestOrigin,
+      websocketAdmission: this.hostPolicy.admitWebsocketOrigin,
       noCache: true,
       securityHeaders,
     };
@@ -221,8 +261,10 @@ export class WccDevServer {
       watch: true,
       // Lets the reload client get pushed changes instead of polling
       websocketTypedRouter: new plugins.typedrequest.TypedRouter(),
-      // As tswatch serves catalogs
-      cors: true,
+      requestAdmission: this.hostPolicy.admitRequestOrigin,
+      websocketAdmission: this.hostPolicy.admitWebsocketOrigin,
+      // Shell and preview share one origin, so no other origin may read the catalog
+      cors: false,
       httpHandler: async (contextArg) => {
         if (contextArg.path === '/' && (contextArg.method === 'GET' || contextArg.method === 'HEAD')) {
           return new Response(null, { status: 302, headers: { Location: `${shellPathPrefix}/` } });

package/ts/classes.hostpolicy.ts

@@ -0,0 +1,201 @@
+import * as plugins from './plugins.js';
+
+type TRequestContext = plugins.typedserver.IRequestContext;
+type TAdmissionResult = plugins.typedserver.TRequestAdmissionResult;
+
+/** The interface address `wcctools dev` listens on unless told otherwise. */
+export const defaultListenHost = '127.0.0.1';
+
+/** The hostnames every dev server answers: the loopback names. */
+const loopbackHostnames = ['localhost', '127.0.0.1', '::1'];
+
+const wildcardHosts = new Set(['0.0.0.0', '::']);
+
+/** Methods that never change state, which the Origin check leaves to the Host check alone. */
+const safeMethods = new Set(['GET', 'HEAD', 'OPTIONS']);
+
+/** Canonical form of a hostname: lower case, IPv6 without brackets, no trailing dot. */
+export const normalizeHostname = (hostnameArg: string): string => {
+  let hostname = hostnameArg.trim().toLowerCase();
+  if (hostname.startsWith('[') && hostname.endsWith(']')) {
+    hostname = hostname.slice(1, -1);
+  }
+  if (hostname.endsWith('.') && hostname.length > 1) {
+    hostname = hostname.slice(0, -1);
+  }
+  return hostname;
+};
+
+/** Whether the address is the wildcard address of all interfaces. */
+export const isWildcardHost = (hostArg: string): boolean => wildcardHosts.has(normalizeHostname(hostArg));
+
+/** Whether a peer address is a loopback address (IPv4, IPv6 or IPv4-mapped IPv6). */
+export const isLoopbackAddress = (addressArg: string): boolean => {
+  const address = normalizeHostname(addressArg);
+  return address === '::1' || address.startsWith('127.') || address.startsWith('::ffff:127.');
+};
+
+/** A hostname as it appears in a URL: IPv6 addresses in brackets. */
+export const formatUrlHost = (hostnameArg: string): string => {
+  return hostnameArg.includes(':') ? `[${hostnameArg}]` : hostnameArg;
+};
+
+/** An invalid `--host` or `--allowed-host` value. */
+export class WccHostPolicyError extends Error {
+  constructor(messageArg: string) {
+    super(messageArg);
+    this.name = 'WccHostPolicyError';
+  }
+}
+
+export interface IWccHostPolicyOptions {
+  /** The interface address the server listens on. */
+  listenHost: string;
+  /** Further hostnames or addresses the server answers (`--allowed-host`). */
+  allowedHosts?: readonly string[];
+}
+
+/**
+ * Who may talk to a `wcctools dev` server. The server listens on loopback unless told otherwise
+ * and answers only the hostnames it serves: the loopback names, the address it listens on, the
+ * machine's interface addresses when it listens on all of them, and the hosts allowed explicitly.
+ * Every other Host is refused, which defeats DNS rebinding. Requests that can change state
+ * (any method but GET, HEAD and OPTIONS) and WebSocket connections are further admitted only from
+ * the server's own origin, so other web pages cannot drive the API; a request without an Origin
+ * is admitted only from a loopback peer (local tools, such as the CLI and tests).
+ */
+export class WccHostPolicy {
+  /** The canonical hostnames the server answers. */
+  public readonly allowedHostnames: ReadonlySet<string>;
+  public readonly listenHost: string;
+  private port: number | null = null;
+
+  constructor(optionsArg: IWccHostPolicyOptions) {
+    this.listenHost = WccHostPolicy.parseHost(optionsArg.listenHost);
+    const hostnames = new Set(loopbackHostnames);
+    if (isWildcardHost(this.listenHost)) {
+      for (const address of WccHostPolicy.getInterfaceAddresses()) {
+        hostnames.add(address);
+      }
+    } else {
+      hostnames.add(this.listenHost);
+    }
+    for (const host of optionsArg.allowedHosts ?? []) {
+      hostnames.add(WccHostPolicy.parseHost(host));
+    }
+    this.allowedHostnames = hostnames;
+  }
+
+  /** A hostname or address, as a URL would carry it; anything else is refused. */
+  private static parseHost(hostArg: string): string {
+    const hostname = normalizeHostname(hostArg);
+    let parsed: string | null = null;
+    try {
+      parsed = normalizeHostname(new URL(`http://${formatUrlHost(hostname)}/`).hostname);
+    } catch {
+      parsed = null;
+    }
+    if (!hostname || parsed !== hostname) {
+      throw new WccHostPolicyError(`wcctools: "${hostArg}" is not a hostname or address.`);
+    }
+    return hostname;
+  }
+
+  /** Every address of the machine's network interfaces. */
+  private static getInterfaceAddresses(): string[] {
+    const addresses: string[] = [];
+    for (const interfaceAddresses of Object.values(plugins.os.networkInterfaces())) {
+      for (const interfaceAddress of interfaceAddresses ?? []) {
+        addresses.push(normalizeHostname(interfaceAddress.address));
+      }
+    }
+    return addresses;
+  }
+
+  /** The port the server listens on, once it does: origins are compared against it. */
+  public setPort(portArg: number | null) {
+    this.port = portArg;
+  }
+
+  /**
+   * The host the server's own tools reach it on: the loopback address when it listens on all
+   * interfaces or on loopback, otherwise the address it listens on.
+   */
+  public getLocalHost(): string {
+    if (isWildcardHost(this.listenHost) || isLoopbackAddress(this.listenHost)) {
+      return '127.0.0.1';
+    }
+    return this.listenHost;
+  }
+
+  /** The host shown to the user: `localhost` for a loopback or all-interface server. */
+  public getDisplayHost(): string {
+    if (isWildcardHost(this.listenHost) || isLoopbackAddress(this.listenHost) || this.listenHost === 'localhost') {
+      return 'localhost';
+    }
+    return this.listenHost;
+  }
+
+  /** Server-wide HTTP and WebSocket admission: the Host must be one the server answers. */
+  public readonly admitHost = (contextArg: TRequestContext): TAdmissionResult => {
+    const hostname = normalizeHostname(contextArg.url.hostname);
+    if (this.allowedHostnames.has(hostname)) {
+      return true;
+    }
+    return this.refuse(
+      `wcctools: the dev server does not answer the host "${hostname}". Open it on localhost, or restart it with --allowed-host ${hostname}.`,
+    );
+  };
+
+  /** Surface HTTP admission: a request that can change state must come from the server's origin. */
+  public readonly admitRequestOrigin = (contextArg: TRequestContext): TAdmissionResult => {
+    if (safeMethods.has(contextArg.method)) {
+      return true;
+    }
+    return this.admitOrigin(contextArg);
+  };
+
+  /** Surface WebSocket admission: a connection must come from the server's origin. */
+  public readonly admitWebsocketOrigin = (contextArg: TRequestContext): TAdmissionResult => {
+    return this.admitOrigin(contextArg);
+  };
+
+  /** Whether an Origin header names this server: http, an allowed host and the server's port. */
+  public isOwnOrigin(originArg: string): boolean {
+    if (this.port === null) {
+      return false;
+    }
+    let origin: URL;
+    try {
+      origin = new URL(originArg);
+    } catch {
+      return false;
+    }
+    const port = origin.port === '' ? 80 : Number(origin.port);
+    return origin.protocol === 'http:'
+      && port === this.port
+      && this.allowedHostnames.has(normalizeHostname(origin.hostname));
+  }
+
+  private admitOrigin(contextArg: TRequestContext): TAdmissionResult {
+    const origin = contextArg.headers.get('origin');
+    if (origin === null) {
+      const peer = contextArg.connectionInfo?.remoteAddr ?? 'unknown';
+      if (isLoopbackAddress(peer)) {
+        return true;
+      }
+      return this.refuse('wcctools: requests without an Origin are admitted only from this machine.');
+    }
+    if (this.isOwnOrigin(origin)) {
+      return true;
+    }
+    return this.refuse(`wcctools: requests from the origin "${origin}" are not admitted.`);
+  }
+
+  private refuse(messageArg: string): Response {
+    return new Response(`${messageArg}\n`, {
+      status: 403,
+      headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+    });
+  }
+}