@botiverse/porthole 0.1.3 → 0.1.5

package/dist/server/server.js

@@ -2,7 +2,7 @@ import { compile } from "../compile/compile.js";
 import { hostOriginProblem, maybeSameSite, originMatchesSource, parseOrigin, } from "../isolation/served.js";
 import { sandboxProxyDocument } from "../mcp/proxy.js";
 import { createKeys, newTicket, ticketId } from "./keys.js";
-import { isHostLabel } from "./naming.js";
+import { isHostLabel, reservedLabels } from "./naming.js";
 import { enterPage, pageScript, SESSION_PATH, statusPage } from "./pages.js";
 import { memoryTicketStore } from "./tickets.js";
 /**
@@ -26,6 +26,17 @@ const DEFAULT_SESSION_SECONDS = 3_600;
 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, protocol) {
+    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;
+}
 const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
 /** Which configs a kind of served document may be served under. */
 const MODES = {
@@ -44,6 +55,10 @@ function mergeEgress(base, extra) {
             merged[kind] = origins;
         }
     }
+    // What the host's config opens to any https site stays; a view can't ask for it (P059).
+    if (base.anyHttps !== undefined) {
+        merged.anyHttps = base.anyHttps;
+    }
     return merged;
 }
 /** `instance` with only the fields Porthole reads, each checked: what a ticket and cookie carry. */
@@ -148,25 +163,20 @@ export function createServer(options) {
         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) => {
         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`);
         }
         return label;
     };
     /** Whether a request's label may be one this server named. */
-    const ours = (label) => !reserved.has(label) && (content.name === undefined ? LABEL.test(label) : isHostLabel(label));
+    const ours = (label) => !isReserved(label) && (content.name === undefined ? LABEL.test(label) : isHostLabel(label));
     const secure = content.scheme === "https";
     const defaultPort = secure ? 443 : 80;
     const portPart = content.port === undefined || content.port === defaultPort ? "" : `:${content.port}`;
@@ -431,6 +441,7 @@ export function createServer(options) {
             "cache-control": "no-store",
             "referrer-policy": "no-referrer",
             "x-content-type-options": "nosniff",
+            "x-robots-tag": "noindex, nofollow",
         });
     }
     async function serveDocument(request, url, label, key) {
@@ -563,7 +574,16 @@ export function createServer(options) {
             return page(502, "The app didn't answer", "Its server couldn't be reached.", method);
         }
     }
-    /** The label a request is for: null when it isn't under the content domain at all. */
+    const underDomain = (host) => 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) {
         let url;
         try {
@@ -573,13 +593,25 @@ export function createServer(options) {
             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 };
@@ -639,7 +671,7 @@ export function createServer(options) {
         },
         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);
@@ -650,8 +682,11 @@ export function createServer(options) {
             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);
@@ -673,7 +708,8 @@ export function createServer(options) {
                 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/dist/server/types.d.ts

@@ -18,10 +18,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);
 }
 /**
  * Who may open an instance, decided by the host before it calls `issue`: a viewer the host

package/dist/shell/annotate.js

@@ -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/dist/shell/document.d.ts

@@ -21,6 +21,12 @@ 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;
 }
 /**
  * The frame's document: its policy first, then the base styles, an empty root, and the runtime.

package/dist/shell/document.js

@@ -1,6 +1,8 @@
 import { hostOriginProblem } from "../isolation/served.js";
 import { ANNOTATE_RUNTIME } from "./annotate.js";
 import { SHELL_RUNTIME } from "./runtime.js";
+/** A CSP nonce: base64 or base64url characters, 8 to 256 of them. */
+const NONCE = /^[A-Za-z0-9+/_=-]{8,256}$/u;
 const escapeAttribute = (value) => value.replace(/&/gu, "&amp;").replace(/"/gu, "&quot;").replace(/</gu, "&lt;");
 const escapeText = (value) => value.replace(/&/gu, "&amp;").replace(/</gu, "&lt;").replace(/>/gu, "&gt;");
 /** JSON that is safe inside a `<script>`: no `</script>`, no `<!--`. */
@@ -53,6 +55,10 @@ export function shellDocument(plan, csp, options) {
             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__", () => plan.capabilities.annotate === undefined ? "" : ANNOTATE_RUNTIME).replace("__PLAN__", () => scriptJson({
@@ -75,13 +81,13 @@ export function shellDocument(plan, csp, options) {
 ${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/dist/shell/runtime.js

@@ -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
@@ -579,12 +607,16 @@ export const SHELL_RUNTIME = String.raw `(() => {
   const notify = (method, params) => send({ method, params });
 
   const themeNames = new Set(plan.themeVariables);
+  // What the content was last told of (its scheme and values): the theme it starts with is no
+  // change, and a host context that changes neither (a host re-sending it) is none either.
+  let announced = null;
   const applyTheme = (context) => {
     if (context === null || typeof context !== "object") {
       return;
     }
     // The spec's variables, and Porthole's own beside them (its own-prefixed field).
     const own = context["porthole/styles"];
+    const applied = [];
     for (const variables of [context.styles && context.styles.variables, own && own.variables]) {
       if (variables === null || typeof variables !== "object") {
         continue;
@@ -593,12 +625,21 @@ export const SHELL_RUNTIME = String.raw `(() => {
         const value = variables[name];
         if (themeNames.has(name) && typeof value === "string") {
           document.documentElement.style.setProperty(name, value);
+          applied.push(name + ":" + value);
         }
       }
     }
     lastContext = context;
     schemeFollows();
-    window.dispatchEvent(new CustomEvent(plan.themeEvent, { detail: { theme: context.theme } }));
+    const now = JSON.stringify([context.theme, applied.sort()]);
+    if (announced === null) {
+      announced = now;
+      return;
+    }
+    if (now !== announced) {
+      announced = now;
+      window.dispatchEvent(new CustomEvent(plan.themeEvent, { detail: { theme: context.theme } }));
+    }
   };
 
   // No size before there is something to size: an empty shell's height would make the host
@@ -672,7 +713,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 +848,7 @@ export const SHELL_RUNTIME = String.raw `(() => {
     schedule();
     await runScripts(scripts);
     announceLoaded();
+    contentArrived();
     schedule();
   };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botiverse/porthole",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "A host-side sandbox for agent-made HTML: isolation, egress hardening, a themed shell, gated host functions, and the agent manual, from one config.",
   "license": "Apache-2.0",
   "files": [

package/src/compile/policy.ts

@@ -1,5 +1,5 @@
 import { CAPABILITIES, type CapabilityName, type Gate } from "../config/capabilities.ts";
-import type { EgressConfig, PortholeConfig } from "../config/schema.ts";
+import type { PortholeConfig } from "../config/schema.ts";
 
 /**
  * The frame's policies, derived from the config: its CSP (in the shell's `<meta>` for opaque
@@ -10,7 +10,12 @@ import type { EgressConfig, PortholeConfig } from "../config/schema.ts";
 /** A CSP directive: its name, then its sources. */
 export type CspDirective = readonly [name: string, ...sources: string[]];
 
-export type EgressKind = keyof EgressConfig;
+export type EgressKind = "connect" | "script" | "style" | "img" | "font" | "media";
+
+/** Whether `kind` loads from any https site (`EgressConfig.anyHttps`, P059): passive kinds only. */
+export function anyHttps(config: PortholeConfig, kind: EgressKind): boolean {
+  return (config.egress.anyHttps ?? []).some((each) => each === kind);
+}
 
 /** The capabilities a config declares, in vocabulary order. */
 export function declaredCapabilities(config: PortholeConfig): CapabilityName[] {
@@ -56,13 +61,15 @@ export function frameCspDirectives(config: PortholeConfig): CspDirective[] {
     return [];
   }
   const origins = (kind: EgressKind) => egressOrigins(config, kind);
+  // Any https site, for passive kinds a host opened so (P059); never for what runs or talks.
+  const https = (kind: "img" | "media" | "font") => (anyHttps(config, kind) ? ["https:"] : []);
   return [
     ["default-src", "'none'"],
     ["script-src", "'unsafe-inline'", "'unsafe-eval'", "blob:", ...origins("script")],
     ["style-src", "'unsafe-inline'", ...origins("style")],
-    ["font-src", "data:", ...origins("font")],
-    ["img-src", "data:", "blob:", ...origins("img")],
-    ["media-src", "data:", "blob:", ...origins("media")],
+    ["font-src", "data:", ...https("font"), ...origins("font")],
+    ["img-src", "data:", "blob:", ...https("img"), ...origins("img")],
+    ["media-src", "data:", "blob:", ...https("media"), ...origins("media")],
     ["connect-src", ...list(origins("connect"))],
     ["worker-src", "blob:"],
     ["child-src", "blob:"],
@@ -129,6 +136,15 @@ export function embedderFrameSources(config: PortholeConfig): string[] {
  * engine Porthole supports reads frames from `frame-src`, P038).
  */
 export function embedderCsp(configs: readonly PortholeConfig[]): string {
-  const sources = unique(configs.flatMap(embedderFrameSources));
+  const sources = embedderFrameSourcesOf(configs);
   return serializeCsp([["frame-src", ...(sources.length === 0 ? ["'none'"] : sources)]]);
 }
+
+/**
+ * The `frame-src` sources the embedding page must allow for every kind of display it shows, as a
+ * list, for a host that writes its own policy around them (empty: it frames nothing of
+ * Porthole's but `srcdoc`, which needs none).
+ */
+export function embedderFrameSourcesOf(configs: readonly PortholeConfig[]): string[] {
+  return unique(configs.flatMap(embedderFrameSources));
+}

package/src/config/schema.ts

@@ -61,8 +61,19 @@ export interface EgressConfig {
   readonly img?: readonly string[];
   readonly font?: readonly string[];
   readonly media?: readonly string[];
+  /**
+   * Passive content that may load from any https site (P059): images, audio and video, fonts, for
+   * pages that hotlink them. Never scripts, styles or data. It opens a channel out: a viewer's
+   * address and a visit signal reach any site, and data can leave in the URL.
+   */
+  readonly anyHttps?: readonly PassiveKind[];
 }
 
+/** What `EgressConfig.anyHttps` may open: content that runs nothing (P059). */
+export const PASSIVE_KINDS = ["img", "media", "font"] as const;
+
+export type PassiveKind = (typeof PASSIVE_KINDS)[number];
+
 export interface ThemeConfig {
   /**
    * Every CSS variable the content may read, with its default per scheme. The shell injects
@@ -175,4 +186,16 @@ export interface PortholeConfig {
   readonly sandbox?: readonly UrlSandboxExtra[];
   /** Url mode only: features delegated to the frame (`URL_PERMISSIONS`); none by default. */
   readonly permissions?: readonly UrlPermission[];
+  /**
+   * Domain isolation: how far a display's storage reaches, for the manual. Storage is per origin,
+   * and the host picks each display's origin (`InstanceRef.scope`); a host that gives several
+   * displays one scope (all of a conversation's widgets) names it here (`{ shared:
+   * "conversation" }`), so the manual says storage is shared across it and keys need a prefix.
+   */
+  readonly storage?: StorageConfig;
+}
+
+export interface StorageConfig {
+  /** What the displays sharing one origin have in common, as a noun ("conversation"). */
+  readonly shared?: string;
 }