@botiverse/porthole 0.2.1 → 0.2.2

package/dist/server/host.js

@@ -88,7 +88,19 @@ export function createContentHost(options) {
                 ...(options.upstream === undefined ? {} : { upstream: options.upstream }),
                 ...(options.entry === undefined
                     ? {}
-                    : { entry: { authorizeUrl: options.entry.authorizeUrl } }),
+                    : {
+                        entry: {
+                            authorizeUrl: options.entry.authorizeUrl,
+                            // Whether a clean address names anything, before a browser is sent away (P070).
+                            named: async (label, path, request) => {
+                                const scope = options.name?.scopeOf?.(label) ?? null;
+                                const at = options.entry?.at;
+                                return (scope !== null &&
+                                    at !== undefined &&
+                                    (await at(scope, path, null, request)) != null);
+                            },
+                        },
+                    }),
                 ...(options.authorize === undefined
                     ? {}
                     : {
@@ -173,6 +185,14 @@ export function createContentHost(options) {
                     ? { evt: "porthole.content.healthy" }
                     : { evt: "porthole.content.unhealthy", reason });
             }
+            if (before.state !== view.state) {
+                try {
+                    gate.onChange?.(view);
+                }
+                catch {
+                    // The app's listener failing changes nothing here.
+                }
+            }
             running = null;
             schedule();
             return view;
@@ -356,18 +376,28 @@ export function createContentHost(options) {
                 try {
                     const instance = scope === null
                         ? null
-                        : await entry.at(scope, new URL(state.path, "https://x.invalid").pathname, viewer, request);
+                        : ((await entry.at(scope, new URL(state.path, "https://x.invalid").pathname, viewer, request)) ?? null);
                     const grant = instance === null ? null : await options.access(instance, viewer, request);
+                    // The address being opened, decoded, for the app's sign-in and refusal pages.
+                    const context = {
+                        label: state.label,
+                        scope,
+                        path: state.path,
+                        url: clean,
+                        instance,
+                        framed,
+                    };
                     if (instance === null || grant === null) {
                         if (viewer === null) {
                             // The app's sign-in never shows in a frame: the person opens a tab for it.
                             return framed
                                 ? appPage(401, "Open this in a new tab to sign in", "Signing in doesn't work inside a frame.", "sign-in", method)
-                                : await entry.signIn(request.url, request);
+                                : await entry.signIn(request.url, request, context);
                         }
                         const status = instance === null ? 404 : 403;
-                        if (!framed && entry.refusal !== undefined) {
-                            return await entry.refusal(status, request);
+                        const own = framed ? null : await entry.refusal?.(status, request, context);
+                        if (own !== null && own !== undefined) {
+                            return own;
                         }
                         return status === 404
                             ? appPage(404, "Not found", "There is nothing here.", "not-found", method)

package/dist/server/index.d.ts

@@ -33,10 +33,12 @@
  * content without a valid ticket or cookie gets nothing of the content.
  */
 export { createServer } from "./server.ts";
-export { createContentHost, HEALTH_PATH, type ContentHealthView, type ContentHost, type ContentHostEvent, type ContentHostOptions, type EntryOptions, type ContentMeta, type HealthOptions, type HealthProbe, } from "./host.ts";
+export { createContentHost, HEALTH_PATH, type ContentHealthView, type ContentHost, type ContentHostEvent, type ContentHostOptions, type EntryContext, type EntryOptions, type ContentMeta, type HealthOptions, type HealthProbe, } from "./host.ts";
 export { clashOf, contentDomain, ContentDomainError, hostnameOf, type ContentDomainInfo, type ContentDomainProblem, } from "./domain.ts";
 export { d1TicketSchema, d1TicketStore, memoryTicketStore, type D1Like, type D1StatementLike, } from "./tickets.ts";
 export { FRAME_STATUS_METHOD } from "../isolation/types.ts";
 export { isHostLabel, prefixedName, type Naming } from "./naming.ts";
+export type { PortholeConfig } from "../config/schema.ts";
+export type { FrameLocation, InstanceRef, ServedDocument } from "../isolation/types.ts";
 export { proxyTo, type ProxyOptions } from "./proxy.ts";
 export type { Access, ArtifactStore, AuthorizeAnswer, AuthorizeRequest, Authorizer, ContentDomain, EntryState, Grant, PortholeServer, ServerOptions, TicketRecord, TicketStore, Upstream, } from "./types.ts";

package/dist/server/pages.js

@@ -14,7 +14,21 @@ 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 page that frames this one how loading went, at each web host origin. A desktop app's
+ * own scheme (`ferry://app`) is no target origin a browser takes (postMessage throws), so where
+ * the host origins hold one, and the parent isn't known to be a web host origin, the word goes to
+ * the parent as `*`: these pages' `frame-ancestors` already hold their parent to the host origins,
+ * and what they say is no secret (P070). One origin failing never stops the page.
+ */
+const say = () => `const say = (params) => {
+    if (window.parent === window) return;
+    const message = { jsonrpc: "2.0", method: ${JSON.stringify(FRAME_STATUS_METHOD)}, params };
+    const web = hosts.filter((origin) => origin.startsWith("https://") || origin.startsWith("http://"));
+    for (const origin of web) { try { window.parent.postMessage(message, origin); } catch (_) {} }
+    const parent = location.ancestorOrigins && location.ancestorOrigins.length > 0 ? location.ancestorOrigins[0] : null;
+    if (web.length < hosts.length && (parent === null || !web.includes(parent))) { try { window.parent.postMessage(message, "*"); } catch (_) {} }
+  };`;
 /** 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]");

package/dist/server/proxy.js

@@ -96,6 +96,8 @@ export function proxyTo(options = {}) {
             method,
             headers: upstreamRequestHeaders(request.headers, access.origin, target),
             redirect: "manual",
+            // The browser went away (`nodeHost` aborts it): so does the relay (P070).
+            signal: request.signal,
             ...(hasBody ? { body: request.body, duplex: "half" } : {}),
         });
         return new Response(method === "HEAD" ? null : answer.body, {

package/dist/server/server.js

@@ -565,8 +565,15 @@ export function createServer(options) {
      * signed state, the browser holding the state's nonce in a cookie of this origin. A path just
      * entered whose cookie still didn't come back is a browser that keeps none here: no loop.
      */
-    function beginEntry(request, url, label, to) {
+    async function beginEntry(request, url, label, to) {
         const method = request.method.toUpperCase();
+        // An address that names nothing is nothing here (P070): never a trip to the app's sign-in.
+        const scopeOf = content.name?.scopeOf;
+        const named = options.entry?.named;
+        if ((scopeOf !== undefined && scopeOf(label) === null) ||
+            (named !== undefined && !(await named(label, url.pathname, request)))) {
+            return page(404, "Nothing here", "This address names no content.", method);
+        }
         if (method !== "GET" && method !== "HEAD") {
             return page(401, "Open this from the app", "Open this address in a browser.", method, "session");
         }
@@ -942,7 +949,7 @@ export function createServer(options) {
                         return await serveAccess(request, entered, null);
                     }
                     if (options.upstream === undefined || accessOf(request, label, null) === null) {
-                        return beginEntry(request, url, label, authorizeUrl);
+                        return await beginEntry(request, url, label, authorizeUrl);
                     }
                 }
                 // Without an upstream, only Porthole's own paths are served here: any other is nothing.

package/dist/server/types.d.ts

@@ -1,5 +1,6 @@
 import type { PortholeConfig } from "../config/schema.ts";
 import type { FrameLocation, InstanceRef } from "../isolation/types.ts";
+import type { Naming } from "./naming.ts";
 export interface ContentDomain {
     /**
      * The registrable domain content is served under, used for nothing else
@@ -16,13 +17,14 @@ export interface ContentDomain {
      * names like `a-<id>`) must return one lowercase DNS label, the same for the same scope, a
      * different one for a different scope, and never a `reserved` one.
      */
-    readonly name?: (scope: string) => string;
+    readonly name?: Naming;
     /**
-     * Labels this server never serves or names: another server's namespace under the same domain
-     * (`f` for `<instance>.f.<domain>`, `www`), or the host's own (`p-*`: every label starting
-     * `p-`). Each entry is a whole label, or a prefix ending in `*`; or a function that says
-     * whether a label is reserved. Requests for them, and for the names under them, get null (the
-     * host's routes), so a host routes them without wrapping `handle`.
+     * Labels something else serves on this domain, so this server never names them and hands their
+     * requests back: another server's namespace (`f` for `<instance>.f.<domain>`, where that server
+     * answers), or the host's own (`p-*`: its previews). Each entry is a whole label, or a prefix
+     * ending in `*`; or a function that says whether a label is reserved. Requests for them, and for
+     * the names under them, get null (the host's routes), so a host routes them without wrapping
+     * `handle`. Labels nothing serves need no entry: they get this server's 404 (P070).
      */
     readonly reserved?: readonly string[] | ((label: string) => boolean);
 }
@@ -161,6 +163,13 @@ export interface ServerOptions {
      */
     readonly entry?: {
         readonly authorizeUrl: string;
+        /**
+         * Whether a clean address names anything (P070): asked before sending a browser away, with
+         * the address's label and pathname. False: this server's 404, never the authorize route. A
+         * naming that says a label's scope (`Naming.scopeOf`) already answers 404 for a label it never
+         * makes.
+         */
+        readonly named?: (label: string, path: string, request: Request) => boolean | Promise<boolean>;
     };
 }
 /** A redirect entry's state, as the host's authorize route reads it (`PortholeServer.entryState`). */

package/docs/ARCHITECTURE.md

@@ -0,0 +1,277 @@
+# Architecture
+
+This describes the layers, their contracts, the flows and trust boundaries, and
+the extension points. It is meant to stay stable while concrete APIs change; the
+phase-1 API lives in [DESIGN.md](DESIGN.md).
+
+## The core abstraction
+
+Porthole renders **agent-drawn HTML plus a declared set of host functions.**
+
+- The HTML is untrusted. It may draw anything, but on its own it can only draw.
+- A **host function (capability)** is any power beyond drawing: send a prompt to
+  the agent, open a link, read or write state, call a tool, read data, report an
+  error. Each is named in the config and carries three facts: its **gate** (needs
+  a user gesture, needs a person's confirmation, is rate-limited), its **egress
+  needs** (origins it must reach), and its **guide entry** (how the manual
+  describes it).
+
+One capability list therefore drives three artifacts: the **bridge** (which
+functions the shell wires and the host handles), the **CSP** (what the sandbox
+may reach), and the **manual** (what the agent is told). This is why the config
+is the single source (PRINCIPLE 3) and why "talk to the agent" is not special —
+it is one host function (PRINCIPLE 4).
+
+## Layers
+
+```
+            ┌──────────────────────────────────────────────────────────┐
+            │  Host app  (owns product policy, theme, callbacks)         │
+            └───────────────┬──────────────────────────────────────────┘
+                            │ picks a preset, passes theme + callbacks
+  ┌─────────────────────────▼─────────────────────────────────────────┐
+  │  PRESET POLICY LAYER                                                │
+  │  inline-widget · artifact · mcp-app · url                           │
+  │  each = a config: CSP+origins, capabilities+gates, theme, guide     │
+  └─────────────────────────┬─────────────────────────────────────────┘
+                            │ one config
+  ┌─────────────────────────▼─────────────────────────────────────────┐
+  │  FRAMEWORK LAYER  (mechanisms only, no policy)                      │
+  │                                                                     │
+  │  config compiler ── CSP + sandbox/allow attrs                       │
+  │                 └── shell runtime (what to wire)                    │
+  │                 └── guide + tool description                        │
+  │                                                                     │
+  │  isolation core · egress hardening · streaming render · auto-size   │
+  │  theming · host-function bridge · guide gen · serving (/server)     │
+  └───────┬───────────────────────────────────────┬────────────────────┘
+          │ host side                              │ in-frame side (shell)
+  ┌───────▼─────────┐                      ┌───────▼──────────────────┐
+  │ PROTOCOL ADAPTER│  ◄── transport ──►   │  SHELL  (runs first in    │
+  │ (MCP Apps; …)   │   (postMessage/      │  the isolated frame;      │
+  │                 │    native bridge)    │  renders HTML, wires caps)│
+  └───────┬─────────┘                      └───────────────────────────┘
+          │
+  ┌───────▼───────────────────────────────────────────────────────────┐
+  │ PLATFORM HOST   web (iframe) now · WKWebView / Android later        │
+  └─────────────────────────────────────────────────────────────────── ┘
+
+  CONFORMANCE / LEAK SUITE drives a platform host through the adapter and
+  probes every egress and escape channel (runnable by any host).
+```
+
+### Framework layer (mechanisms)
+
+Pure mechanism, no product policy, no host or vendor types.
+
+- **Config compiler.** Turns one config into the CSP string, the iframe sandbox
+  and `allow` attributes, the shell's wiring, and the guide + tool description.
+  Deterministic and pure, so a test can assert the three outputs agree.
+- **Isolation core.** Places the content on an origin that is never the host's,
+  with nothing of the host's reachable: an opaque-origin frame, or a served
+  origin of its own (domain mode: a subdomain per storage scope on a separate
+  registrable domain; url mode: the app's own origin). The mode is chosen by
+  config; the rest of the framework does not depend on which.
+- **Egress hardening.** The closed-by-default network and navigation walls, plus
+  the in-shell defenses for channels a CSP does not cover (see Trust boundaries).
+- **Shell runtime.** The code that runs first inside the frame: applies theme,
+  inserts the HTML (streaming-aware), reports size and errors, and exposes the
+  declared host functions to the content.
+- **Host-function bridge.** Carries capability calls from the shell to the host
+  and results back, over a transport, with validation and gating at the boundary.
+- **Streaming render, auto-size, theming, guide generator.** The remaining
+  mechanisms, each usable on its own. Content is plain HTML and SVG; its look
+  comes from the theme variables, never from a component vocabulary (P015).
+- **Serving.** For served modes, a request handler a host's backend mounts: it
+  serves documents on their own origins with their CSP in headers, and turns a
+  one-time ticket the host minted into a cookie of that origin only.
+
+### Preset policy layer
+
+A preset is a named config with safe defaults. It fixes the CSP and allowed
+origins, the capabilities and their gates, the theme vocabulary, and the manual.
+A host adopts a preset and overrides only theme and callbacks.
+
+- **inline-widget** — host injects agent code into a strict, opaque-origin frame
+  with a shell; smallest capability set; for cards inside a conversation.
+- **artifact** — a standalone page: written into an opaque frame where the host
+  has it, or served at a URL on a separate registrable domain, CSP in headers,
+  versioned.
+- **mcp-app** — renders a standard MCP Apps view (a `ui://` template plus tool
+  input/result), using the MCP Apps adapter.
+- **url** — frames a running app by URL (a dev server's preview): isolation and
+  access auth only; no shell, no capabilities, no egress control.
+
+### Protocol adapters
+
+A thin adapter maps the framework's capability and lifecycle events onto a wire
+protocol. **MCP Apps** is the first and default. The adapter is the only layer
+that knows protocol method names and shapes; the core speaks capabilities.
+
+### Platform hosts
+
+The platform host owns the actual isolation primitive and the transport: an
+`iframe` + `postMessage` on the web now; a `WKWebView` + message handler on iOS
+later. The framework layer is written against a small platform interface so a new
+platform is an implementation of that interface, not a fork.
+
+### Conformance / leak suite
+
+A standalone test runner that drives a platform host through an adapter and
+attempts every known egress and escape channel, asserting none succeeds. Any host
+can run it against its own integration. It is both our regression gate and the
+artifact we offer upstream (PRINCIPLE 5, 6).
+
+## Contracts between layers
+
+- **Host → preset:** a preset name, theme tokens (resolved per color scheme), and
+  callbacks for each enabled host function. Nothing else is required.
+- **Preset → framework:** one config (capabilities with gates and egress needs,
+  allowed origins, theme variable map, limits, layout, mode and isolation).
+- **Config → {CSP, shell, guide}:** derived, never hand-written; a test asserts
+  agreement.
+- **Framework ↔ shell:** lifecycle and capability messages over a transport.
+  Validated both directions; unknown or malformed messages are dropped.
+- **Framework ↔ adapter:** the adapter translates between capability/lifecycle
+  events and protocol messages; it may add protocol-only messages (handshake,
+  teardown) that the framework does not model.
+- **Framework ↔ platform host:** create an isolated surface, set its policy
+  (CSP/sandbox/allow or the native equivalent), send and receive messages,
+  report size, tear down.
+
+## Flows per mode
+
+### Inline widget
+
+```
+Host app                 Framework/Adapter            Shell (opaque frame)
+   │  mount(config, cbs)       │                             │
+   │──────────────────────────►│  compile config → CSP,      │
+   │                           │  sandbox attrs, shell doc    │
+   │                           │  create opaque frame ───────►│ (shell runs first)
+   │                           │◄──── initialize ─────────────│
+   │                           │──── host context (theme,     │
+   │                           │     capabilities, size) ────►│
+   │  content (may stream) ───►│──── content (partial*) ─────►│ draw inert
+   │                           │──── content (complete) ─────►│ run
+   │                           │◄──── size / error ───────────│
+   │◄── onError / onResize ────│                             │
+   │                           │◄──── capability call ────────│ (e.g. sendPrompt)
+   │◄── gate (confirm?) ───────│   validate + gate            │
+   │── result ────────────────►│──── result ─────────────────►│
+```
+
+`*` partial content is drawn inert (no scripts, handlers or navigation) until
+complete; see Streaming in DESIGN.md.
+
+### MCP Apps view
+
+Same shape, with the adapter speaking MCP Apps: the view is an MCP Apps `App`;
+`initialize`/`initialized` is the handshake; content arrives as tool input
+(streamed as tool-input-partial, then tool-input) and tool result; capability
+calls are `ui/message`, `ui/open-link`, etc., which map to host functions. On the
+web a second-origin sandbox proxy relays messages so arbitrary MCP App HTML
+(which expects `allow-same-origin`) is isolated from the host; the proxy is
+transparent to the view and the host.
+
+### Artifact page
+
+The content is served as a real document at a URL on a separate registrable
+domain with its CSP in HTTP headers; the host embeds that URL in a frame whose
+`frame-ancestors` names the host. No code injection, and the shell is optional.
+Access is gated by a one-time ticket exchanged for a scoped cookie. Where the host
+holds the page and needs no stable origin, the shell writes it into an opaque
+frame instead.
+
+### URL frame
+
+```
+Host app            Host backend (+ /server)          App origin (served)
+   │  mount(url preset) │                                  │
+   │── locate ─────────►│ decide the viewer may see it,    │
+   │◄── ticketed URL ───│ mint a one-time ticket           │
+   │  frame src = URL ──────────────────────────────────────►│ ticket → cookie
+   │                                                       │ (that origin only)
+```
+
+No shell and no protocol: the app is someone else's. The embedding page frames
+only the declared content origins.
+
+## Trust boundaries
+
+1. **Host ↔ content.** The hard boundary. The content runs on an origin that is
+   never the host's, so same-origin policy denies it the host's DOM, storage,
+   cookies and credentials. Everything it wants beyond drawing crosses the bridge
+   as a validated, gated capability call. *What each side may know:* the content
+   never holds a host secret; whatever it says, the host treats as the content's
+   own word and confirms with a person before acting where the capability's gate
+   says so.
+
+2. **Content ↔ the outside network.** Closed by default and opened only to the
+   origins the config's capabilities declare. Two kinds of attacker matter:
+   - *Attacking the host* (steal credentials, read other data, escape the
+     sandbox): stopped by origin isolation — the content is a stranger to the
+     host origin.
+   - *Leaking or deceiving* (exfiltrate what the content was already given, or
+     draw a convincing fake to fool the viewer): origin isolation does not help
+     here; egress hardening and gating do. Some channels (a peer connection's
+     ICE gathering, a self-navigation of the frame, a nested frame in a fresh
+     realm) reach the network outside a frame's own `connect-src`. These are
+     closed by in-shell defenses and by the embedding page's own policy, each
+     proven by a leak-suite probe (DESIGN.md lists them).
+   - *An opaque frame is as closed as its page.* A `srcdoc` frame inherits the
+     embedding page's whole policy as well as its own, so on a page with
+     `default-src 'none'` and a tight `connect-src`/`img-src` its content is more
+     closed than its config says: an origin the config opens stays shut. On such
+     a page prefer domain mode, whose frames inherit nothing (P058).
+
+3. **Message boundary.** Every message crossing the frame is validated against a
+   schema and checked for sender identity before use; the shell accepts messages
+   only from its host, and the host only from its frame. What the frame says about
+   itself (its size, its errors, an annotation's anchor and where it is) is the
+   content's word even when the shell says it, since they share a realm: the host
+   bounds it and uses it as a UI hint, never as a permission (P053).
+
+4. **Host's decision ↔ content domain.** Authentication and authorization
+   *policy* are the host's; carrying the host's decision safely onto the content
+   domain is Porthole's *mechanism*. The host decides who may open an instance
+   before it calls `issue` (a viewer it knows, or a public link), and may decide
+   again on every request (`ServerOptions.authorize`). Porthole carries the decision
+   as a one-time ticket, then a signed cookie of that origin and instance only,
+   with the host's opaque `subject` inside, and never interprets identity. A deny
+   ends access from the next request on and tells the display why.
+
+## Extension points
+
+- **Capabilities.** New host functions are added to the capability vocabulary
+  with a gate, egress need, and guide entry. Adding one extends the bridge, the
+  CSP, and the manual together.
+- **Protocol extension points.** MCP Apps gaps go through the spec's own
+  mechanisms (experimental capabilities, own-prefixed methods), so the external
+  contract stays standard (PRINCIPLE 2).
+- **Theme variables.** The theme map is config; the standard MCP Apps variable
+  names are the default vocabulary.
+- **The person's clipboard** is the host's alone: content asks for a copy
+  (`copyText`), the host performs it and shows what it copied (P051, P052).
+- **Annotations** (`annotate`): the host drives a select mode and marks anchors in
+  the shell; anchors are W3C Web Annotation selectors a host stores with its own
+  comments (P053).
+- **Served content.** A host plugs its own policy and infrastructure into `/server`:
+  who may see what (`authorize`), where tickets live (`TicketStore`: memory, D1),
+  how origins are named (`content.name`, other servers' `reserved` namespaces),
+  and where apps and artifact versions come from (`upstream`, `artifacts`). It runs
+  on any runtime with web-standard `Request`/`Response` (Node, Workers).
+
+## How a new protocol or platform plugs in
+
+- **A new protocol** is a new adapter implementing the capability/lifecycle
+  translation. It does not touch the core, the shell mechanisms, or the presets
+  beyond adding a preset that selects it. The capability abstraction is the seam.
+- **A new platform** is a new implementation of the platform-host interface
+  (create isolated surface, set policy, transport, size, teardown). The framework
+  layer, adapters and presets are unchanged; the shell runtime is plain,
+  dependency-free script so it runs as-is in a new engine.
+
+This is what keeps the three answers independent: *which protocol* (adapter),
+*which platform* (platform host), and *what policy* (preset/config) each vary
+without the others changing.