@botiverse/porthole 0.1.0 → 0.1.2

package/src/server/index.ts

@@ -9,12 +9,18 @@
  *
  * and calls `issue` from its own authenticated API when a viewer opens served content.
  *
+ * Runs on any runtime with web-standard `Request`/`Response` and `crypto.getRandomValues`: Node,
+ * Cloudflare Workers (no `nodejs_compat` needed), Deno, Bun (P044). On Workers, keep tickets in D1
+ * (`d1TicketStore`, P045).
+ *
  * Origins: each storage scope gets `<label>.<domain>`, the label keyed from the scope by the
- * secret (stable, DNS-safe, not guessable from the scope). The domain is a registrable domain the
+ * secret (stable, DNS-safe, not guessable from the scope), or a host's own flat name
+ * (`content.name`, `prefixedName("a-")` for `a-<id>`), with other servers' namespaces reserved (P047). The domain is a registrable domain the
  * host uses for nothing else, so no content origin is ever same-site with the host. Documents go
  * out with their CSP (from the config) plus `frame-ancestors` (the host origins) in headers.
  *
- * Tickets: `issue` mints a one-time ticket for an instance and a viewer, good for a short time;
+ * Tickets: `issue` mints a one-time ticket for an instance and a viewer (or anonymously, for a
+ * public link, P046), good for a short time;
  * the frame's first request carries it, and the content origin takes it (once). A served document
  * comes back in that same answer, with a cookie of that origin only (`__Host-`, `Secure`,
  * `HttpOnly`, `SameSite=None; Partitioned` in a frame) for what follows; a url-mode app's ticket
@@ -22,11 +28,22 @@
  * content without a valid ticket or cookie gets nothing of the content.
  */
 export { createServer } from "./server.ts";
-export { memoryTicketStore } from "./tickets.ts";
+export {
+  d1TicketSchema,
+  d1TicketStore,
+  memoryTicketStore,
+  type D1Like,
+  type D1StatementLike,
+} from "./tickets.ts";
+export { FRAME_STATUS_METHOD } from "../isolation/types.ts";
+export { isHostLabel, prefixedName } from "./naming.ts";
 export { proxyTo, type ProxyOptions } from "./proxy.ts";
 export type {
   Access,
   ArtifactStore,
+  AuthorizeAnswer,
+  AuthorizeRequest,
+  Authorizer,
   ContentDomain,
   Grant,
   PortholeServer,

package/src/server/keys.ts

@@ -1,4 +1,13 @@
-import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import {
+  base64url,
+  fromBase64url,
+  fromUtf8,
+  hmacSha256,
+  randomBytes,
+  sha256,
+  timingSafeEqual,
+  utf8,
+} from "./crypto.ts";
 
 /**
  * The server's secrets, derived from the one it is given: one key per use, so a value made for
@@ -27,8 +36,6 @@ export function base32(bytes: Uint8Array): string {
   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)) {
@@ -58,19 +65,17 @@ 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 derive = (use: string): Uint8Array => hmacSha256(secret, utf8(`porthole/${use}`));
   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();
+  const mac = (key: Uint8Array, text: string): Uint8Array => hmacSha256(key, utf8(text));
 
   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");
+      const payload = base64url(utf8(JSON.stringify(value)));
       return `${payload}.${base64url(mac(signKey, payload))}`;
     },
     verify: (token) => {
@@ -79,12 +84,16 @@ export function createKeys(secret: Uint8Array): Keys {
         return null;
       }
       const expected = mac(signKey, payload);
-      const given = Buffer.from(signature, "base64url");
-      if (given.length !== expected.length || !timingSafeEqual(given, expected)) {
+      const given = fromBase64url(signature);
+      if (given === null || !timingSafeEqual(given, expected)) {
+        return null;
+      }
+      const bytes = fromBase64url(payload);
+      if (bytes === null) {
         return null;
       }
       try {
-        return JSON.parse(Buffer.from(payload, "base64url").toString("utf8")) as unknown;
+        return JSON.parse(fromUtf8(bytes)) as unknown;
       } catch {
         return null;
       }
@@ -96,5 +105,4 @@ export function createKeys(secret: Uint8Array): Keys {
 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");
+export const ticketId = (ticket: string): string => base64url(sha256(utf8(ticket)));

package/src/server/naming.ts

@@ -0,0 +1,42 @@
+/**
+ * Names for content origins a host chooses itself (P047): flat labels like `a-<id>` under a
+ * shared content domain, next to other servers' namespaces (`<instance>.f.<domain>`).
+ */
+
+/** One lowercase DNS label (a-z 0-9 -, at most 63, no hyphen at either end). */
+const DNS_LABEL = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/u;
+
+/**
+ * Whether a label is one a host may name a content origin with: one lowercase DNS label, and not
+ * of the form IDNA reserves (`xn--`, any `??--`), so a name never displays as something else.
+ */
+export function isHostLabel(label: unknown): label is string {
+  return typeof label === "string" && DNS_LABEL.test(label) && label.slice(2, 4) !== "--";
+}
+
+const PREFIX = /^[a-z][a-z0-9]{0,15}-$/u;
+const ID = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/u;
+
+/**
+ * A naming for `content.name` that puts each scope on `<prefix><scope>` (`prefixedName("a-")`:
+ * scope `k3x9` is served on `a-k3x9.<domain>`). One-to-one, so no two scopes share an origin, and
+ * no name it makes is a reserved one or a keyed default (those have no hyphen). Scopes must
+ * already be label-safe (lowercase letters, digits, inner hyphens); anything else throws rather
+ * than being folded into another scope's name.
+ */
+export function prefixedName(prefix: string): (scope: string) => string {
+  if (!PREFIX.test(prefix)) {
+    throw new TypeError(
+      "A name prefix is a lowercase letter, then letters or digits, then '-' (a-)",
+    );
+  }
+  return (scope) => {
+    const label = `${prefix}${scope}`;
+    if (!ID.test(scope) || !isHostLabel(label)) {
+      throw new TypeError(
+        `Scope ${JSON.stringify(scope)} can't be named under ${prefix}: lowercase letters, digits and inner hyphens, ${63 - prefix.length} at most`,
+      );
+    }
+    return label;
+  };
+}

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,112 @@ 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()}
+  const blocked = { state: "blocked", reason: main.dataset.portholeReason || "error", status: Number(main.dataset.portholeStatus) };
+  if (main.dataset.portholeCode) blocked.code = main.dataset.portholeCode;
+  say(blocked);
+})();`;
+
+/**
+ * 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, once this page has loaded,
+ * 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) {
+    // The host counts this page's load, then the app's (P040): leave only once this page has
+    // loaded, or a fast answer would leave first and its load would never be seen.
+    if (document.readyState !== "complete") {
+      await new Promise((resolve) => addEventListener("load", resolve, { once: true }));
+    }
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    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[] = [],
+  code?: 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)}"${code === undefined ? "" : ` data-porthole-code="${escape(code)}"`} 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 });
+}