@botiverse/porthole 0.1.0 → 0.1.1

package/src/server/pages.ts

@@ -1,7 +1,12 @@
+import { FRAME_STATUS_METHOD } from "../isolation/types.ts";
+import type { FrameBlock } from "../host/types.ts";
+
 /**
- * The server's own pages on a content origin: why it shows nothing of the content. Plain, no
- * script, framable only by the host origins, never cached. Their words are the host-agnostic
- * mechanism's; a host that wants its own wording serves its own page in front.
+ * The server's own pages on a content origin: why it shows nothing of the content, and the page a
+ * framed app is entered through. Plain, framable only by the host origins, never cached. Each tells
+ * the page that frames it how loading went (`porthole/notifications/frame-status`, P040), posted to
+ * the host origins only, so a host can show its own fallback ("Open in a new tab"). Their words are
+ * the host-agnostic mechanism's; a host that wants its own wording serves its own page in front.
  */
 
 const escape = (text: string): string =>
@@ -10,22 +15,103 @@ const escape = (text: string): string =>
 const STYLE =
   ":root{color-scheme:light dark;font-family:system-ui,sans-serif}body{margin:0;min-height:100vh;display:grid;place-items:center;background:Canvas;color:CanvasText}main{max-width:420px;padding:24px}h1{font-size:17px;margin:0 0 8px}p{margin:0;opacity:.75;line-height:1.5}";
 
+/** Where the pages' scripts are served, on every content origin. */
+export const STATUS_SCRIPT_PATH = "/__porthole/status.js";
+export const ENTER_SCRIPT_PATH = "/__porthole/enter.js";
+/** Answers 204 when the request carries a good session for its origin's app, 401 otherwise. */
+export const SESSION_PATH = "/__porthole/session";
+
+const say = (): string =>
+  `const say = (params) => { if (window.parent === window) return; for (const origin of hosts) window.parent.postMessage({ jsonrpc: "2.0", method: ${JSON.stringify(FRAME_STATUS_METHOD)}, params }, origin); };`;
+
+/** Tells the host the page is blocked, and why (from the page's data attributes). */
+const STATUS_SCRIPT = `(() => {
+  const main = document.querySelector("[data-porthole-status]");
+  if (main === null) return;
+  const hosts = JSON.parse(main.dataset.portholeHosts || "[]");
+  ${say()}
+  say({ state: "blocked", reason: main.dataset.portholeReason || "error", status: Number(main.dataset.portholeStatus) });
+})();`;
+
+/**
+ * Enters a framed app: says so, checks that the browser kept the session cookie this page's own
+ * answer set (WebKit keeps none in a cross-site frame, P025), then goes on to the app, or says it
+ * is blocked and why.
+ */
+const ENTER_SCRIPT = `(async () => {
+  const main = document.querySelector("[data-porthole-enter]");
+  if (main === null) return;
+  const hosts = JSON.parse(main.dataset.portholeHosts || "[]");
+  ${say()}
+  say({ state: "entering" });
+  let kept = false;
+  try {
+    kept = (await fetch(${JSON.stringify(SESSION_PATH)}, { credentials: "same-origin", cache: "no-store" })).ok;
+  } catch (_) {}
+  if (kept) {
+    location.replace(main.dataset.portholeTarget || "/");
+    return;
+  }
+  say({ state: "blocked", reason: "cookies", status: 401 });
+  main.querySelector("h1").textContent = "Open this app in a new tab";
+  main.querySelector("p").textContent = "This browser keeps no sign-in for it inside a frame.";
+})();`;
+
+/** The pages' scripts, by path: served with the pages' own policy in mind (`script-src 'self'`). */
+export function pageScript(pathname: string): Response | null {
+  const body =
+    pathname === STATUS_SCRIPT_PATH
+      ? STATUS_SCRIPT
+      : pathname === ENTER_SCRIPT_PATH
+        ? ENTER_SCRIPT
+        : null;
+  return body === null
+    ? null
+    : new Response(body, {
+        headers: {
+          "content-type": "text/javascript; charset=utf-8",
+          "cache-control": "no-store",
+          "x-content-type-options": "nosniff",
+        },
+      });
+}
+
+const policy = (frameAncestors: string, connect: boolean): string =>
+  `default-src 'none'; style-src 'unsafe-inline'; script-src 'self'; ${connect ? "connect-src 'self'; " : ""}base-uri 'none'; form-action 'none'; frame-ancestors ${frameAncestors}`;
+
+const pageHeaders = (frameAncestors: string, connect: boolean) => ({
+  "content-type": "text/html; charset=utf-8",
+  "cache-control": "no-store",
+  "content-security-policy": policy(frameAncestors, connect),
+  "referrer-policy": "no-referrer",
+  "x-content-type-options": "nosniff",
+});
+
 export function statusPage(
   status: number,
   title: string,
   detail: string,
   frameAncestors: string,
   method = "GET",
+  reason: FrameBlock = "error",
+  hostOrigins: readonly string[] = [],
 ): Response {
-  const body = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${escape(title)}</title><style>${STYLE}</style></head><body><main data-porthole-status="${status}"><h1>${escape(title)}</h1><p>${escape(detail)}</p></main></body></html>`;
+  const body = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${escape(title)}</title><style>${STYLE}</style></head><body><main data-porthole-status="${status}" data-porthole-reason="${escape(reason)}" data-porthole-hosts="${escape(JSON.stringify(hostOrigins))}"><h1>${escape(title)}</h1><p>${escape(detail)}</p></main><script src="${STATUS_SCRIPT_PATH}"></script></body></html>`;
   return new Response(method === "HEAD" ? null : body, {
     status,
-    headers: {
-      "content-type": "text/html; charset=utf-8",
-      "cache-control": "no-store",
-      "content-security-policy": `default-src 'none'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'; frame-ancestors ${frameAncestors}`,
-      "referrer-policy": "no-referrer",
-      "x-content-type-options": "nosniff",
-    },
+    headers: pageHeaders(frameAncestors, false),
   });
 }
+
+/** The page a framed app is entered through (its answer also sets the session cookie). */
+export function enterPage(
+  target: string,
+  frameAncestors: string,
+  hostOrigins: readonly string[],
+  cookie: string,
+): Response {
+  const body = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Opening the app</title><style>${STYLE}</style></head><body><main data-porthole-enter="" data-porthole-target="${escape(target)}" data-porthole-hosts="${escape(JSON.stringify(hostOrigins))}"><h1>Opening the app…</h1><p></p></main><script src="${ENTER_SCRIPT_PATH}"></script></body></html>`;
+  const headers = new Headers(pageHeaders(frameAncestors, true));
+  headers.set("set-cookie", cookie);
+  return new Response(body, { status: 200, headers });
+}

package/src/server/server.ts

@@ -1,7 +1,7 @@
 import { compile, type CompiledConfig } from "../compile/compile.ts";
 import type { DisplayMode, EgressConfig } from "../config/schema.ts";
 import {
-  isExactOrigin,
+  hostOriginProblem,
   maybeSameSite,
   originMatchesSource,
   parseOrigin,
@@ -9,7 +9,8 @@ import {
 import type { FrameLocation, InstanceRef, ServedDocument } from "../isolation/types.ts";
 import { sandboxProxyDocument } from "../mcp/proxy.ts";
 import { createKeys, newTicket, ticketId } from "./keys.ts";
-import { statusPage } from "./pages.ts";
+import { enterPage, pageScript, SESSION_PATH, statusPage } from "./pages.ts";
+import type { FrameBlock } from "../host/types.ts";
 import { memoryTicketStore } from "./tickets.ts";
 import type { Access, PortholeServer, ServerOptions, TicketRecord, TicketStore } from "./types.ts";
 
@@ -187,9 +188,14 @@ export function createServer(options: ServerOptions): PortholeServer {
     throw new TypeError("hostOrigins must name the origins that embed content");
   }
   for (const origin of options.hostOrigins) {
-    const parsed = isExactOrigin(origin) ? parseOrigin(origin) : null;
+    const problem = hostOriginProblem(origin);
+    if (problem !== null) {
+      throw new TypeError(`hostOrigins: ${problem}`);
+    }
+    // A desktop app's own scheme (ferry://app) is never the same site as web content.
+    const parsed = parseOrigin(origin);
     if (parsed === null) {
-      throw new TypeError(`hostOrigins: ${JSON.stringify(origin)} is not an exact origin`);
+      continue;
     }
     if (
       parsed.host === domain ||
@@ -209,8 +215,15 @@ export function createServer(options: ServerOptions): PortholeServer {
   }
   const tickets: TicketStore = options.tickets ?? memoryTicketStore();
 
-  const page = (status: number, title: string, detail: string, method?: string): Response =>
-    statusPage(status, title, detail, frameAncestors, method);
+  /** A page saying why there is nothing to show, told to the host too (its reason, P040). */
+  const page = (
+    status: number,
+    title: string,
+    detail: string,
+    method?: string,
+    reason: FrameBlock = status === 404 ? "not-found" : status === 502 ? "upstream" : "error",
+  ): Response =>
+    statusPage(status, title, detail, frameAncestors, method, reason, options.hostOrigins);
 
   /** The config a served document is served under, checked to fit it and this server. */
   function configFor(name: string, kind: keyof typeof MODES): CompiledConfig {
@@ -428,6 +441,7 @@ export function createServer(options: ServerOptions): PortholeServer {
         "This link has been used",
         "Content here opens once per link. Open it again from the app that showed it.",
         method,
+        "session",
       );
     }
     const served = await documentOf(access.instance);
@@ -452,13 +466,27 @@ export function createServer(options: ServerOptions): PortholeServer {
         403,
         "This link has been used",
         "A link into an app works once, for a short time. Open it again from the app that showed it.",
+        method,
+        "session",
       );
     }
     const target = new URL(record.instance.document.url);
+    const landing = `${target.pathname}${target.search}${target.hash}`;
+    // In a frame, a page enters the app: it can tell whether the browser kept the cookie (and tell
+    // the host), where a redirect would leave a frame without one showing a refusal. On a tab of
+    // its own, a redirect.
+    if (request.headers.get("sec-fetch-dest") !== "document") {
+      return enterPage(
+        landing,
+        frameAncestors,
+        options.hostOrigins,
+        sessionCookie(request, record),
+      );
+    }
     return new Response(null, {
       status: 303,
       headers: {
-        location: `${target.pathname}${target.search}${target.hash}`,
+        location: landing,
         "set-cookie": sessionCookie(request, record),
         "cache-control": "no-store",
         "referrer-policy": "no-referrer",
@@ -508,6 +536,7 @@ export function createServer(options: ServerOptions): PortholeServer {
         "Open this from the app",
         "This address shows an app only to the people the app opens it for.",
         method,
+        "session",
       );
     }
     if (options.upstream === undefined) {
@@ -579,7 +608,7 @@ export function createServer(options: ServerOptions): PortholeServer {
         clean.document.kind === "external"
           ? `${ENTER_PATH}?ticket=${ticket}`
           : `${PREFIX}d/${key}?ticket=${ticket}`;
-      return { url: `${origin}${path}`, origin };
+      return { url: `${origin}${path}`, origin, reports: true };
     },
 
     async access(request) {
@@ -601,6 +630,17 @@ export function createServer(options: ServerOptions): PortholeServer {
         if (url.pathname === ENTER_PATH) {
           return await enter(request, url, label);
         }
+        const script = pageScript(url.pathname);
+        if (script !== null) {
+          return script;
+        }
+        if (url.pathname === SESSION_PATH) {
+          // Whether this request's cookie opens its origin's app: the entry page asks.
+          return new Response(null, {
+            status: accessOf(request, label, null) === null ? 401 : 204,
+            headers: { "cache-control": "no-store" },
+          });
+        }
         const document = DOCUMENT_PATH.exec(url.pathname);
         if (document?.[1] !== undefined) {
           return await serveDocument(request, url, label, document[1]);

package/src/shell/document.ts

@@ -1,11 +1,13 @@
+import { hostOriginProblem } from "../isolation/served.ts";
 import { SHELL_RUNTIME } from "./runtime.ts";
 import type { ShellPlan } from "./plan.ts";
 
 export interface ShellDocumentOptions {
   /**
    * The origins the shell takes messages from: the embedding page's own (`location.origin`), or
-   * every host origin a served document may be embedded by. Exact origins, no wildcards. The
-   * sender must also be the frame's parent.
+   * every host origin a served document may be embedded by. Exact origins of any scheme (a
+   * desktop app's own, `ferry://app`), no wildcards, never "null". The sender must also be the
+   * frame's parent.
    */
   readonly origins: readonly string[];
   /** The frame document's title (for assistive technology inside the frame). */
@@ -24,8 +26,6 @@ export interface ShellDocumentOptions {
   readonly cspMeta?: boolean;
 }
 
-const EXACT_ORIGIN = /^(https?:\/\/[a-z0-9.-]+(:\d{1,5})?|https?:\/\/\[::1\](:\d{1,5})?)$/u;
-
 const escapeAttribute = (value: string): string =>
   value.replace(/&/gu, "&amp;").replace(/"/gu, "&quot;").replace(/</gu, "&lt;");
 
@@ -80,8 +80,9 @@ body {
  */
 export function shellDocument(plan: ShellPlan, csp: string, options: ShellDocumentOptions): string {
   for (const origin of options.origins) {
-    if (!EXACT_ORIGIN.test(origin)) {
-      throw new TypeError(`shellDocument: ${JSON.stringify(origin)} is not an exact origin`);
+    const problem = hostOriginProblem(origin);
+    if (problem !== null) {
+      throw new TypeError(`shellDocument: ${problem}`);
     }
   }
   const runtime = SHELL_RUNTIME.replace("__PLAN__", () =>

package/src/shell/plan.ts

@@ -25,6 +25,8 @@ export interface ShellPlan {
   readonly themeVariables: readonly string[];
   /** The window event fired after a theme change. */
   readonly themeEvent: string;
+  /** Whether a whole document takes the person's scheme: when it declares it, or always. */
+  readonly themeDocuments: "declared" | "always";
   /** `memory`: an opaque origin has no storage, so a map stands in for the frame's life. */
   readonly storage: "memory" | "native";
   readonly maxErrorReports: number;
@@ -58,6 +60,7 @@ export function shellPlan(config: PortholeConfig): ShellPlan | null {
     globals,
     themeVariables: Object.keys(config.theme.variables),
     themeEvent: config.theme.event,
+    themeDocuments: config.theme.documents ?? "declared",
     storage: config.isolation === "opaque" ? "memory" : "native",
     maxErrorReports: config.limits.maxErrorReports,
     maxPromptChars: config.limits.maxPromptChars,

package/src/shell/runtime.ts

@@ -487,6 +487,21 @@ export const SHELL_RUNTIME = String.raw`(() => {
     window.dispatchEvent(new Event("load"));
   };
 
+  // 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;
+  let themed = plan.content !== "document";
+  const schemeFollows = () => {
+    const root = document.documentElement;
+    const theme = lastContext && lastContext.theme;
+    if (themed && (theme === "light" || theme === "dark")) {
+      root.style.colorScheme = theme;
+      root.setAttribute("data-theme", theme);
+    } else {
+      root.style.removeProperty("color-scheme");
+      root.removeAttribute("data-theme");
+    }
+  };
   // A whole document, parsed inert (no scripts run, no declarative shadow roots built), guarded,
   // imported in place of the shell's, then its scripts run in order. The theme on the root stays.
   const renderDocument = async (html) => {
@@ -502,6 +517,9 @@ export const SHELL_RUNTIME = String.raw`(() => {
     document.head.replaceChildren(...Array.from(parsed.head.childNodes, (node) => document.importNode(node, true)));
     document.body.replaceWith(document.importNode(parsed.body, true));
     root = null;
+    const declaredScheme = parsed.querySelector('meta[name="color-scheme" i]');
+    themed = plan.themeDocuments === "always" || (declaredScheme !== null && /\bdark\b/i.test(declaredScheme.getAttribute("content") || ""));
+    schemeFollows();
     await runScripts(scripts);
     announceLoaded();
   };
@@ -554,10 +572,8 @@ export const SHELL_RUNTIME = String.raw`(() => {
         }
       }
     }
-    if (context.theme === "light" || context.theme === "dark") {
-      document.documentElement.style.colorScheme = context.theme;
-      document.documentElement.setAttribute("data-theme", context.theme);
-    }
+    lastContext = context;
+    schemeFollows();
     window.dispatchEvent(new CustomEvent(plan.themeEvent, { detail: { theme: context.theme } }));
   };