@botiverse/porthole 0.0.1 → 0.1.1

package/src/server/keys.ts

@@ -0,0 +1,100 @@
+import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+
+/**
+ * The server's secrets, derived from the one it is given: one key per use, so a value made for
+ * one (a label) can never stand in for another (a cookie's signature).
+ */
+
+const ALPHABET = "abcdefghijklmnopqrstuvwxyz234567";
+
+/** Lowercase base32 (RFC 4648 alphabet, no padding): DNS-safe, case-insensitive. */
+export function base32(bytes: Uint8Array): string {
+  let out = "";
+  let buffer = 0;
+  let bits = 0;
+  for (const byte of bytes) {
+    buffer = (buffer << 8) | byte;
+    bits += 8;
+    while (bits >= 5) {
+      out += ALPHABET[(buffer >>> (bits - 5)) & 31];
+      bits -= 5;
+    }
+    buffer &= (1 << bits) - 1;
+  }
+  if (bits > 0) {
+    out += ALPHABET[(buffer << (5 - bits)) & 31];
+  }
+  return out;
+}
+
+const base64url = (bytes: Uint8Array): string => Buffer.from(bytes).toString("base64url");
+
+/** JSON with object keys in a fixed order, so equal values always serialize alike. */
+export function canonicalJson(value: unknown): string {
+  if (Array.isArray(value)) {
+    return `[${value.map(canonicalJson).join(",")}]`;
+  }
+  if (value !== null && typeof value === "object") {
+    const entries = Object.entries(value as Record<string, unknown>)
+      .filter(([, each]) => each !== undefined)
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return `{${entries.map(([key, each]) => `${JSON.stringify(key)}:${canonicalJson(each)}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+export interface Keys {
+  /** The DNS label for a storage scope: 24 base32 characters (120 bits), stable, not guessable. */
+  label(scope: string): string;
+  /** A short name for an instance (16 base32 characters): its document's path and cookie name. */
+  instanceKey(instance: unknown): string;
+  /** `value` signed: `<payload>.<signature>`, both base64url. */
+  sign(value: unknown): string;
+  /** The signed value, or null when the signature doesn't hold. */
+  verify(token: string): unknown;
+}
+
+export function createKeys(secret: Uint8Array): Keys {
+  if (secret.byteLength < 32) {
+    throw new TypeError("The server's secret must be at least 32 random bytes");
+  }
+  const derive = (use: string): Buffer =>
+    createHmac("sha256", secret).update(`porthole/${use}`).digest();
+  const labelKey = derive("label");
+  const instanceKey = derive("instance");
+  const signKey = derive("session");
+  const mac = (key: Buffer, text: string): Buffer =>
+    createHmac("sha256", key).update(text).digest();
+
+  return {
+    label: (scope) => base32(mac(labelKey, scope).subarray(0, 15)),
+    instanceKey: (instance) => base32(mac(instanceKey, canonicalJson(instance)).subarray(0, 10)),
+    sign: (value) => {
+      const payload = Buffer.from(JSON.stringify(value)).toString("base64url");
+      return `${payload}.${base64url(mac(signKey, payload))}`;
+    },
+    verify: (token) => {
+      const [payload, signature, ...rest] = token.split(".");
+      if (payload === undefined || signature === undefined || rest.length > 0) {
+        return null;
+      }
+      const expected = mac(signKey, payload);
+      const given = Buffer.from(signature, "base64url");
+      if (given.length !== expected.length || !timingSafeEqual(given, expected)) {
+        return null;
+      }
+      try {
+        return JSON.parse(Buffer.from(payload, "base64url").toString("utf8")) as unknown;
+      } catch {
+        return null;
+      }
+    },
+  };
+}
+
+/** A fresh one-time ticket: 160 random bits. */
+export const newTicket = (): string => `pt_${base32(randomBytes(20))}`;
+
+/** What a ticket is stored under: its hash, so a leaked store holds no usable ticket. */
+export const ticketId = (ticket: string): string =>
+  createHash("sha256").update(ticket).digest("base64url");

package/src/server/pages.ts

@@ -0,0 +1,117 @@
+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, 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 =>
+  text.replace(/[&<>"']/gu, (char) => `&#${char.charCodeAt(0)};`);
+
+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}" 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: 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/proxy.ts

@@ -0,0 +1,131 @@
+import type { Access, Upstream } from "./types.ts";
+
+/**
+ * A url-mode upstream that relays each request to the running app by HTTP: the app believes it is
+ * on its own origin (Host, Origin and Referer name it; dev servers check Host), learns nothing of
+ * the proxy (no forwarding headers), and its answer comes back on the content origin (its
+ * redirects to itself, and its cookies, stay there). WebSockets (a dev server's hot reload) don't
+ * go through a fetch-style handler: the host relays those on its own upgrade path, after
+ * `PortholeServer.access` lets the request in.
+ */
+
+export interface ProxyOptions {
+  /** Where the app runs. Default: the external instance's own `url` (its origin; paths map 1:1). */
+  readonly target?: (access: Access) => string;
+  /** The fetch to relay with. Default: the global one. */
+  readonly fetch?: typeof fetch;
+}
+
+const HOP_BY_HOP = new Set([
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "proxy-connection",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade",
+]);
+/** What a proxy in front of the host's server added: the app is told nothing of it. */
+const FORWARDING = /^(?:x-forwarded-.*|forwarded|x-real-ip)$/u;
+
+function connectionTokens(headers: Headers): Set<string> {
+  return new Set(
+    (headers.get("connection") ?? "")
+      .split(",")
+      .map((token) => token.trim().toLowerCase())
+      .filter((token) => token !== ""),
+  );
+}
+
+/** The browser's request headers as the app at `target` gets them. */
+export function upstreamRequestHeaders(headers: Headers, origin: string, target: string): Headers {
+  const named = connectionTokens(headers);
+  const out = new Headers();
+  for (const [name, value] of headers) {
+    const key = name.toLowerCase();
+    if (key === "host" || HOP_BY_HOP.has(key) || named.has(key) || FORWARDING.test(key)) {
+      continue;
+    }
+    if (key === "origin" && value === origin) {
+      out.set(name, target);
+    } else if (key === "referer" && (value === origin || value.startsWith(`${origin}/`))) {
+      out.set(name, `${target}${value.slice(origin.length)}`);
+    } else {
+      out.append(name, value);
+    }
+  }
+  // The answer comes back decoded by fetch: ask for it plain rather than pay to decode it.
+  out.set("accept-encoding", "identity");
+  return out;
+}
+
+/** The app's answer headers as the browser on `origin` gets them. */
+export function upstreamResponseHeaders(headers: Headers, origin: string, target: string): Headers {
+  const named = connectionTokens(headers);
+  const out = new Headers();
+  for (const [name, value] of headers) {
+    const key = name.toLowerCase();
+    if (
+      HOP_BY_HOP.has(key) ||
+      named.has(key) ||
+      key === "set-cookie" ||
+      // fetch decoded the body, whatever the app said it encoded.
+      key === "content-encoding" ||
+      key === "content-length"
+    ) {
+      continue;
+    }
+    if (key === "location") {
+      out.set(name, onOrigin(value, origin, target));
+    } else {
+      out.append(name, value);
+    }
+  }
+  for (const cookie of headers.getSetCookie()) {
+    // Host-only on the content origin: an app's cookie never reaches the content domain's others.
+    const [pair = "", ...attributes] = cookie.split(";");
+    const kept = attributes.filter((attribute) => !/^\s*domain\s*=/iu.test(attribute));
+    out.append("set-cookie", [pair, ...kept].join(";"));
+  }
+  return out;
+}
+
+/** `<target>/x` → `<origin>/x`; any other URL as it is. */
+function onOrigin(location: string, origin: string, target: string): string {
+  try {
+    const url = new URL(location, target);
+    return url.origin === target ? `${origin}${url.pathname}${url.search}${url.hash}` : location;
+  } catch {
+    return location;
+  }
+}
+
+/** An `Upstream` that relays to the app by HTTP. */
+export function proxyTo(options: ProxyOptions = {}): Upstream {
+  const relay = options.fetch ?? fetch;
+  return async (request, access) => {
+    const where =
+      options.target?.(access) ??
+      (access.instance.document.kind === "external" ? access.instance.document.url : null);
+    if (where === null) {
+      return new Response("Not an app", { status: 502 });
+    }
+    const target = new URL(where).origin;
+    const url = new URL(request.url);
+    const method = request.method.toUpperCase();
+    const hasBody = method !== "GET" && method !== "HEAD";
+    const answer = await relay(`${target}${url.pathname}${url.search}`, {
+      method,
+      headers: upstreamRequestHeaders(request.headers, access.origin, target),
+      redirect: "manual",
+      ...(hasBody ? { body: request.body, duplex: "half" } : {}),
+    });
+    return new Response(method === "HEAD" ? null : answer.body, {
+      status: answer.status,
+      statusText: answer.statusText,
+      headers: upstreamResponseHeaders(answer.headers, access.origin, target),
+    });
+  };
+}