@botiverse/porthole 0.0.1 → 0.1.1

package/dist/react/frame.js

@@ -0,0 +1,255 @@
+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, 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,
+        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) => {
+                    // 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] }));
+}
+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] }));
+}
+/** 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();
+    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 = 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: {
+            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;
+    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) => {
+        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;
+            case "outcome":
+                frame.onOutcome?.(detail);
+                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, proceed) => (latest().confirm ?? page.confirm ?? (() => Promise.resolve(false)))({ ...request, display: { id: latest().displayId, title: latest().title } }, proceed),
+                    }
+                    : {}),
+                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",
+            "outcome",
+        ];
+        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]);
+    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, ...(fills ? { height: "100%" } : {}) } }), 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,11 @@
+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[]): 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;

package/dist/server/pages.js

@@ -0,0 +1,86 @@
+import { FRAME_STATUS_METHOD } from "../isolation/types.js";
+/**
+ * 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) => 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 = () => `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) {
+    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, connect) => `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, connect) => ({
+    "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, title, detail, frameAncestors, method = "GET", reason = "error", hostOrigins = []) {
+    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, frameAncestors, hostOrigins, cookie) {
+    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/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;