@botiverse/porthole 0.1.8 → 0.2.0

package/src/node/index.ts

@@ -0,0 +1,221 @@
+/**
+ * `@botiverse/porthole/node`: the host kit on Node's own HTTP server (P066). Every request and
+ * WebSocket whose Host is under the content domain is Porthole's; the app's reserved labels
+ * (previews) and its own hosts go to the app's listeners.
+ *
+ *   const content = createContentHost({ …, health: { probe: nodeProbe() } });
+ *   const porthole = nodeHost(content, { request: appListener, upgrade: appUpgrade });
+ *   const server = http.createServer(porthole.request);
+ *   server.on("upgrade", porthole.upgrade);
+ *   server.listen(8080, () => content.start());
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import type { LookupFunction } from "node:net";
+import type { Duplex } from "node:stream";
+import { Readable } from "node:stream";
+import type { ContentHost, HealthProbe } from "../server/host.ts";
+import type { Access } from "../server/types.ts";
+
+type RequestListener = (request: IncomingMessage, response: ServerResponse) => void;
+type UpgradeListener = (request: IncomingMessage, socket: Duplex, head: Buffer) => void;
+
+export interface NodeHostOptions {
+  /** The app's own request listener (Express, Hono's `getRequestListener`, a router). */
+  readonly request: RequestListener;
+  /** The app's own upgrade listener (its WebSockets, and its reserved labels' sockets). */
+  readonly upgrade?: UpgradeListener;
+  /** A url-mode app's WebSocket, once its cookie checks out (`ContentHost.access`). */
+  readonly appSocket?: (
+    access: Access,
+    request: IncomingMessage,
+    socket: Duplex,
+    head: Buffer,
+  ) => void;
+}
+
+export interface NodeHost {
+  readonly request: RequestListener;
+  readonly upgrade: UpgradeListener;
+}
+
+/** The Node request as a fetch `Request`: an absolute-form target kept as it came (P056). */
+export function toRequest(request: IncomingMessage, scheme: "https" | "http"): Request {
+  const headers = new Headers();
+  for (const [name, value] of Object.entries(request.headers)) {
+    for (const each of Array.isArray(value) ? value : value === undefined ? [] : [value]) {
+      headers.append(name, each);
+    }
+  }
+  const target = request.url ?? "/";
+  const url = target.startsWith("/")
+    ? `${scheme}://${request.headers.host ?? "localhost"}${target}`
+    : target;
+  const method = request.method ?? "GET";
+  const body =
+    method === "GET" || method === "HEAD" ? null : (Readable.toWeb(request) as ReadableStream);
+  return new Request(url, { method, headers, body, duplex: "half" } as RequestInit);
+}
+
+/** Writes a fetch `Response` to a Node response, cookies one header each. */
+export async function sendResponse(response: ServerResponse, answer: Response): Promise<void> {
+  const headers: Record<string, string | string[]> = {};
+  for (const [name, value] of answer.headers) {
+    if (name !== "set-cookie") {
+      headers[name] = value;
+    }
+  }
+  const cookies = answer.headers.getSetCookie();
+  if (cookies.length > 0) {
+    headers["set-cookie"] = cookies;
+  }
+  response.writeHead(answer.status, headers);
+  if (answer.body === null) {
+    response.end();
+    return;
+  }
+  for await (const chunk of answer.body as unknown as AsyncIterable<Uint8Array>) {
+    response.write(chunk);
+  }
+  response.end();
+}
+
+/** Whether a Node request's Host (or absolute-form target) is under the content domain. */
+function forContent<V>(content: ContentHost<V>, request: IncomingMessage): boolean {
+  const domain = content.domain;
+  if (domain === null) {
+    return false;
+  }
+  const host = request.headers.host ?? "";
+  let target = "";
+  try {
+    target = (request.url ?? "/").startsWith("/") ? "" : new URL(request.url ?? "").hostname;
+  } catch {
+    target = "";
+  }
+  return domain.isContentHost(host) || (target !== "" && domain.isContentHost(target));
+}
+
+/** Refuses a WebSocket on the content domain with a plain 404, and closes it. */
+function refuseSocket(socket: Duplex): void {
+  socket.end("HTTP/1.1 404 Not Found\r\nConnection: close\r\nContent-Length: 0\r\n\r\n");
+}
+
+export function nodeHost<V>(content: ContentHost<V>, app: NodeHostOptions): NodeHost {
+  const scheme = () => content.domain?.scheme ?? "http";
+  return {
+    request(request, response) {
+      if (!forContent(content, request)) {
+        app.request(request, response);
+        return;
+      }
+      content.fetch(toRequest(request, scheme())).then(
+        (answer) => {
+          if (answer === null) {
+            // A label the app routes itself.
+            app.request(request, response);
+            return;
+          }
+          return sendResponse(response, answer);
+        },
+        () => {
+          if (!response.headersSent) {
+            response.writeHead(500, { "content-type": "text/plain; charset=utf-8" });
+          }
+          response.end("Content couldn't be served.");
+        },
+      );
+    },
+    upgrade(request, socket, head) {
+      if (!forContent(content, request)) {
+        if (app.upgrade === undefined) {
+          refuseSocket(socket);
+        } else {
+          app.upgrade(request, socket, head);
+        }
+        return;
+      }
+      const asked = toRequest(request, scheme());
+      // A reserved label's socket is the app's.
+      if (!content.owns(asked)) {
+        if (app.upgrade === undefined) {
+          refuseSocket(socket);
+        } else {
+          app.upgrade(request, socket, head);
+        }
+        return;
+      }
+      const appSocket = app.appSocket;
+      if (appSocket === undefined) {
+        refuseSocket(socket);
+        return;
+      }
+      content.access(asked).then(
+        (access) => {
+          if (access === null) {
+            refuseSocket(socket);
+          } else {
+            appSocket(access, request, socket, head);
+          }
+        },
+        () => refuseSocket(socket),
+      );
+    },
+  };
+}
+
+/** Resolves every `*.localhost` name to loopback, as browsers do (Node's resolver may not). */
+const loopbackLookup: LookupFunction = (hostname, options, callback) => {
+  const all = typeof options === "object" && options !== null && options.all === true;
+  if (all) {
+    (
+      callback as unknown as (error: null, addresses: { address: string; family: number }[]) => void
+    )(null, [{ address: "127.0.0.1", family: 4 }]);
+    return;
+  }
+  callback(null, "127.0.0.1", 4);
+};
+
+/**
+ * The health gate's probe on Node: a GET over the real network (DNS, the edge, TLS with Node's
+ * own certificate checks), `*.localhost` resolved to loopback, redirects not followed, at most 4 KB
+ * of the answer read.
+ */
+export function nodeProbe(): HealthProbe {
+  return (url, timeoutMs) =>
+    new Promise((resolve, reject) => {
+      const target = new URL(url);
+      const local = target.hostname === "localhost" || target.hostname.endsWith(".localhost");
+      const send = target.protocol === "https:" ? httpsRequest : httpRequest;
+      const asked = send(
+        target,
+        {
+          method: "GET",
+          headers: { accept: "application/json" },
+          timeout: timeoutMs,
+          ...(local ? { lookup: loopbackLookup } : {}),
+        },
+        (response) => {
+          let body = "";
+          response.setEncoding("utf8");
+          response.on("data", (chunk: string) => {
+            if (body.length < 4_096) {
+              body += chunk;
+            }
+          });
+          response.on("end", () =>
+            resolve({ status: response.statusCode ?? 0, body: body.slice(0, 4_096) }),
+          );
+          response.on("error", reject);
+        },
+      );
+      asked.on("timeout", () => asked.destroy(new Error(`no answer within ${timeoutMs / 1000} s`)));
+      asked.on("error", (error: NodeJS.ErrnoException) =>
+        reject(
+          new Error(error.code === undefined ? error.message : `${error.code} ${error.message}`),
+        ),
+      );
+      asked.end();
+    });
+}

package/src/platform/web.ts

@@ -1,7 +1,15 @@
 import type { ColorScheme } from "../config/schema.ts";
+import { FRAME_STATUS_METHOD } from "../isolation/types.ts";
 import { postMessageTransport } from "../transport/post-message.ts";
 import type { PlatformHost, Surface, SurfaceSpec } from "./types.ts";
 
+/** A frame-status message (`porthole/notifications/frame-status`), by its method alone. */
+const isFrameStatus = (data: unknown): boolean =>
+  data !== null &&
+  typeof data === "object" &&
+  (data as { jsonrpc?: unknown }).jsonrpc === "2.0" &&
+  (data as { method?: unknown }).method === FRAME_STATUS_METHOD;
+
 /**
  * The web platform: an `<iframe>` whose policy attributes are set before its document is given,
  * talking over `postMessage`. Its first load is the document it was given; any later load is the
@@ -54,7 +62,17 @@ export const webPlatform: PlatformHost = {
     container.append(frame);
 
     const view = container.ownerDocument.defaultView ?? window;
-    const transport = postMessageTransport(() => frame.contentWindow, origin, view);
+    // A served frame may pass through the host's own pages (a redirect entry's, P068): what they
+    // say of the frame's status is heard too, and nothing else from there.
+    const own = view.origin;
+    const transport = postMessageTransport(
+      () => frame.contentWindow,
+      origin,
+      view,
+      origin === "null" || own === "null" || own === origin
+        ? undefined
+        : { origin: own, accept: isFrameStatus },
+    );
     return {
       transport,
       element: frame,

package/src/server/domain.ts

@@ -0,0 +1,158 @@
+import { maybeSameSite, parseOrigin } from "../isolation/served.ts";
+import type { ContentDomain } from "./types.ts";
+
+/**
+ * A content domain from deployment settings (P066): `content.example.com`, `content.localhost:8790`
+ * or `https://content.example.com`, parsed, and checked against the app's own origins. Porthole
+ * never serves a content domain that holds an app origin or may share its site: the host kit
+ * either throws at startup or (with its opaque fallback) reports it as permanently unhealthy.
+ */
+
+export interface ContentDomainInfo {
+  /** The registrable domain content is served under (`content.example.com`). */
+  readonly domain: string;
+  /** `http` only on loopback (`localhost`, `*.localhost`). */
+  readonly scheme: "https" | "http";
+  /** A port other than the scheme's default. */
+  readonly port?: number;
+  /** The frame source every content origin matches (`https://*.content.example.com`). */
+  readonly source: string;
+  /** The origin a label is served on. */
+  originOf(label: string): string;
+  /** Whether a host (or hostname) is under the content domain (the apex included). */
+  isContentHost(host: string): boolean;
+  /** The part of a hostname under the content domain (`a-1`, `x.f`), or null. */
+  labelOf(host: string): string | null;
+}
+
+export type ContentDomainProblem = "invalid" | "clash" | "same-site";
+
+/** Why a content domain can't be served; `code` says which rule (P066). */
+export class ContentDomainError extends Error {
+  readonly code: ContentDomainProblem;
+
+  constructor(code: ContentDomainProblem, message: string) {
+    super(message);
+    this.name = "ContentDomainError";
+    this.code = code;
+  }
+}
+
+const HOST = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$/u;
+const LOOPBACK = (host: string) => host === "localhost" || host.endsWith(".localhost");
+const IPV4 = /^\d{1,3}(\.\d{1,3}){3}$/u;
+
+/** A hostname as it compares: lowercase, no port, no trailing dot. */
+export function hostnameOf(host: string): string {
+  const lower = host.trim().toLowerCase();
+  const bare = lower.startsWith("[")
+    ? lower.replace(/(\])(:\d+)?$/u, "$1")
+    : lower.replace(/:\d+$/u, "");
+  return bare.replace(/\.$/u, "");
+}
+
+/**
+ * Parses a content domain. `null` for an empty setting (content off). Throws a
+ * `ContentDomainError` for one that isn't a domain, or that holds or may share a site with one of
+ * `appOrigins` (the clash rules, named in the message).
+ */
+export function contentDomain(
+  input: string | null | undefined,
+  options: { readonly appOrigins: readonly string[] },
+): ContentDomainInfo | null {
+  const raw = (input ?? "").trim().toLowerCase().replace(/\/+$/u, "");
+  if (raw === "") {
+    return null;
+  }
+  const match = /^(?:(https?):\/\/)?([^/:]+)(?::(\d{1,5}))?$/u.exec(raw);
+  const host = match?.[2]?.replace(/^\.+|\.+$/gu, "") ?? "";
+  if (
+    match === null ||
+    !HOST.test(host) ||
+    IPV4.test(host) ||
+    (!host.includes(".") && host !== "localhost")
+  ) {
+    throw new ContentDomainError(
+      "invalid",
+      `The content domain ${JSON.stringify(input)} isn't a domain: give host[:port] (content.example.com, content.localhost:8790)`,
+    );
+  }
+  const loopback = LOOPBACK(host);
+  const scheme =
+    match[1] === undefined ? (loopback ? "http" : "https") : (match[1] as "http" | "https");
+  if (scheme === "http" && !loopback) {
+    throw new ContentDomainError(
+      "invalid",
+      `The content domain ${host} is served over http, which only loopback may use: serve it over https`,
+    );
+  }
+  const portNumber = match[3] === undefined ? undefined : Number(match[3]);
+  if (portNumber !== undefined && (portNumber < 1 || portNumber > 65_535)) {
+    throw new ContentDomainError("invalid", `The content domain's port ${match[3]} isn't a port`);
+  }
+  const port = portNumber === (scheme === "https" ? 443 : 80) ? undefined : portNumber;
+  const portPart = port === undefined ? "" : `:${port}`;
+  const info: ContentDomainInfo = {
+    domain: host,
+    scheme,
+    ...(port === undefined ? {} : { port }),
+    source: `${scheme}://*.${host}${portPart}`,
+    originOf: (label) => `${scheme}://${label}.${host}${portPart}`,
+    isContentHost: (each) => {
+      const name = hostnameOf(each);
+      return name === host || name.endsWith(`.${host}`);
+    },
+    labelOf: (each) => {
+      const name = hostnameOf(each);
+      return name.endsWith(`.${host}`) ? name.slice(0, -host.length - 1) : null;
+    },
+  };
+  const problem = clashOf(info, options.appOrigins);
+  if (problem !== null) {
+    throw problem;
+  }
+  return info;
+}
+
+/** The first clash between a content domain and the app's origins, as an error; null if none. */
+export function clashOf(
+  info: ContentDomainInfo,
+  appOrigins: readonly string[],
+): ContentDomainError | null {
+  // A label of the content domain, as a scope's would be: what "same site" is judged against.
+  const sample = `a1b2c3d4e5f6g7h8i9j0k1l2.${info.domain}`;
+  for (const origin of appOrigins) {
+    // A desktop app's own scheme (ferry://app) is never the same site as web content.
+    const parsed = parseOrigin(origin);
+    if (parsed === null) {
+      continue;
+    }
+    if (info.isContentHost(parsed.host)) {
+      return new ContentDomainError(
+        "clash",
+        `The content domain ${info.domain} holds the app's own origin ${origin}: content there could read the app's cookies and storage. Serve content from a domain the app uses for nothing else`,
+      );
+    }
+    if (maybeSameSite(parsed.host, sample)) {
+      return new ContentDomainError(
+        "same-site",
+        `The content domain ${info.domain} may be the same site as the app's origin ${origin}: serve content from a registrable domain the app uses for nothing else`,
+      );
+    }
+  }
+  return null;
+}
+
+/** The `ContentDomain` `createServer` takes, from parsed settings. */
+export function serverDomain(
+  info: ContentDomainInfo,
+  naming: Pick<ContentDomain, "name" | "reserved">,
+): ContentDomain {
+  return {
+    domain: info.domain,
+    scheme: info.scheme,
+    ...(info.port === undefined ? {} : { port: info.port }),
+    ...(naming.name === undefined ? {} : { name: naming.name }),
+    ...(naming.reserved === undefined ? {} : { reserved: naming.reserved }),
+  };
+}