@botiverse/porthole 0.1.0 → 0.1.2

package/src/server/server.ts

@@ -1,7 +1,7 @@
 import { compile, type CompiledConfig } from "../compile/compile.ts";
 import type { DisplayMode, EgressConfig } from "../config/schema.ts";
 import {
-  isExactOrigin,
+  hostOriginProblem,
   maybeSameSite,
   originMatchesSource,
   parseOrigin,
@@ -9,9 +9,18 @@ import {
 import type { FrameLocation, InstanceRef, ServedDocument } from "../isolation/types.ts";
 import { sandboxProxyDocument } from "../mcp/proxy.ts";
 import { createKeys, newTicket, ticketId } from "./keys.ts";
-import { statusPage } from "./pages.ts";
+import { isHostLabel } from "./naming.ts";
+import { enterPage, pageScript, SESSION_PATH, statusPage } from "./pages.ts";
+import type { FrameBlock } from "../host/types.ts";
 import { memoryTicketStore } from "./tickets.ts";
-import type { Access, PortholeServer, ServerOptions, TicketRecord, TicketStore } from "./types.ts";
+import type {
+  Access,
+  AuthorizeAnswer,
+  PortholeServer,
+  ServerOptions,
+  TicketRecord,
+  TicketStore,
+} from "./types.ts";
 
 /**
  * Paths on a content origin. Porthole's own live under `/__porthole/`; on a url-mode app's origin
@@ -24,6 +33,9 @@ const DOCUMENT_PATH = /^\/__porthole\/d\/([a-z2-7]{16})$/u;
 const ENTER_PATH = "/__porthole/enter";
 
 const LABEL = /^[a-z2-7]{24}$/u;
+/** A host's opaque subject and reason codes. */
+const SUBJECT_MAX = 512;
+const CODE = /^[a-z0-9-]{1,40}$/u;
 const DNS_NAME = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$/u;
 const NAME = /^[A-Za-z0-9._:-]{1,200}$/u;
 
@@ -34,11 +46,16 @@ const MAX_SESSION_SECONDS = 30 * 24 * 3_600;
 /** Browsers keep a cookie of up to 4 KB, name and attributes included. */
 const MAX_COOKIE_BYTES = 3_800;
 
-/** What a session cookie carries, signed: the instance, its viewer, and when it stops. */
+/**
+ * What a session cookie carries, signed: the instance, its viewer (or anonymous), the host's
+ * opaque subject, and when it stops.
+ */
 interface Session {
   readonly i: InstanceRef;
   readonly w: string;
   readonly x: number;
+  readonly a?: 1;
+  readonly s?: string;
 }
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
@@ -173,6 +190,30 @@ export function createServer(options: ServerOptions): PortholeServer {
     throw new TypeError("content.port must be a port number");
   }
   const keys = createKeys(options.secret);
+  const reserved = new Set(content.reserved ?? []);
+  for (const label of reserved) {
+    if (!isHostLabel(label)) {
+      throw new TypeError(
+        `content.reserved: ${JSON.stringify(label)} is not a lowercase DNS label`,
+      );
+    }
+  }
+  /** The label a scope is served on: the host's naming, checked, or the keyed default. */
+  const nameOf = (scope: string): string => {
+    if (content.name === undefined) {
+      return keys.label(scope);
+    }
+    const label = content.name(scope);
+    if (!isHostLabel(label) || reserved.has(label)) {
+      throw new TypeError(
+        `content.name gave ${JSON.stringify(label)} for a scope: it must be one lowercase DNS label (a-z 0-9 -, at most 63, not xn--), not reserved`,
+      );
+    }
+    return label;
+  };
+  /** Whether a request's label may be one this server named. */
+  const ours = (label: string): boolean =>
+    !reserved.has(label) && (content.name === undefined ? LABEL.test(label) : isHostLabel(label));
   const secure = content.scheme === "https";
   const defaultPort = secure ? 443 : 80;
   const portPart =
@@ -182,14 +223,25 @@ export function createServer(options: ServerOptions): PortholeServer {
   const contentSource = `${content.scheme}://*.${domain}${portPart}`;
   const sampleHost = `${keys.label("")}.${domain}`;
   const sampleOrigin = originOfLabel(keys.label(""));
+  const authorize = options.authorize;
+  const authorizeTtl = authorize?.ttlSeconds ?? 0;
+  if (!Number.isInteger(authorizeTtl) || authorizeTtl < 0 || authorizeTtl > 300) {
+    throw new TypeError("authorize.ttlSeconds must be an integer from 0 to 300");
+  }
+  const answers = new Map<string, { readonly answer: AuthorizeAnswer; readonly until: number }>();
 
   if (options.hostOrigins.length === 0) {
     throw new TypeError("hostOrigins must name the origins that embed content");
   }
   for (const origin of options.hostOrigins) {
-    const parsed = isExactOrigin(origin) ? parseOrigin(origin) : null;
+    const problem = hostOriginProblem(origin);
+    if (problem !== null) {
+      throw new TypeError(`hostOrigins: ${problem}`);
+    }
+    // A desktop app's own scheme (ferry://app) is never the same site as web content.
+    const parsed = parseOrigin(origin);
     if (parsed === null) {
-      throw new TypeError(`hostOrigins: ${JSON.stringify(origin)} is not an exact origin`);
+      continue;
     }
     if (
       parsed.host === domain ||
@@ -209,8 +261,70 @@ export function createServer(options: ServerOptions): PortholeServer {
   }
   const tickets: TicketStore = options.tickets ?? memoryTicketStore();
 
-  const page = (status: number, title: string, detail: string, method?: string): Response =>
-    statusPage(status, title, detail, frameAncestors, method);
+  /** A page saying why there is nothing to show, told to the host too (its reason, P040). */
+  const page = (
+    status: number,
+    title: string,
+    detail: string,
+    method?: string,
+    reason: FrameBlock = status === 404 ? "not-found" : status === 502 ? "upstream" : "error",
+    code?: string,
+  ): Response =>
+    statusPage(status, title, detail, frameAncestors, method, reason, options.hostOrigins, code);
+
+  /**
+   * The host's check on a request its cookie (or ticket) let in (P050): null to go on, or the
+   * page saying it's denied. Answers are reused only for the host's own `ttlSeconds`.
+   */
+  async function denied(request: Request, access: Access): Promise<Response | null> {
+    if (authorize === undefined) {
+      return null;
+    }
+    const key = JSON.stringify([
+      keys.instanceKey(access.instance),
+      access.viewer,
+      access.subject ?? null,
+      access.expiresAt,
+    ]);
+    const at = Date.now();
+    let answer = authorizeTtl > 0 ? answers.get(key) : undefined;
+    if (answer === undefined || answer.until <= at) {
+      let given: AuthorizeAnswer;
+      try {
+        given = await authorize.check({
+          scope: access.instance.scope,
+          instance: access.instance,
+          viewer: access.viewer,
+          anonymous: access.anonymous === true,
+          ...(access.subject === undefined ? {} : { subject: access.subject }),
+          request,
+        });
+      } catch {
+        given = { allow: false };
+      }
+      answer = { answer: given, until: at + authorizeTtl * 1_000 };
+      if (authorizeTtl > 0) {
+        if (answers.size > 10_000) {
+          answers.clear();
+        }
+        answers.set(key, answer);
+      }
+    }
+    // Only an explicit allow lets the request on: anything else the check gives is a deny.
+    const given = answer.answer as Partial<{ allow: unknown; code: unknown }> | null | undefined;
+    if (given?.allow === true) {
+      return null;
+    }
+    const code = typeof given?.code === "string" && CODE.test(given.code) ? given.code : undefined;
+    return page(
+      403,
+      "You can't open this anymore",
+      "The app that showed it no longer lets you see it here.",
+      request.method.toUpperCase(),
+      "denied",
+      code,
+    );
+  }
 
   /** The config a served document is served under, checked to fit it and this server. */
   function configFor(name: string, kind: keyof typeof MODES): CompiledConfig {
@@ -318,6 +432,8 @@ export function createServer(options: ServerOptions): PortholeServer {
       i: record.instance,
       w: record.viewer,
       x: Date.now() + sessionSeconds * 1_000,
+      ...(record.anonymous === true ? { a: 1 as const } : {}),
+      ...(record.subject === undefined ? {} : { s: record.subject }),
     };
     const framed = request.headers.get("sec-fetch-dest") !== "document";
     return [
@@ -343,7 +459,8 @@ export function createServer(options: ServerOptions): PortholeServer {
         !isRecord(session) ||
         typeof session.w !== "string" ||
         typeof session.x !== "number" ||
-        session.x <= Date.now()
+        session.x <= Date.now() ||
+        (session.s !== undefined && typeof session.s !== "string")
       ) {
         continue;
       }
@@ -353,14 +470,27 @@ export function createServer(options: ServerOptions): PortholeServer {
       } catch {
         continue;
       }
+      let named: string;
+      try {
+        named = nameOf(instance.scope);
+      } catch {
+        continue;
+      }
       if (
-        keys.label(instance.scope) !== label ||
+        named !== label ||
         (key === null ? instance.document.kind !== "external" : keys.instanceKey(instance) !== key)
       ) {
         continue;
       }
       if (best === null || session.x > best.expiresAt) {
-        best = { instance, viewer: session.w, origin: originOfLabel(label), expiresAt: session.x };
+        best = {
+          instance,
+          viewer: session.w,
+          origin: originOfLabel(label),
+          expiresAt: session.x,
+          ...(session.a === 1 ? { anonymous: true } : {}),
+          ...(typeof session.s === "string" ? { subject: session.s } : {}),
+        };
       }
     }
     return best;
@@ -377,7 +507,7 @@ export function createServer(options: ServerOptions): PortholeServer {
     }
     try {
       const instance = cleanInstance(record.instance);
-      return keys.label(instance.scope) === label ? { ...record, instance } : null;
+      return nameOf(instance.scope) === label ? { ...record, instance } : null;
     } catch {
       return null;
     }
@@ -419,6 +549,8 @@ export function createServer(options: ServerOptions): PortholeServer {
         viewer: record.viewer,
         origin: originOfLabel(label),
         expiresAt: Date.now() + (record.sessionSeconds ?? DEFAULT_SESSION_SECONDS) * 1_000,
+        ...(record.anonymous === true ? { anonymous: true } : {}),
+        ...(record.subject === undefined ? {} : { subject: record.subject }),
       };
     }
     access ??= accessOf(request, label, key);
@@ -428,8 +560,13 @@ export function createServer(options: ServerOptions): PortholeServer {
         "This link has been used",
         "Content here opens once per link. Open it again from the app that showed it.",
         method,
+        "session",
       );
     }
+    const refusal = await denied(request, access);
+    if (refusal !== null) {
+      return refusal;
+    }
     const served = await documentOf(access.instance);
     if (served === null) {
       return page(404, "Not found", "This page, or this version of it, doesn't exist.", method);
@@ -452,13 +589,37 @@ export function createServer(options: ServerOptions): PortholeServer {
         403,
         "This link has been used",
         "A link into an app works once, for a short time. Open it again from the app that showed it.",
+        method,
+        "session",
       );
     }
+    const refusal = await denied(request, {
+      instance: record.instance,
+      viewer: record.viewer,
+      origin: originOfLabel(label),
+      expiresAt: record.expiresAt,
+      ...(record.subject === undefined ? {} : { subject: record.subject }),
+    });
+    if (refusal !== null) {
+      return refusal;
+    }
     const target = new URL(record.instance.document.url);
+    const landing = `${target.pathname}${target.search}${target.hash}`;
+    // In a frame, a page enters the app: it can tell whether the browser kept the cookie (and tell
+    // the host), where a redirect would leave a frame without one showing a refusal. On a tab of
+    // its own, a redirect.
+    if (request.headers.get("sec-fetch-dest") !== "document") {
+      return enterPage(
+        landing,
+        frameAncestors,
+        options.hostOrigins,
+        sessionCookie(request, record),
+      );
+    }
     return new Response(null, {
       status: 303,
       headers: {
-        location: `${target.pathname}${target.search}${target.hash}`,
+        location: landing,
         "set-cookie": sessionCookie(request, record),
         "cache-control": "no-store",
         "referrer-policy": "no-referrer",
@@ -508,8 +669,13 @@ export function createServer(options: ServerOptions): PortholeServer {
         "Open this from the app",
         "This address shows an app only to the people the app opens it for.",
         method,
+        "session",
       );
     }
+    const refusal = await denied(request, access);
+    if (refusal !== null) {
+      return refusal;
+    }
     if (options.upstream === undefined) {
       return page(502, "Nothing serves this app", "The server has no upstream for apps.", method);
     }
@@ -532,23 +698,43 @@ export function createServer(options: ServerOptions): PortholeServer {
     if (host !== domain && !host.endsWith(`.${domain}`)) {
       return null;
     }
-    return { url, label: host.slice(0, Math.max(0, host.length - domain.length - 1)) };
+    const label = host.slice(0, Math.max(0, host.length - domain.length - 1));
+    // A reserved label is another server's namespace (`f` for `<x>.f.<domain>`): it and the names
+    // under it go to the host's own routes. Any other deeper name is ours to refuse.
+    if (reserved.has(label.split(".").at(-1) ?? "")) {
+      return null;
+    }
+    return { url, label };
   }
 
   return {
     contentSource,
 
-    originFor: (scope) => originOfLabel(keys.label(scope)),
+    originFor: (scope) => originOfLabel(nameOf(scope)),
 
     async issue(instance, grant): Promise<FrameLocation> {
       const clean = cleanInstance(instance);
       check(clean);
-      if (
+      const anonymous = grant.anonymous === true;
+      if (anonymous) {
+        if (grant.viewer !== undefined) {
+          throw new TypeError("An anonymous grant names no viewer");
+        }
+        if (clean.document.kind === "external") {
+          throw new TypeError("A url-mode app is never opened anonymously (P046)");
+        }
+      } else if (
         typeof grant.viewer !== "string" ||
         grant.viewer.length === 0 ||
         grant.viewer.length > 512
       ) {
-        throw new TypeError("A grant's viewer is 1 to 512 characters");
+        throw new TypeError("A grant's viewer is 1 to 512 characters (or the grant is anonymous)");
+      }
+      if (
+        grant.subject !== undefined &&
+        (typeof grant.subject !== "string" || grant.subject.length > SUBJECT_MAX)
+      ) {
+        throw new TypeError(`A grant's subject is a string of at most ${SUBJECT_MAX} characters`);
       }
       const ttl = seconds(
         grant.ttlSeconds,
@@ -563,28 +749,41 @@ export function createServer(options: ServerOptions): PortholeServer {
         "sessionSeconds",
       );
       const key = keys.instanceKey(clean);
-      const probe = keys.sign({ i: clean, w: grant.viewer, x: Number.MAX_SAFE_INTEGER });
+      const viewer = anonymous ? "" : grant.viewer;
+      const probe = keys.sign({
+        i: clean,
+        w: viewer,
+        x: Number.MAX_SAFE_INTEGER,
+        ...(anonymous ? { a: 1 } : {}),
+        ...(grant.subject === undefined ? {} : { s: grant.subject }),
+      });
       if (cookieName(key).length + probe.length + 120 > MAX_COOKIE_BYTES) {
         throw new TypeError("This instance is too large to carry in a cookie (fewer origins?)");
       }
       const ticket = newTicket();
       await tickets.put(ticketId(ticket), {
         instance: clean,
-        viewer: grant.viewer,
+        viewer,
         expiresAt: Date.now() + ttl * 1_000,
         ...(grant.sessionSeconds === undefined ? {} : { sessionSeconds }),
+        ...(anonymous ? { anonymous: true } : {}),
+        ...(grant.subject === undefined ? {} : { subject: grant.subject }),
       });
-      const origin = originOfLabel(keys.label(clean.scope));
+      const origin = originOfLabel(nameOf(clean.scope));
       const path =
         clean.document.kind === "external"
           ? `${ENTER_PATH}?ticket=${ticket}`
           : `${PREFIX}d/${key}?ticket=${ticket}`;
-      return { url: `${origin}${path}`, origin };
+      return { url: `${origin}${path}`, origin, reports: true };
     },
 
     async access(request) {
       const at = labelOf(request);
-      return at === null || !LABEL.test(at.label) ? null : accessOf(request, at.label, null);
+      if (at === null || !ours(at.label)) {
+        return null;
+      }
+      const access = accessOf(request, at.label, null);
+      return access === null || (await denied(request, access)) !== null ? null : access;
     },
 
     async handle(request) {
@@ -595,12 +794,23 @@ export function createServer(options: ServerOptions): PortholeServer {
       const { url, label } = at;
       const method = request.method.toUpperCase();
       try {
-        if (!LABEL.test(label)) {
+        if (!ours(label)) {
           return page(404, "Nothing here", "This address names no content.", method);
         }
         if (url.pathname === ENTER_PATH) {
           return await enter(request, url, label);
         }
+        const script = pageScript(url.pathname);
+        if (script !== null) {
+          return script;
+        }
+        if (url.pathname === SESSION_PATH) {
+          // Whether this request's cookie opens its origin's app: the entry page asks.
+          const access = accessOf(request, label, null);
+          const status =
+            access === null ? 401 : (await denied(request, access)) === null ? 204 : 403;
+          return new Response(null, { status, headers: { "cache-control": "no-store" } });
+        }
         const document = DOCUMENT_PATH.exec(url.pathname);
         if (document?.[1] !== undefined) {
           return await serveDocument(request, url, label, document[1]);

package/src/server/tickets.ts

@@ -28,3 +28,68 @@ export function memoryTicketStore(options: { readonly now?: () => number } = {})
     },
   };
 }
+
+/**
+ * The part of a Cloudflare D1 database (or any SQLite-like binding with the same shape) the ticket
+ * store uses: a prepared statement, bound, run or read once.
+ */
+export interface D1Like {
+  prepare(query: string): D1StatementLike;
+}
+
+export interface D1StatementLike {
+  bind(...values: unknown[]): D1StatementLike;
+  run(): Promise<unknown>;
+  first<T = Record<string, unknown>>(): Promise<T | null>;
+}
+
+const TABLE = /^[a-z_][a-z0-9_]{0,62}$/u;
+
+/** The table a D1 ticket store needs (run once, as a migration). */
+export function d1TicketSchema(table = "porthole_tickets"): string {
+  if (!TABLE.test(table)) {
+    throw new TypeError("A ticket table is named with a-z 0-9 _");
+  }
+  return `CREATE TABLE IF NOT EXISTS ${table} (id TEXT PRIMARY KEY, record TEXT NOT NULL, expires_at INTEGER NOT NULL);
+CREATE INDEX IF NOT EXISTS ${table}_expires_at ON ${table} (expires_at);`;
+}
+
+/**
+ * Tickets in a D1 database (P045): shared by every Worker isolate, and taken once by an atomic
+ * `DELETE … RETURNING` (one statement on D1's single primary, so two requests racing for a ticket
+ * can't both get it). Expired tickets are swept as new ones go in. Workers KV is no place for
+ * tickets: it is eventually consistent, so a ticket read in two places could be used twice.
+ */
+export function d1TicketStore(
+  db: D1Like,
+  options: { readonly table?: string; readonly now?: () => number } = {},
+): TicketStore {
+  const table = options.table ?? "porthole_tickets";
+  if (!TABLE.test(table)) {
+    throw new TypeError("A ticket table is named with a-z 0-9 _");
+  }
+  const now = options.now ?? Date.now;
+  return {
+    async put(id, record) {
+      await db.prepare(`DELETE FROM ${table} WHERE expires_at <= ?`).bind(now()).run();
+      await db
+        .prepare(`INSERT INTO ${table} (id, record, expires_at) VALUES (?, ?, ?)`)
+        .bind(id, JSON.stringify(record), record.expiresAt)
+        .run();
+    },
+    async take(id) {
+      const row = await db
+        .prepare(`DELETE FROM ${table} WHERE id = ? RETURNING record, expires_at`)
+        .bind(id)
+        .first<{ record: string; expires_at: number }>();
+      if (row === null || row.expires_at <= now()) {
+        return null;
+      }
+      try {
+        return JSON.parse(row.record) as TicketRecord;
+      } catch {
+        return null;
+      }
+    },
+  };
+}

package/src/server/types.ts

@@ -11,12 +11,45 @@ export interface ContentDomain {
   /** `http` only for `localhost`. */
   readonly scheme: "https" | "http";
   readonly port?: number;
+  /**
+   * The label under `domain` a storage scope is served on (P047). Default: 24 base32 characters
+   * keyed from the scope with the server's secret (stable, not guessable). A host's own (flat
+   * 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;
+  /**
+   * Labels this server never serves or names (another server's namespace under the same domain,
+   * `f` for `<instance>.f.<domain>`, or `www`). Requests for them get null (the host's routes).
+   */
+  readonly reserved?: readonly string[];
 }
 
-/** Who may open an instance, decided by the host before it calls `issue`. */
-export interface Grant {
-  /** The host's id for the viewer: recorded with the ticket, never shown to content. */
-  readonly viewer: string;
+/**
+ * Who may open an instance, decided by the host before it calls `issue`: a viewer the host
+ * knows, or (a public link) nobody in particular. Porthole never interprets either: identity and
+ * authorization policy are the host's (P050).
+ */
+export type Grant = (
+  | {
+      /** The host's id for the viewer: recorded with the ticket, never shown to content. */
+      readonly viewer: string;
+      readonly anonymous?: never;
+    }
+  | {
+      /**
+       * A public link: no viewer (P046). Only for documents (a shell, an artifact version, the
+       * sandbox proxy), never for a url-mode app.
+       */
+      readonly anonymous: true;
+      readonly viewer?: never;
+    }
+) & {
+  /**
+   * The host's own opaque claim, carried in the ticket and the session cookie and handed back to
+   * `authorize` on every request (a session id, a share id). At most 512 characters.
+   */
+  readonly subject?: string;
   /** How long the ticket is good for, seconds (default 60). */
   readonly ttlSeconds?: number;
   /**
@@ -24,11 +57,14 @@ export interface Grant {
    * url-mode app's every request, rides on.
    */
   readonly sessionSeconds?: number;
-}
+};
 
 export interface TicketRecord {
   readonly instance: InstanceRef;
+  /** The grant's viewer; "" for an anonymous grant. */
   readonly viewer: string;
+  readonly anonymous?: boolean;
+  readonly subject?: string;
   /** Epoch milliseconds. */
   readonly expiresAt: number;
   /** The grant's `sessionSeconds`, if it set one. */
@@ -50,7 +86,11 @@ export interface ArtifactStore {
 /** What a request's cookie lets in: one instance, for one viewer, on one origin, until a time. */
 export interface Access {
   readonly instance: InstanceRef;
+  /** The grant's viewer; "" for an anonymous one. */
   readonly viewer: string;
+  readonly anonymous?: boolean;
+  /** The grant's opaque subject, if it had one. */
+  readonly subject?: string;
   /** The content origin the access is for. */
   readonly origin: string;
   /** When the cookie stops being good, epoch milliseconds. */
@@ -64,6 +104,40 @@ export interface Access {
  */
 export type Upstream = (request: Request, access: Access) => Response | Promise<Response>;
 
+/** What `authorize` is asked about: a request the cookie (or ticket) let in. */
+export interface AuthorizeRequest {
+  readonly scope: string;
+  readonly instance: InstanceRef;
+  readonly viewer: string;
+  readonly anonymous: boolean;
+  readonly subject?: string;
+  /** The request itself (its path, method; never its Porthole cookie's value). */
+  readonly request: Request;
+}
+
+/** The host's answer: let it in, or not (with a short reason code for the host's own UI). */
+export type AuthorizeAnswer =
+  | { readonly allow: true }
+  | {
+      readonly allow: false;
+      /** A short code (`revoked`, `left-workspace`): lowercase letters, digits and dashes. */
+      readonly code?: string;
+    };
+
+/**
+ * The host's check on every request its cookie lets in (P050): revocation, membership,
+ * liveness. Porthole calls it after the cookie (or ticket) verifies and before anything of the
+ * content is served; a deny is a 403 page that tells the host why (`blocked: denied`).
+ */
+export interface Authorizer {
+  check(request: AuthorizeRequest): AuthorizeAnswer | Promise<AuthorizeAnswer>;
+  /**
+   * How long an answer may be reused for the same session and scope, seconds. Default 0: asked
+   * on every request. A host opts into a short time for apps with many requests.
+   */
+  readonly ttlSeconds?: number;
+}
+
 export interface ServerOptions {
   readonly content: ContentDomain;
   /** At least 32 random bytes: keys the labels and signs tickets and cookies. */
@@ -79,6 +153,8 @@ export interface ServerOptions {
   readonly tickets?: TicketStore;
   /** Url mode: where an external instance's requests go once let in. Absent: nothing serves them. */
   readonly upstream?: Upstream;
+  /** The host's per-request check (P050). Absent: a good cookie is enough until it ends. */
+  readonly authorize?: Authorizer;
 }
 
 export interface PortholeServer {
@@ -95,8 +171,9 @@ export interface PortholeServer {
    */
   issue(instance: InstanceRef, grant: Grant): Promise<FrameLocation>;
   /**
-   * The access a request's cookie carries for a url-mode app on the request's origin, or null:
-   * for a host's own WebSocket upgrade path, which a fetch-style handler can't take.
+   * The access a request's cookie carries for a url-mode app on the request's origin, or null
+   * (no good cookie, or the host's check denies it): for a host's own WebSocket upgrade path,
+   * which a fetch-style handler can't take.
    */
   access(request: Request): Promise<Access | null>;
   /** The frame source every content origin matches (`https://*.example-usercontent.com`). */

package/src/shell/document.ts

@@ -1,11 +1,13 @@
+import { hostOriginProblem } from "../isolation/served.ts";
 import { SHELL_RUNTIME } from "./runtime.ts";
 import type { ShellPlan } from "./plan.ts";
 
 export interface ShellDocumentOptions {
   /**
    * The origins the shell takes messages from: the embedding page's own (`location.origin`), or
-   * every host origin a served document may be embedded by. Exact origins, no wildcards. The
-   * sender must also be the frame's parent.
+   * every host origin a served document may be embedded by. Exact origins of any scheme (a
+   * desktop app's own, `ferry://app`), no wildcards, never "null". The sender must also be the
+   * frame's parent.
    */
   readonly origins: readonly string[];
   /** The frame document's title (for assistive technology inside the frame). */
@@ -24,8 +26,6 @@ export interface ShellDocumentOptions {
   readonly cspMeta?: boolean;
 }
 
-const EXACT_ORIGIN = /^(https?:\/\/[a-z0-9.-]+(:\d{1,5})?|https?:\/\/\[::1\](:\d{1,5})?)$/u;
-
 const escapeAttribute = (value: string): string =>
   value.replace(/&/gu, "&amp;").replace(/"/gu, "&quot;").replace(/</gu, "&lt;");
 
@@ -80,8 +80,9 @@ body {
  */
 export function shellDocument(plan: ShellPlan, csp: string, options: ShellDocumentOptions): string {
   for (const origin of options.origins) {
-    if (!EXACT_ORIGIN.test(origin)) {
-      throw new TypeError(`shellDocument: ${JSON.stringify(origin)} is not an exact origin`);
+    const problem = hostOriginProblem(origin);
+    if (problem !== null) {
+      throw new TypeError(`shellDocument: ${problem}`);
     }
   }
   const runtime = SHELL_RUNTIME.replace("__PLAN__", () =>