@botiverse/porthole 0.1.3 → 0.1.4

package/src/server/naming.ts

@@ -40,3 +40,44 @@ export function prefixedName(prefix: string): (scope: string) => string {
     return label;
   };
 }
+
+const PREFIX_ENTRY = /^[a-z0-9]([a-z0-9-]{0,61})?\*$/u;
+
+/**
+ * Whether a label is reserved (`ContentDomain.reserved`): a whole label, a prefix ending in `*`
+ * (`p-*`), or the host's own function. Entries are checked once, here; a function that throws
+ * reserves the label (fail closed: the request goes to the host's routes, never served as ours).
+ */
+export function reservedLabels(
+  reserved: readonly string[] | ((label: string) => boolean) | undefined,
+): (label: string) => boolean {
+  if (reserved === undefined) {
+    return () => false;
+  }
+  if (typeof reserved === "function") {
+    return (label) => {
+      try {
+        return reserved(label);
+      } catch {
+        return true;
+      }
+    };
+  }
+  if (!Array.isArray(reserved)) {
+    throw new TypeError("content.reserved: a list of labels and prefixes, or a function");
+  }
+  const whole = new Set<string>();
+  const prefixes: string[] = [];
+  for (const entry of reserved) {
+    if (typeof entry === "string" && PREFIX_ENTRY.test(entry)) {
+      prefixes.push(entry.slice(0, -1));
+    } else if (isHostLabel(entry)) {
+      whole.add(entry);
+    } else {
+      throw new TypeError(
+        `content.reserved: ${JSON.stringify(entry)} is not a lowercase DNS label or a prefix ending in *`,
+      );
+    }
+  }
+  return (label) => whole.has(label) || prefixes.some((prefix) => label.startsWith(prefix));
+}

package/src/server/pages.ts

@@ -93,6 +93,8 @@ const pageHeaders = (frameAncestors: string, connect: boolean) => ({
   "content-security-policy": policy(frameAncestors, connect),
   "referrer-policy": "no-referrer",
   "x-content-type-options": "nosniff",
+  // Content origins are behind tickets: nothing on them is for search engines.
+  "x-robots-tag": "noindex, nofollow",
 });
 
 export function statusPage(

package/src/server/server.ts

@@ -9,7 +9,7 @@ import {
 import type { FrameLocation, InstanceRef, ServedDocument } from "../isolation/types.ts";
 import { sandboxProxyDocument } from "../mcp/proxy.ts";
 import { createKeys, newTicket, ticketId } from "./keys.ts";
-import { isHostLabel } from "./naming.ts";
+import { isHostLabel, reservedLabels } from "./naming.ts";
 import { enterPage, pageScript, SESSION_PATH, statusPage } from "./pages.ts";
 import type { FrameBlock } from "../host/types.ts";
 import { memoryTicketStore } from "./tickets.ts";
@@ -46,6 +46,18 @@ const MAX_SESSION_SECONDS = 30 * 24 * 3_600;
 /** Browsers keep a cookie of up to 4 KB, name and attributes included. */
 const MAX_COOKIE_BYTES = 3_800;
 
+/** A host (and port) as it compares: lowercase, no trailing dot, no default port. */
+function normalHost(value: string, protocol: string): string {
+  const host = value
+    .trim()
+    .toLowerCase()
+    .replace(/\.(?=:\d+$|$)/u, "");
+  const defaultPort = protocol === "https:" ? ":443" : protocol === "http:" ? ":80" : "";
+  return defaultPort !== "" && host.endsWith(defaultPort)
+    ? host.slice(0, -defaultPort.length)
+    : host;
+}
+
 /**
  * What a session cookie carries, signed: the instance, its viewer (or anonymous), the host's
  * opaque subject, and when it stops.
@@ -190,21 +202,14 @@ export function createServer(options: ServerOptions): PortholeServer {
     throw new TypeError("content.port must be a port number");
   }
   const keys = createKeys(options.secret);
-  const reserved = new Set(content.reserved ?? []);
-  for (const label of reserved) {
-    if (!isHostLabel(label)) {
-      throw new TypeError(
-        `content.reserved: ${JSON.stringify(label)} is not a lowercase DNS label`,
-      );
-    }
-  }
+  const isReserved = reservedLabels(content.reserved);
   /** The label a scope is served on: the host's naming, checked, or the keyed default. */
   const nameOf = (scope: string): string => {
     if (content.name === undefined) {
       return keys.label(scope);
     }
     const label = content.name(scope);
-    if (!isHostLabel(label) || reserved.has(label)) {
+    if (!isHostLabel(label) || isReserved(label)) {
       throw new TypeError(
         `content.name gave ${JSON.stringify(label)} for a scope: it must be one lowercase DNS label (a-z 0-9 -, at most 63, not xn--), not reserved`,
       );
@@ -213,7 +218,7 @@ export function createServer(options: ServerOptions): PortholeServer {
   };
   /** Whether a request's label may be one this server named. */
   const ours = (label: string): boolean =>
-    !reserved.has(label) && (content.name === undefined ? LABEL.test(label) : isHostLabel(label));
+    !isReserved(label) && (content.name === undefined ? LABEL.test(label) : isHostLabel(label));
   const secure = content.scheme === "https";
   const defaultPort = secure ? 443 : 80;
   const portPart =
@@ -520,6 +525,7 @@ export function createServer(options: ServerOptions): PortholeServer {
       "cache-control": "no-store",
       "referrer-policy": "no-referrer",
       "x-content-type-options": "nosniff",
+      "x-robots-tag": "noindex, nofollow",
     });
   }
 
@@ -686,8 +692,20 @@ export function createServer(options: ServerOptions): PortholeServer {
     }
   }
 
-  /** The label a request is for: null when it isn't under the content domain at all. */
-  function labelOf(request: Request): { readonly url: URL; readonly label: string } | null {
+  const underDomain = (host: string): boolean => host === domain || host.endsWith(`.${domain}`);
+
+  /**
+   * The label a request is for: null when it isn't under the content domain at all (or is in a
+   * reserved namespace), "mismatch" when its Host header names another host than its URL does
+   * and either is under the content domain. A Node adapter may build the URL from an
+   * absolute-form request target (`GET http://other/…`) while a host routes by the Host header
+   * (and a cache keys on it): the two must agree before anything is served. A Host that is a
+   * local server address (an IP literal, `localhost`), as a test runner or a dev proxy sends, is
+   * not a name and isn't compared.
+   */
+  function labelOf(
+    request: Request,
+  ): { readonly url: URL; readonly label: string } | "mismatch" | null {
     let url: URL;
     try {
       url = new URL(request.url);
@@ -695,13 +713,27 @@ export function createServer(options: ServerOptions): PortholeServer {
       return null;
     }
     const host = url.hostname.toLowerCase().replace(/\.$/u, "");
-    if (host !== domain && !host.endsWith(`.${domain}`)) {
+    const header = request.headers.get("host");
+    if (header !== null) {
+      const named = normalHost(header, url.protocol);
+      const name = named.replace(/:\d+$/u, "");
+      const local = name === "localhost" || /^[\d.]+$/u.test(name) || name.startsWith("[");
+      if (
+        !local &&
+        named !== normalHost(url.host, url.protocol) &&
+        (underDomain(host) || underDomain(name))
+      ) {
+        return "mismatch";
+      }
+    }
+    if (!underDomain(host)) {
       return null;
     }
     const label = host.slice(0, Math.max(0, host.length - domain.length - 1));
-    // A reserved label is another server's namespace (`f` for `<x>.f.<domain>`): it and the names
-    // under it go to the host's own routes. Any other deeper name is ours to refuse.
-    if (reserved.has(label.split(".").at(-1) ?? "")) {
+    // A reserved label is another server's namespace (`f` for `<x>.f.<domain>`), or the host's
+    // own: it and the names under it go to the host's own routes. Any other deeper name is ours
+    // to refuse.
+    if (isReserved(label.split(".").at(-1) ?? "")) {
       return null;
     }
     return { url, label };
@@ -779,7 +811,7 @@ export function createServer(options: ServerOptions): PortholeServer {
 
     async access(request) {
       const at = labelOf(request);
-      if (at === null || !ours(at.label)) {
+      if (at === null || at === "mismatch" || !ours(at.label)) {
         return null;
       }
       const access = accessOf(request, at.label, null);
@@ -791,8 +823,16 @@ export function createServer(options: ServerOptions): PortholeServer {
       if (at === null) {
         return null;
       }
-      const { url, label } = at;
       const method = request.method.toUpperCase();
+      if (at === "mismatch") {
+        return page(
+          400,
+          "Bad request",
+          "The request's Host header and its URL name different hosts.",
+          method,
+        );
+      }
+      const { url, label } = at;
       try {
         if (!ours(label)) {
           return page(404, "Nothing here", "This address names no content.", method);
@@ -815,7 +855,8 @@ export function createServer(options: ServerOptions): PortholeServer {
         if (document?.[1] !== undefined) {
           return await serveDocument(request, url, label, document[1]);
         }
-        if (url.pathname.startsWith(PREFIX)) {
+        // Without an upstream, only Porthole's own paths are served here: any other is nothing.
+        if (url.pathname.startsWith(PREFIX) || options.upstream === undefined) {
           return page(404, "Nothing here", "This address names no content.", method);
         }
         return await serveApp(request, label);

package/src/server/types.ts

@@ -19,10 +19,13 @@ export interface ContentDomain {
    */
   readonly name?: (scope: string) => string;
   /**
-   * Labels this server never serves or names (another server's namespace under the same domain,
-   * `f` for `<instance>.f.<domain>`, or `www`). Requests for them get null (the host's routes).
+   * Labels this server never serves or names: another server's namespace under the same domain
+   * (`f` for `<instance>.f.<domain>`, `www`), or the host's own (`p-*`: every label starting
+   * `p-`). Each entry is a whole label, or a prefix ending in `*`; or a function that says
+   * whether a label is reserved. Requests for them, and for the names under them, get null (the
+   * host's routes), so a host routes them without wrapping `handle`.
    */
-  readonly reserved?: readonly string[];
+  readonly reserved?: readonly string[] | ((label: string) => boolean);
 }
 
 /**

package/src/shell/annotate.ts

@@ -369,6 +369,9 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
         const root = ensureLayer();
         const parts = [];
         const style = createElement.call(document, "style");
+        if (nonce !== "") {
+          style.nonce = nonce;
+        }
         style.textContent = STYLE;
         parts.push(style);
         const flashOn = Date.now() < flashUntil;
@@ -439,20 +442,41 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
       let anchorTimer = 0;
       let deadline = 0;
       let reportAll = false;
+      // Nothing is reported before the content is in place (an empty shell would orphan every
+      // mark), nor before a run of changes settles; a focus asked for meanwhile waits for it.
+      let waitingForContent = false;
+      let pendingFocus = null;
+      const settling = () => anchorTimer !== 0 || waitingForContent || marks.some((mark) => mark.state === null);
       const scheduleAnchor = (all) => {
         if (all) {
           reportAll = true;
         }
+        if (!contentIsIn()) {
+          if (!waitingForContent) {
+            waitingForContent = true;
+            whenContentIsIn(() => {
+              waitingForContent = false;
+              scheduleAnchor(false);
+            });
+          }
+          return;
+        }
         const now = Date.now();
         if (deadline === 0) {
           deadline = now + 1000;
         }
         clearTimeout(anchorTimer);
         anchorTimer = setTimeout(() => {
+          anchorTimer = 0;
           deadline = 0;
           const every = reportAll;
           reportAll = false;
           anchorAll(every);
+          if (pendingFocus !== null) {
+            const id = pendingFocus;
+            pendingFocus = null;
+            focus(id);
+          }
         }, Math.max(0, Math.min(150, deadline - now)));
       };
       new MutationObserver((records) => {
@@ -475,6 +499,12 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
         if (!mark) {
           return;
         }
+        if (settling()) {
+          // Where it is isn't known yet: focus it once anchoring has settled, then say where.
+          pendingFocus = id;
+          active = id;
+          return;
+        }
         active = id;
         if (mark.found !== null) {
           const rect = rectOf(mark.found);
@@ -657,6 +687,7 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
             focus(String(params.id));
             break;
           case M.clear:
+            pendingFocus = null;
             marks = [];
             active = null;
             draw();

package/src/shell/document.ts

@@ -25,8 +25,17 @@ export interface ShellDocumentOptions {
    * both apply, and the stricter wins.
    */
   readonly cspMeta?: boolean;
+  /**
+   * The embedding page's CSP nonce, where its `script-src` is nonce-based (P054): a `srcdoc` frame
+   * inherits the embedding page's policy, so the shell's script and style carry it, and so does
+   * every script the shell runs for the content. The frame can read it.
+   */
+  readonly nonce?: string;
 }
 
+/** A CSP nonce: base64 or base64url characters, 8 to 256 of them. */
+const NONCE = /^[A-Za-z0-9+/_=-]{8,256}$/u;
+
 const escapeAttribute = (value: string): string =>
   value.replace(/&/gu, "&amp;").replace(/"/gu, "&quot;").replace(/</gu, "&lt;");
 
@@ -86,6 +95,10 @@ export function shellDocument(plan: ShellPlan, csp: string, options: ShellDocume
       throw new TypeError(`shellDocument: ${problem}`);
     }
   }
+  if (options.nonce !== undefined && !NONCE.test(options.nonce)) {
+    throw new TypeError("shellDocument: a nonce is 8 to 256 base64 characters");
+  }
+  const nonce = options.nonce === undefined ? "" : ` nonce="${options.nonce}"`;
   // The annotation runtime only where it is declared; spliced in before the plan, which may carry
   // any text (a document) and must not be searched.
   const runtime = SHELL_RUNTIME.replace("__ANNOTATE__", () =>
@@ -113,13 +126,13 @@ export function shellDocument(plan: ShellPlan, csp: string, options: ShellDocume
 ${head.join("\n")}
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>${escapeText(options.title ?? "Content")}</title>
-<style>
+<style${nonce}>
 ${BASE_STYLE}
 </style>
 </head>
 <body>
 <div id="porthole-root"></div>
-<script>${runtime}</script>
+<script${nonce}>${runtime}</script>
 </body>
 </html>
 `;

package/src/shell/runtime.ts

@@ -31,6 +31,9 @@
 export const SHELL_RUNTIME = String.raw`(() => {
   "use strict";
   const plan = __PLAN__;
+  // The embedding page's nonce, where it gave one (a srcdoc frame inherits its policy): every
+  // script the shell runs for the content carries it.
+  const nonce = document.currentScript && document.currentScript.nonce ? document.currentScript.nonce : "";
   const declared = (name) => Object.prototype.hasOwnProperty.call(plan.capabilities, name);
   // Fixed in place: content can neither restore what is removed nor replace what is wrapped.
   const lock = (target, name, value) => {
@@ -485,6 +488,9 @@ export const SHELL_RUNTIME = String.raw`(() => {
       }
       // A script made by a script is async unless told otherwise: keep the page's order.
       live.async = script.hasAttribute("async");
+      if (nonce !== "") {
+        live.nonce = nonce;
+      }
       live.textContent = script.textContent;
       const external = live.hasAttribute("src") && !live.async && live.type !== "module";
       const loaded = external
@@ -509,6 +515,27 @@ export const SHELL_RUNTIME = String.raw`(() => {
     window.dispatchEvent(new Event("load"));
   };
 
+  // Whether the content is in place: a fragment or page the shell draws, once drawn whole; a
+  // view the plan carries, once rendered; a view that is the document itself, from the start.
+  const contentHooks = [];
+  let contentIn = typeof plan.document !== "string" && plan.protocol !== "shell";
+  const contentIsIn = () => contentIn;
+  const whenContentIsIn = (run) => {
+    if (contentIn) {
+      run();
+    } else {
+      contentHooks.push(run);
+    }
+  };
+  const contentArrived = () => {
+    if (!contentIn) {
+      contentIn = true;
+      for (const run of contentHooks.splice(0)) {
+        run();
+      }
+    }
+  };
+
   // A fragment takes the person's scheme; a whole document only if it declares that it supports
   // both (or the config says always), else it shows as its author styled it (P039).
   let lastContext = null;
@@ -544,6 +571,7 @@ export const SHELL_RUNTIME = String.raw`(() => {
     schemeFollows();
     await runScripts(scripts);
     announceLoaded();
+    contentArrived();
   };
 
   // A document the plan carries (a served page, an MCP Apps view) is rendered once the shell's own
@@ -672,7 +700,10 @@ export const SHELL_RUNTIME = String.raw`(() => {
   window.addEventListener("error", (event) => {
     const error = event.error;
     const where = event.lineno ? " (line " + event.lineno + ")" : "";
-    report(error && error.stack ? String(error.stack).split("\n").slice(0, 3).join(" ") : event.message + where);
+    // V8's stack starts with the message; WebKit's and Firefox's don't, so it goes first there.
+    const stack = error && error.stack ? String(error.stack).split("\n").slice(0, 3).join(" ") : "";
+    const said = error && error.message !== undefined ? String(error.name || "Error") + ": " + String(error.message) : event.message;
+    report(stack === "" ? said + where : stack.indexOf(String(error.message)) === -1 ? said + " " + stack : stack);
   });
   window.addEventListener("unhandledrejection", (event) => {
     const reason = event.reason;
@@ -804,6 +835,7 @@ export const SHELL_RUNTIME = String.raw`(() => {
     schedule();
     await runScripts(scripts);
     announceLoaded();
+    contentArrived();
     schedule();
   };