@botiverse/porthole 0.0.1 → 0.1.0

package/dist/react/frame.d.ts

@@ -0,0 +1,75 @@
+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 { InstanceLocator, InstanceRef } from "../isolation/types.ts";
+/** The height a display holds before it has reported its own. */
+export declare const PLACEHOLDER_HEIGHT_PX = 96;
+export interface PortholeProviderProps {
+    /**
+     * Who confirms gated calls for every frame below. Omitted: the default dialog (`ConfirmDialog`).
+     * Pass your own function to replace it.
+     */
+    readonly confirm?: Confirm;
+    /** How the host names itself in the handshake. */
+    readonly hostInfo?: {
+        readonly name: string;
+        readonly version: string;
+    };
+    /** Where domain and external frames load from (see `InstanceLocator`). */
+    readonly locator?: InstanceLocator;
+    /** A class for the default dialog, to restyle it. */
+    readonly dialogClassName?: string;
+    readonly children?: ReactNode;
+}
+export declare function PortholeProvider(props: PortholeProviderProps): ReactElement;
+/** What a placeholder shows: a display not yet running, loading, or stopped for others. */
+export interface PlaceholderProps {
+    readonly state: "waiting" | "loading" | "stopped";
+    readonly title: string;
+    /** Runs the display again (a stopped one), stopping another if the page is at its most. */
+    readonly run: () => void;
+}
+export interface PortholeFrameProps {
+    /** A preset's config. Keep it stable (module scope or memoized): a new one remounts the frame. */
+    readonly config: PortholeConfig;
+    /** The host's id for this display: what its height is remembered by, and calls name. */
+    readonly displayId: string;
+    /** The frame's accessible name, and the title its confirmations show (the host's words). */
+    readonly title: string;
+    /** The content so far (inline and artifact modes). */
+    readonly content?: string;
+    /** The content is still being written: drawn inert as it grows, run once when whole. */
+    readonly partial?: boolean;
+    /** A whole document to start with (an MCP Apps view). */
+    readonly document?: string;
+    /** Domain and external isolation: the instance to show. */
+    readonly instance?: InstanceRef;
+    readonly scheme: ColorScheme;
+    /** The host's live values for the config's theme variables (from its design tokens). */
+    readonly theme?: (scheme: ColorScheme) => Readonly<Record<string, string | null | undefined>>;
+    /** Handlers for the declared capabilities (the latest ones are called). */
+    readonly handlers?: CapabilityHandlers;
+    /** Who confirms this frame's gated calls, over the provider's. */
+    readonly confirm?: Confirm;
+    /** Bump to run the content again from the start. */
+    readonly generation?: number;
+    /** Run at once, without waiting to near the screen (it still counts toward the page's most). */
+    readonly eager?: boolean;
+    readonly onInitialized?: () => void;
+    readonly onResize?: (size: {
+        readonly height: number;
+        readonly width?: number;
+    }) => void;
+    readonly onError?: (message: string) => void;
+    /** The content navigated its frame away; it was started again (or stopped, after a few). */
+    readonly onNavigated?: () => void;
+    readonly onRefused?: (capability: CapabilityName, refusal: Refusal) => void;
+    /** Too many declines: the display stops asking until it runs again. */
+    readonly onMuted?: () => void;
+    /** Draws the placeholder instead of the default one. */
+    readonly renderPlaceholder?: (props: PlaceholderProps) => ReactNode;
+    readonly className?: string;
+    readonly style?: CSSProperties;
+}
+export declare function PortholeFrame(props: PortholeFrameProps): ReactElement;

package/dist/react/frame.js

@@ -0,0 +1,221 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createContext, useCallback, useContext, useEffect, useEffectEvent, useId, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore, } from "react";
+import { createHost } from "../host/create-host.js";
+import { ConfirmDialog } from "./dialog.js";
+import { createLiveFrames } from "./live.js";
+/**
+ * The React binding: a `<PortholeProvider>` near the root owns what is per page (which frames
+ * run, the heights displays reported, and the default confirmation dialog); a `<PortholeFrame>` per
+ * display mounts it when it nears the screen, streams its content, flips its theme, and remembers
+ * its height. All the isolation is the core's (`createHost`); this is mounting and lifecycle.
+ */
+/** How far off screen a frame starts (and keeps) running. */
+const NEAR_SCREEN = "800px 0px";
+/** The height a display holds before it has reported its own. */
+export const PLACEHOLDER_HEIGHT_PX = 96;
+/** Without a provider: one registry for the page, and no one to confirm (gated calls refused). */
+const PAGE = { live: createLiveFrames(), heights: new Map() };
+const Page = createContext(PAGE);
+export function PortholeProvider(props) {
+    const live = useMemo(() => createLiveFrames(), []);
+    const heights = useMemo(() => new Map(), []);
+    const [queue, setQueue] = useState([]);
+    // The host's confirm as of the last render, read when a frame asks (never during render).
+    const own = useRef(props.confirm);
+    useLayoutEffect(() => {
+        own.current = props.confirm;
+    });
+    const confirm = useCallback((request) => own.current !== undefined
+        ? own.current(request)
+        : new Promise((resolve) => setQueue((waiting) => [...waiting, { request, resolve }])), []);
+    const { hostInfo, locator } = props;
+    const value = useMemo(() => ({
+        live,
+        heights,
+        confirm,
+        ...(hostInfo === undefined ? {} : { hostInfo }),
+        ...(locator === undefined ? {} : { locator }),
+    }), [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);
+                    setQueue((waiting) => waiting.slice(1));
+                } })) : null] }));
+}
+const PLACEHOLDER_STYLE = {
+    position: "absolute",
+    inset: 0,
+    display: "flex",
+    flexDirection: "column",
+    alignItems: "center",
+    justifyContent: "center",
+    gap: 8,
+    fontSize: "0.8em",
+    opacity: 0.7,
+};
+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] }));
+}
+export function PortholeFrame(props) {
+    const page = useContext(Page);
+    const key = useId();
+    const box = useRef(null);
+    const max = props.config.limits.maxLiveFrames;
+    const state = useSyncExternalStore((listener) => page.live.subscribe(listener), () => page.live.state(key), () => "waiting");
+    const { eager } = props;
+    useEffect(() => {
+        const element = box.current;
+        if (element === null) {
+            return;
+        }
+        if (eager === true || typeof IntersectionObserver !== "function") {
+            page.live.near(key, true);
+            page.live.admit(key, max);
+            return () => page.live.release(key);
+        }
+        const observer = new IntersectionObserver((entries) => {
+            const entry = entries.at(-1);
+            if (entry === undefined) {
+                return;
+            }
+            page.live.near(key, entry.isIntersecting);
+            if (entry.isIntersecting) {
+                page.live.admit(key, max);
+            }
+        }, { rootMargin: NEAR_SCREEN });
+        observer.observe(element);
+        return () => {
+            observer.disconnect();
+            page.live.release(key);
+        };
+    }, [page, key, max, eager]);
+    const height = page.heights.get(props.displayId) ?? 0;
+    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: {
+            position: "relative",
+            width: "100%",
+            ...(state === "running" ? {} : { minHeight: Math.max(height, PLACEHOLDER_HEIGHT_PX) }),
+            ...props.style,
+        }, children: state === "running" ? (_jsx(Mount, { frame: props, page: page, initialHeightPx: height, placeholder: placeholder, run: run }, String(props.generation ?? 0))) : (placeholder({ state, title: props.title, run })) }));
+}
+/** One running display: created when mounted, torn down when unmounted, fed as props change. */
+function Mount({ frame, page, initialHeightPx, placeholder, run }) {
+    const holder = useRef(null);
+    const handle = useRef(null);
+    const [ready, setReady] = useState(false);
+    // 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;
+    // The latest props, read when the display calls back (never during render).
+    const latest = useEffectEvent(() => frame);
+    const notify = useEffectEvent((event, detail) => {
+        switch (event) {
+            case "initialized":
+                setReady(true);
+                frame.onInitialized?.();
+                return;
+            case "resize": {
+                const size = detail;
+                page.heights.set(frame.displayId, size.height);
+                frame.onResize?.(size);
+                return;
+            }
+            case "error":
+                frame.onError?.(detail.message);
+                return;
+            case "navigated":
+                frame.onNavigated?.();
+                return;
+            case "refused": {
+                const { capability, refusal } = detail;
+                frame.onRefused?.(capability, refusal);
+                return;
+            }
+            case "muted":
+                frame.onMuted?.();
+                return;
+        }
+    });
+    useEffect(() => {
+        const container = holder.current;
+        if (container === null) {
+            return;
+        }
+        const first = latest();
+        // A display keeps running when the host renames it (a streamed display's id and title can
+        // settle after it starts): calls and confirmations name it as the latest props do.
+        const named = (context) => ({
+            ...context,
+            displayId: latest().displayId,
+            title: latest().title,
+        });
+        // The handlers present now (a declared one must be), each calling the latest prop's.
+        const handlers = {};
+        for (const name of Object.keys(first.handlers ?? {})) {
+            handlers[name] = (args, context) => latest().handlers?.[name]?.(args, named(context));
+        }
+        const asks = first.confirm !== undefined || page.confirm !== undefined;
+        let display;
+        try {
+            display = createHost(config, {
+                handlers,
+                ...(asks
+                    ? {
+                        confirm: (request) => (latest().confirm ?? page.confirm ?? (() => Promise.resolve(false)))({
+                            ...request,
+                            display: { id: latest().displayId, title: latest().title },
+                        }),
+                    }
+                    : {}),
+                theme: (each) => latest().theme?.(each) ?? {},
+                ...(page.hostInfo === undefined ? {} : { hostInfo: page.hostInfo }),
+                ...(page.locator === undefined ? {} : { locator: page.locator }),
+            }).mount(container, {
+                displayId: first.displayId,
+                title: first.title,
+                scheme: first.scheme,
+                initialHeightPx: startHeight,
+                ...(view === undefined ? {} : { document: view }),
+                ...(instance === undefined ? {} : { instance }),
+            });
+        }
+        catch (error) {
+            first.onError?.(error instanceof Error ? error.message : String(error));
+            return;
+        }
+        handle.current = display;
+        const events = [
+            "initialized",
+            "resize",
+            "error",
+            "navigated",
+            "refused",
+            "muted",
+        ];
+        for (const event of events) {
+            display.on(event, (detail) => notify(event, detail));
+        }
+        if (first.content !== undefined) {
+            display.setContent(first.content, { partial: first.partial === true });
+        }
+        return () => {
+            display.destroy();
+            handle.current = null;
+        };
+        // A new display only for a new config, document, instance or page (or generation, by key);
+        // content, theme, handlers, id and title are fed to the running one.
+    }, [config, view, instance, page, startHeight]);
+    useEffect(() => {
+        if (content !== undefined) {
+            handle.current?.setContent(content, { partial: partial === true });
+        }
+    }, [content, partial]);
+    useEffect(() => {
+        handle.current?.setTheme(scheme);
+    }, [scheme]);
+    return (_jsxs("div", { "data-porthole-ready": String(ready), style: {
+            position: "relative",
+            ...(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 })] }));
+}

package/dist/react/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `@botiverse/porthole/react`: the thin React binding (TSX: a host's bundler compiles it, or the
+ * package's `dist`). Peer: `react` (19.2+, for `useEffectEvent`).
+ *
+ *   <PortholeProvider>                         // per page: live-frame cap, heights, the dialog
+ *     <PortholeFrame config={widgetConfig} displayId={id} title={title} scheme={scheme}
+ *       content={code} partial={streaming} handlers={{ sendPrompt, openLink }}
+ *       theme={tokensFor} onError={report} />
+ *   </PortholeProvider>
+ */
+export { PLACEHOLDER_HEIGHT_PX, PortholeFrame, PortholeProvider, type PlaceholderProps, type PortholeFrameProps, type PortholeProviderProps, } from "./frame.tsx";
+export { ARM_DELAY_MS, ConfirmDialog, type ConfirmDialogProps } from "./dialog.tsx";
+export { admitFrame, createLiveFrames, type FrameState, type LiveFrames } from "./live.ts";

package/dist/react/index.js

@@ -0,0 +1,13 @@
+/**
+ * `@botiverse/porthole/react`: the thin React binding (TSX: a host's bundler compiles it, or the
+ * package's `dist`). Peer: `react` (19.2+, for `useEffectEvent`).
+ *
+ *   <PortholeProvider>                         // per page: live-frame cap, heights, the dialog
+ *     <PortholeFrame config={widgetConfig} displayId={id} title={title} scheme={scheme}
+ *       content={code} partial={streaming} handlers={{ sendPrompt, openLink }}
+ *       theme={tokensFor} onError={report} />
+ *   </PortholeProvider>
+ */
+export { PLACEHOLDER_HEIGHT_PX, PortholeFrame, PortholeProvider, } from "./frame.js";
+export { ARM_DELAY_MS, ConfirmDialog } from "./dialog.js";
+export { admitFrame, createLiveFrames } from "./live.js";

package/dist/react/live.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Which frames run on a page: each runs a display's scripts, so a page runs at most a few at once.
+ * A frame runs when it comes near the screen (or is asked to run); past the most, the frames that
+ * went off screen longest ago stop, and show a placeholder at their last height until they come
+ * near again. Framework-free, so it is tested on its own.
+ */
+export type FrameState = "waiting" | "running" | "stopped";
+/**
+ * Which frames run once `key` comes near the screen or is asked to run. `live` is the frames
+ * running, the least recently admitted first. `key` runs; past `max`, the frames that are not near
+ * the screen stop first, oldest first (one near the screen stops only when all are near).
+ */
+export declare function admitFrame(live: readonly string[], near: ReadonlySet<string>, key: string, max: number): string[];
+export interface LiveFrames {
+    subscribe(listener: () => void): () => void;
+    state(key: string): FrameState;
+    /** The frame came near the screen, or left it. */
+    near(key: string, isNear: boolean): void;
+    /** `key` runs (near the screen, or asked to run again); others past `max` stop. */
+    admit(key: string, max: number): void;
+    /** The frame is gone. */
+    release(key: string): void;
+}
+export declare function createLiveFrames(): LiveFrames;

package/dist/react/live.js

@@ -0,0 +1,57 @@
+/**
+ * Which frames run on a page: each runs a display's scripts, so a page runs at most a few at once.
+ * A frame runs when it comes near the screen (or is asked to run); past the most, the frames that
+ * went off screen longest ago stop, and show a placeholder at their last height until they come
+ * near again. Framework-free, so it is tested on its own.
+ */
+/**
+ * Which frames run once `key` comes near the screen or is asked to run. `live` is the frames
+ * running, the least recently admitted first. `key` runs; past `max`, the frames that are not near
+ * the screen stop first, oldest first (one near the screen stops only when all are near).
+ */
+export function admitFrame(live, near, key, max) {
+    const next = [...live.filter((other) => other !== key), key];
+    while (next.length > Math.max(1, max)) {
+        const far = next.findIndex((other) => other !== key && !near.has(other));
+        next.splice(far === -1 ? 0 : far, 1);
+    }
+    return next;
+}
+export function createLiveFrames() {
+    let live = [];
+    const nearScreen = new Set();
+    const ran = new Set();
+    const listeners = new Set();
+    const changed = (next) => {
+        live = next;
+        for (const listener of listeners) {
+            listener();
+        }
+    };
+    return {
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        state: (key) => (live.includes(key) ? "running" : ran.has(key) ? "stopped" : "waiting"),
+        near(key, isNear) {
+            if (isNear) {
+                nearScreen.add(key);
+            }
+            else {
+                nearScreen.delete(key);
+            }
+        },
+        admit(key, max) {
+            ran.add(key);
+            changed(admitFrame(live, nearScreen, key, max));
+        },
+        release(key) {
+            nearScreen.delete(key);
+            ran.delete(key);
+            if (live.includes(key)) {
+                changed(live.filter((other) => other !== key));
+            }
+        },
+    };
+}

package/dist/server/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `@botiverse/porthole/server`: serving content on origins of its own (domain mode, artifact
+ * pages, the MCP Apps sandbox proxy, and url mode's access gate). A host's backend mounts it as a
+ * fetch-style handler in front of its own routes, for every request whose host is under the
+ * content domain:
+ *
+ *   const porthole = createServer({ content: { domain: "example-usercontent.com", scheme: "https" }, … });
+ *   app.all("*", async (c, next) => (await porthole.handle(c.req.raw)) ?? next());   // Hono
+ *
+ * and calls `issue` from its own authenticated API when a viewer opens served content.
+ *
+ * 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
+ * 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;
+ * 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
+ * buys the cookie and redirects to the app's landing path without the ticket (P025). Private
+ * content without a valid ticket or cookie gets nothing of the content.
+ */
+export { createServer } from "./server.ts";
+export { memoryTicketStore } from "./tickets.ts";
+export { proxyTo, type ProxyOptions } from "./proxy.ts";
+export type { Access, ArtifactStore, ContentDomain, Grant, PortholeServer, ServerOptions, TicketRecord, TicketStore, Upstream, } from "./types.ts";

package/dist/server/index.js

@@ -0,0 +1,26 @@
+/**
+ * `@botiverse/porthole/server`: serving content on origins of its own (domain mode, artifact
+ * pages, the MCP Apps sandbox proxy, and url mode's access gate). A host's backend mounts it as a
+ * fetch-style handler in front of its own routes, for every request whose host is under the
+ * content domain:
+ *
+ *   const porthole = createServer({ content: { domain: "example-usercontent.com", scheme: "https" }, … });
+ *   app.all("*", async (c, next) => (await porthole.handle(c.req.raw)) ?? next());   // Hono
+ *
+ * and calls `issue` from its own authenticated API when a viewer opens served content.
+ *
+ * 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
+ * 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;
+ * 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
+ * buys the cookie and redirects to the app's landing path without the ticket (P025). Private
+ * content without a valid ticket or cookie gets nothing of the content.
+ */
+export { createServer } from "./server.js";
+export { memoryTicketStore } from "./tickets.js";
+export { proxyTo } from "./proxy.js";

package/dist/server/keys.d.ts

@@ -0,0 +1,19 @@
+/** Lowercase base32 (RFC 4648 alphabet, no padding): DNS-safe, case-insensitive. */
+export declare function base32(bytes: Uint8Array): string;
+/** JSON with object keys in a fixed order, so equal values always serialize alike. */
+export declare function canonicalJson(value: unknown): string;
+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 declare function createKeys(secret: Uint8Array): Keys;
+/** A fresh one-time ticket: 160 random bits. */
+export declare const newTicket: () => string;
+/** What a ticket is stored under: its hash, so a leaked store holds no usable ticket. */
+export declare const ticketId: (ticket: string) => string;

package/dist/server/keys.js

@@ -0,0 +1,78 @@
+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) {
+    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) => 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)) {
+        return `[${value.map(canonicalJson).join(",")}]`;
+    }
+    if (value !== null && typeof value === "object") {
+        const entries = Object.entries(value)
+            .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 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 labelKey = derive("label");
+    const instanceKey = derive("instance");
+    const signKey = derive("session");
+    const mac = (key, text) => 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"));
+            }
+            catch {
+                return null;
+            }
+        },
+    };
+}
+/** 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");

package/dist/server/pages.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 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;

package/dist/server/pages.js

@@ -0,0 +1,20 @@
+/**
+ * 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.
+ */
+const escape = (text) => 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}";
+export function statusPage(status, title, detail, frameAncestors, method = "GET") {
+    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>`;
+    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",
+        },
+    });
+}

package/dist/server/proxy.d.ts

@@ -0,0 +1,21 @@
+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;
+}
+/** The browser's request headers as the app at `target` gets them. */
+export declare function upstreamRequestHeaders(headers: Headers, origin: string, target: string): Headers;
+/** The app's answer headers as the browser on `origin` gets them. */
+export declare function upstreamResponseHeaders(headers: Headers, origin: string, target: string): Headers;
+/** An `Upstream` that relays to the app by HTTP. */
+export declare function proxyTo(options?: ProxyOptions): Upstream;