@botiverse/porthole 0.1.0 → 0.1.2

package/dist/presets/presets.js

@@ -62,6 +62,19 @@ const mergeEgress = (base, extra) => {
     }
     return merged;
 };
+/** The default variables, with the host's changes and additions, less those it dropped (null). */
+function themeVariables(changes) {
+    const variables = { ...DEFAULT_THEME_VARIABLES };
+    for (const [name, value] of Object.entries(changes ?? {})) {
+        if (value === null) {
+            delete variables[name];
+        }
+        else {
+            variables[name] = value;
+        }
+    }
+    return variables;
+}
 function build(mode, defaults, options) {
     const capabilities = {
         ...BASE_CAPABILITIES,
@@ -80,8 +93,9 @@ function build(mode, defaults, options) {
         capabilities,
         egress: mergeEgress({}, options.egress),
         theme: {
-            variables: { ...DEFAULT_THEME_VARIABLES, ...options.theme?.variables },
+            variables: themeVariables(options.theme?.variables),
             event: options.theme?.event ?? DEFAULT_THEME_EVENT,
+            ...(options.theme?.documents === undefined ? {} : { documents: options.theme.documents }),
         },
         limits: { ...BASE_LIMITS, ...defaults.limits, ...options.limits },
         layout: { ...BASE_LAYOUT, ...options.layout },
@@ -121,5 +135,7 @@ export const presets = {
         guide: {},
         contentOrigins: options.contentOrigins,
         embedder: options.embedder ?? {},
+        ...(options.sandbox === undefined ? {} : { sandbox: options.sandbox }),
+        ...(options.permissions === undefined ? {} : { permissions: options.permissions }),
     }),
 };

package/dist/react/frame.d.ts

@@ -2,6 +2,7 @@ import { type CSSProperties, type ReactElement, type ReactNode } from "react";
 import type { CapabilityHandlers, Confirm, Refusal } from "../bridge/types.ts";
 import type { CapabilityName } from "../config/capabilities.ts";
 import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
+import type { FrameOutcome } from "../host/types.ts";
 import type { InstanceLocator, InstanceRef } from "../isolation/types.ts";
 /** The height a display holds before it has reported its own. */
 export declare const PLACEHOLDER_HEIGHT_PX = 96;
@@ -67,6 +68,21 @@ export interface PortholeFrameProps {
     readonly onRefused?: (capability: CapabilityName, refusal: Refusal) => void;
     /** Too many declines: the display stops asking until it runs again. */
     readonly onMuted?: () => void;
+    /**
+     * How the frame's first document went: loaded, blocked (and why), or a timeout. A host shows its
+     * own fallback (a url-mode app "Open in a new tab") on anything but loaded.
+     */
+    readonly onOutcome?: (outcome: FrameOutcome) => void;
+    /**
+     * Other ids this display had (the call's id, before the display's own settled): its remembered
+     * height is found under them, for a frame that mounts again under its new id.
+     */
+    readonly aliases?: readonly string[];
+    /**
+     * Change it when the host's theme values change without a scheme flip (or after an async
+     * restyle): the running frame reads them again.
+     */
+    readonly themeKey?: string | number;
     /** Draws the placeholder instead of the default one. */
     readonly renderPlaceholder?: (props: PlaceholderProps) => ReactNode;
     readonly className?: string;

package/dist/react/frame.js

@@ -25,9 +25,9 @@ export function PortholeProvider(props) {
     useLayoutEffect(() => {
         own.current = props.confirm;
     });
-    const confirm = useCallback((request) => own.current !== undefined
-        ? own.current(request)
-        : new Promise((resolve) => setQueue((waiting) => [...waiting, { request, resolve }])), []);
+    const confirm = useCallback((request, proceed) => own.current !== undefined
+        ? own.current(request, proceed)
+        : new Promise((resolve) => setQueue((waiting) => [...waiting, { request, resolve, proceed }])), []);
     const { hostInfo, locator } = props;
     const value = useMemo(() => ({
         live,
@@ -38,7 +38,11 @@ export function PortholeProvider(props) {
     }), [live, heights, confirm, hostInfo, locator]);
     const current = queue[0] ?? null;
     return (_jsxs(Page.Provider, { value: value, children: [props.children, props.confirm === undefined ? (_jsx(ConfirmDialog, { request: current?.request ?? null, ...(props.dialogClassName === undefined ? {} : { className: props.dialogClassName }), onAnswer: (accepted) => {
-                    current?.resolve(accepted);
+                    // A yes runs the effect inside this very click (a window it opens is the person's).
+                    if (accepted) {
+                        current?.proceed();
+                    }
+                    current?.resolve(accepted ? "accepted" : "declined");
                     setQueue((waiting) => waiting.slice(1));
                 } })) : null] }));
 }
@@ -56,6 +60,16 @@ const PLACEHOLDER_STYLE = {
 function DefaultPlaceholder({ state, title, run }) {
     return (_jsxs("div", { "data-porthole-placeholder": state, style: { ...PLACEHOLDER_STYLE, pointerEvents: state === "stopped" ? "auto" : "none" }, children: [_jsx("span", { children: state === "stopped" ? "Stopped while others run" : title }), state === "stopped" ? (_jsx("button", { type: "button", "data-porthole-run": "", onClick: run, children: "Run again" })) : null] }));
 }
+/** A display's remembered height: under its id, else under the first of its other ids that has one. */
+function rememberedHeight(heights, displayId, aliases) {
+    for (const id of [displayId, ...(aliases ?? [])]) {
+        const height = heights.get(id);
+        if (height !== undefined) {
+            return height;
+        }
+    }
+    return 0;
+}
 export function PortholeFrame(props) {
     const page = useContext(Page);
     const key = useId();
@@ -89,7 +103,17 @@ export function PortholeFrame(props) {
             page.live.release(key);
         };
     }, [page, key, max, eager]);
-    const height = page.heights.get(props.displayId) ?? 0;
+    const height = rememberedHeight(page.heights, props.displayId, props.aliases);
+    // A display renamed while it runs (its id settled) keeps its height under its new id.
+    const previousId = useRef(props.displayId);
+    useLayoutEffect(() => {
+        const before = previousId.current;
+        previousId.current = props.displayId;
+        const kept = page.heights.get(before);
+        if (before !== props.displayId && kept !== undefined && !page.heights.has(props.displayId)) {
+            page.heights.set(props.displayId, kept);
+        }
+    }, [page, props.displayId]);
     const run = () => page.live.admit(key, max);
     const placeholder = props.renderPlaceholder ?? DefaultPlaceholder;
     return (_jsx("div", { ref: box, className: props.className, "data-porthole-display": props.displayId, "data-porthole-state": state, style: {
@@ -107,6 +131,7 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
     // The height this display started at: later reports don't make it start again.
     const [startHeight] = useState(initialHeightPx);
     const { config, document: view, instance, content, partial, scheme } = frame;
+    const fills = config.mode === "url";
     // The latest props, read when the display calls back (never during render).
     const latest = useEffectEvent(() => frame);
     const notify = useEffectEvent((event, detail) => {
@@ -135,6 +160,9 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
             case "muted":
                 frame.onMuted?.();
                 return;
+            case "outcome":
+                frame.onOutcome?.(detail);
+                return;
         }
     });
     useEffect(() => {
@@ -162,10 +190,7 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
                 handlers,
                 ...(asks
                     ? {
-                        confirm: (request) => (latest().confirm ?? page.confirm ?? (() => Promise.resolve(false)))({
-                            ...request,
-                            display: { id: latest().displayId, title: latest().title },
-                        }),
+                        confirm: (request, proceed) => (latest().confirm ?? page.confirm ?? (() => Promise.resolve(false)))({ ...request, display: { id: latest().displayId, title: latest().title } }, proceed),
                     }
                     : {}),
                 theme: (each) => latest().theme?.(each) ?? {},
@@ -192,6 +217,7 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
             "navigated",
             "refused",
             "muted",
+            "outcome",
         ];
         for (const event of events) {
             display.on(event, (detail) => notify(event, detail));
@@ -214,8 +240,16 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
     useEffect(() => {
         handle.current?.setTheme(scheme);
     }, [scheme]);
+    const { themeKey } = frame;
+    useEffect(() => {
+        if (themeKey !== undefined) {
+            handle.current?.refreshTheme();
+        }
+    }, [themeKey]);
     return (_jsxs("div", { "data-porthole-ready": String(ready), style: {
             position: "relative",
+            // A url-mode app fills the frame's box (give PortholeFrame a height); the rest size to content.
+            ...(fills ? { height: "100%" } : {}),
             ...(ready ? {} : { minHeight: Math.max(startHeight, PLACEHOLDER_HEIGHT_PX) }),
-        }, children: [_jsx("div", { ref: holder, "data-porthole-mount": "", style: { opacity: ready ? 1 : 0 } }), ready ? null : placeholder({ state: "loading", title: frame.title, run })] }));
+        }, children: [_jsx("div", { ref: holder, "data-porthole-mount": "", style: { opacity: ready ? 1 : 0, ...(fills ? { height: "100%" } : {}) } }), ready ? null : placeholder({ state: "loading", title: frame.title, run })] }));
 }

package/dist/server/crypto.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The hashing `/server` needs, in plain JavaScript over web-standard types (`Uint8Array`,
+ * `TextEncoder`, `crypto.getRandomValues`), so it runs the same on Node, Cloudflare Workers and
+ * any other runtime (P044). Synchronous on purpose: Web Crypto's HMAC is async, and an origin
+ * (`originFor`) is computed synchronously. SHA-256 per FIPS 180-4, HMAC per RFC 2104; checked
+ * against the standard vectors and `node:crypto` in `test/crypto.test.ts`.
+ */
+export declare function sha256(data: Uint8Array): Uint8Array;
+export declare function hmacSha256(key: Uint8Array, message: Uint8Array): Uint8Array;
+export declare const utf8: (text: string) => Uint8Array;
+export declare const fromUtf8: (bytes: Uint8Array) => string;
+/** Base64url without padding (RFC 4648 §5). */
+export declare function base64url(bytes: Uint8Array): string;
+/** Decodes base64url without padding; null for anything else. */
+export declare function fromBase64url(text: string): Uint8Array | null;
+/** Equal bytes, compared in time that depends only on the length. */
+export declare function timingSafeEqual(a: Uint8Array, b: Uint8Array): boolean;
+/** Random bytes from the runtime's CSPRNG (`crypto.getRandomValues`: Node, Workers, browsers). */
+export declare function randomBytes(length: number): Uint8Array;

package/dist/server/crypto.js

@@ -0,0 +1,144 @@
+/**
+ * The hashing `/server` needs, in plain JavaScript over web-standard types (`Uint8Array`,
+ * `TextEncoder`, `crypto.getRandomValues`), so it runs the same on Node, Cloudflare Workers and
+ * any other runtime (P044). Synchronous on purpose: Web Crypto's HMAC is async, and an origin
+ * (`originFor`) is computed synchronously. SHA-256 per FIPS 180-4, HMAC per RFC 2104; checked
+ * against the standard vectors and `node:crypto` in `test/crypto.test.ts`.
+ */
+const K = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+    0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+    0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+const rotr = (x, n) => (x >>> n) | (x << (32 - n));
+export function sha256(data) {
+    const length = data.length;
+    // Padded to a multiple of 64 bytes: a 1 bit, zeros, then the length in bits (64-bit big-endian).
+    const padded = new Uint8Array(Math.ceil((length + 9) / 64) * 64);
+    padded.set(data);
+    padded[length] = 0x80;
+    const view = new DataView(padded.buffer);
+    view.setUint32(padded.length - 8, Math.floor(length / 0x20000000), false);
+    view.setUint32(padded.length - 4, (length * 8) >>> 0, false);
+    const h = new Uint32Array([
+        0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
+    ]);
+    const w = new Uint32Array(64);
+    for (let offset = 0; offset < padded.length; offset += 64) {
+        for (let i = 0; i < 16; i += 1) {
+            w[i] = view.getUint32(offset + i * 4, false);
+        }
+        for (let i = 16; i < 64; i += 1) {
+            const a = w[i - 15];
+            const b = w[i - 2];
+            const s0 = rotr(a, 7) ^ rotr(a, 18) ^ (a >>> 3);
+            const s1 = rotr(b, 17) ^ rotr(b, 19) ^ (b >>> 10);
+            w[i] = (w[i - 16] + s0 + w[i - 7] + s1) >>> 0;
+        }
+        let [a, b, c, d, e, f, g, hh] = h;
+        for (let i = 0; i < 64; i += 1) {
+            const s1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+            const ch = (e & f) ^ (~e & g);
+            const t1 = (hh + s1 + ch + K[i] + w[i]) >>> 0;
+            const s0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+            const maj = (a & b) ^ (a & c) ^ (b & c);
+            const t2 = (s0 + maj) >>> 0;
+            hh = g;
+            g = f;
+            f = e;
+            e = (d + t1) >>> 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (t1 + t2) >>> 0;
+        }
+        const next = [a, b, c, d, e, f, g, hh];
+        for (let i = 0; i < 8; i += 1) {
+            h[i] = (h[i] + next[i]) >>> 0;
+        }
+    }
+    const out = new Uint8Array(32);
+    const outView = new DataView(out.buffer);
+    for (let i = 0; i < 8; i += 1) {
+        outView.setUint32(i * 4, h[i], false);
+    }
+    return out;
+}
+const BLOCK = 64;
+export function hmacSha256(key, message) {
+    const block = new Uint8Array(BLOCK);
+    block.set(key.length > BLOCK ? sha256(key) : key);
+    const inner = new Uint8Array(BLOCK + message.length);
+    const outer = new Uint8Array(BLOCK + 32);
+    for (let i = 0; i < BLOCK; i += 1) {
+        inner[i] = block[i] ^ 0x36;
+        outer[i] = block[i] ^ 0x5c;
+    }
+    inner.set(message, BLOCK);
+    outer.set(sha256(inner), BLOCK);
+    return sha256(outer);
+}
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+export const utf8 = (text) => encoder.encode(text);
+export const fromUtf8 = (bytes) => decoder.decode(bytes);
+const B64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+/** Base64url without padding (RFC 4648 §5). */
+export function base64url(bytes) {
+    let out = "";
+    for (let i = 0; i < bytes.length; i += 3) {
+        const n = (bytes[i] << 16) | ((bytes[i + 1] ?? 0) << 8) | (bytes[i + 2] ?? 0);
+        out += B64[(n >>> 18) & 63];
+        out += B64[(n >>> 12) & 63];
+        if (i + 1 < bytes.length) {
+            out += B64[(n >>> 6) & 63];
+        }
+        if (i + 2 < bytes.length) {
+            out += B64[n & 63];
+        }
+    }
+    return out;
+}
+/** Decodes base64url without padding; null for anything else. */
+export function fromBase64url(text) {
+    if (!/^[A-Za-z0-9_-]*$/u.test(text) || text.length % 4 === 1) {
+        return null;
+    }
+    const out = new Uint8Array(Math.floor((text.length * 3) / 4));
+    let bits = 0;
+    let buffer = 0;
+    let index = 0;
+    for (const char of text) {
+        buffer = (buffer << 6) | B64.indexOf(char);
+        bits += 6;
+        if (bits >= 8) {
+            bits -= 8;
+            out[index] = (buffer >>> bits) & 0xff;
+            index += 1;
+        }
+    }
+    // The leftover bits of a canonical encoding are zero.
+    return (buffer & ((1 << bits) - 1)) === 0 ? out : null;
+}
+/** Equal bytes, compared in time that depends only on the length. */
+export function timingSafeEqual(a, b) {
+    if (a.length !== b.length) {
+        return false;
+    }
+    let difference = 0;
+    for (let i = 0; i < a.length; i += 1) {
+        difference |= a[i] ^ b[i];
+    }
+    return difference === 0;
+}
+/** Random bytes from the runtime's CSPRNG (`crypto.getRandomValues`: Node, Workers, browsers). */
+export function randomBytes(length) {
+    const bytes = new Uint8Array(length);
+    globalThis.crypto.getRandomValues(bytes);
+    return bytes;
+}

package/dist/server/index.d.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,6 +28,8 @@
  * 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, ContentDomain, Grant, PortholeServer, ServerOptions, TicketRecord, TicketStore, Upstream, } from "./types.ts";
+export type { Access, ArtifactStore, AuthorizeAnswer, AuthorizeRequest, Authorizer, ContentDomain, Grant, PortholeServer, ServerOptions, TicketRecord, TicketStore, Upstream, } from "./types.ts";

package/dist/server/index.js

@@ -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,5 +28,7 @@
  * content without a valid ticket or cookie gets nothing of the content.
  */
 export { createServer } from "./server.js";
-export { memoryTicketStore } from "./tickets.js";
+export { d1TicketSchema, d1TicketStore, memoryTicketStore, } from "./tickets.js";
+export { FRAME_STATUS_METHOD } from "../isolation/types.js";
+export { isHostLabel, prefixedName } from "./naming.js";
 export { proxyTo } from "./proxy.js";

package/dist/server/keys.js

@@ -1,4 +1,4 @@
-import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { base64url, fromBase64url, fromUtf8, hmacSha256, randomBytes, sha256, timingSafeEqual, utf8, } from "./crypto.js";
 /**
  * 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).
@@ -23,7 +23,6 @@ export function base32(bytes) {
     }
     return out;
 }
-const base64url = (bytes) => Buffer.from(bytes).toString("base64url");
 /** JSON with object keys in a fixed order, so equal values always serialize alike. */
 export function canonicalJson(value) {
     if (Array.isArray(value)) {
@@ -41,16 +40,16 @@ export function createKeys(secret) {
     if (secret.byteLength < 32) {
         throw new TypeError("The server's secret must be at least 32 random bytes");
     }
-    const derive = (use) => createHmac("sha256", secret).update(`porthole/${use}`).digest();
+    const derive = (use) => hmacSha256(secret, utf8(`porthole/${use}`));
     const labelKey = derive("label");
     const instanceKey = derive("instance");
     const signKey = derive("session");
-    const mac = (key, text) => createHmac("sha256", key).update(text).digest();
+    const mac = (key, text) => 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) => {
@@ -59,12 +58,16 @@ export function createKeys(secret) {
                 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"));
+                return JSON.parse(fromUtf8(bytes));
             }
             catch {
                 return null;
@@ -75,4 +78,4 @@ export function createKeys(secret) {
 /** A fresh one-time ticket: 160 random bits. */
 export const newTicket = () => `pt_${base32(randomBytes(20))}`;
 /** What a ticket is stored under: its hash, so a leaked store holds no usable ticket. */
-export const ticketId = (ticket) => createHash("sha256").update(ticket).digest("base64url");
+export const ticketId = (ticket) => base64url(sha256(utf8(ticket)));

package/dist/server/naming.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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>`).
+ */
+/**
+ * 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 declare function isHostLabel(label: unknown): label is string;
+/**
+ * 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 declare function prefixedName(prefix: string): (scope: string) => string;

package/dist/server/naming.js

@@ -0,0 +1,34 @@
+/**
+ * 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) {
+    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) {
+    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/dist/server/pages.d.ts

@@ -1,6 +1,11 @@
-/**
- * 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.
- */
-export declare function statusPage(status: number, title: string, detail: string, frameAncestors: string, method?: string): Response;
+import type { FrameBlock } from "../host/types.ts";
+/** Where the pages' scripts are served, on every content origin. */
+export declare const STATUS_SCRIPT_PATH = "/__porthole/status.js";
+export declare const ENTER_SCRIPT_PATH = "/__porthole/enter.js";
+/** Answers 204 when the request carries a good session for its origin's app, 401 otherwise. */
+export declare const SESSION_PATH = "/__porthole/session";
+/** The pages' scripts, by path: served with the pages' own policy in mind (`script-src 'self'`). */
+export declare function pageScript(pathname: string): Response | null;
+export declare function statusPage(status: number, title: string, detail: string, frameAncestors: string, method?: string, reason?: FrameBlock, hostOrigins?: readonly string[], code?: string): Response;
+/** The page a framed app is entered through (its answer also sets the session cookie). */
+export declare function enterPage(target: string, frameAncestors: string, hostOrigins: readonly string[], cookie: string): Response;