@botiverse/porthole 0.1.7 → 0.2.0

package/src/server/index.ts

@@ -9,6 +9,11 @@
  *
  * and calls `issue` from its own authenticated API when a viewer opens served content.
  *
+ * The host kit (P066): `createContentHost` wraps `createServer` with the routing middleware
+ * (`fetch`), the issue endpoint (`issue`), the content domain's parsing and clash guards
+ * (`contentDomain`), and an optional health gate with an opaque fallback. An app writes its four
+ * policy callbacks and its settings; on Node, `@botiverse/porthole/node` adapts it.
+ *
  * Runs on any runtime with web-standard `Request`/`Response` and `crypto.getRandomValues`: Node,
  * Cloudflare Workers (no `nodejs_compat` needed), Deno, Bun (P044). On Workers, keep tickets in D1
  * (`d1TicketStore`, P045).
@@ -28,6 +33,26 @@
  * 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 {
+  clashOf,
+  contentDomain,
+  ContentDomainError,
+  hostnameOf,
+  type ContentDomainInfo,
+  type ContentDomainProblem,
+} from "./domain.ts";
 export {
   d1TicketSchema,
   d1TicketStore,
@@ -36,7 +61,7 @@ export {
   type D1StatementLike,
 } from "./tickets.ts";
 export { FRAME_STATUS_METHOD } from "../isolation/types.ts";
-export { isHostLabel, prefixedName } from "./naming.ts";
+export { isHostLabel, prefixedName, type Naming } from "./naming.ts";
 export { proxyTo, type ProxyOptions } from "./proxy.ts";
 export type {
   Access,
@@ -45,6 +70,7 @@ export type {
   AuthorizeRequest,
   Authorizer,
   ContentDomain,
+  EntryState,
   Grant,
   PortholeServer,
   ServerOptions,

package/src/server/naming.ts

@@ -24,13 +24,25 @@ const ID = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/u;
  * already be label-safe (lowercase letters, digits, inner hyphens); anything else throws rather
  * than being folded into another scope's name.
  */
-export function prefixedName(prefix: string): (scope: string) => string {
+/**
+ * How scopes are named (`ContentDomain.name`). A naming that can say which scope a label names
+ * (`scopeOf`) gives every scope clean addresses a redirect entry can open (P068).
+ */
+export interface Naming {
+  (scope: string): string;
+  /** The scope a label names, or null for a label this naming never makes. */
+  readonly scopeOf?: (label: string) => string | null;
+}
+
+export function prefixedName(prefix: string): Naming & {
+  readonly scopeOf: (label: string) => string | null;
+} {
   if (!PREFIX.test(prefix)) {
     throw new TypeError(
       "A name prefix is a lowercase letter, then letters or digits, then '-' (a-)",
     );
   }
-  return (scope) => {
+  const name = (scope: string): string => {
     const label = `${prefix}${scope}`;
     if (!ID.test(scope) || !isHostLabel(label)) {
       throw new TypeError(
@@ -39,6 +51,14 @@ export function prefixedName(prefix: string): (scope: string) => string {
     }
     return label;
   };
+  const scopeOf = (label: string): string | null => {
+    if (!label.startsWith(prefix)) {
+      return null;
+    }
+    const scope = label.slice(prefix.length);
+    return ID.test(scope) && isHostLabel(label) ? scope : null;
+  };
+  return Object.assign(name, { scopeOf });
 }
 
 const PREFIX_ENTRY = /^[a-z0-9]([a-z0-9-]{0,61})?\*$/u;

package/src/server/pages.ts

@@ -1,5 +1,6 @@
 import { FRAME_STATUS_METHOD } from "../isolation/types.ts";
 import type { FrameBlock } from "../host/types.ts";
+import { base64url, sha256, utf8 } from "./crypto.ts";
 
 /**
  * The server's own pages on a content origin: why it shows nothing of the content, and the page a
@@ -126,3 +127,46 @@ export function enterPage(
   headers.set("set-cookie", cookie);
   return new Response(body, { status: 200, headers });
 }
+
+/** The status script's hash, for a page that carries it inline (`script-src 'sha256-…'`). */
+let statusHash: string | null = null;
+const hashOfStatus = (): string => {
+  statusHash ??= base64url(sha256(utf8(STATUS_SCRIPT)))
+    .replace(/-/gu, "+")
+    .replace(/_/gu, "/");
+  const padding = (4 - (statusHash.length % 4)) % 4;
+  return `'sha256-${statusHash}${"=".repeat(padding)}'`;
+};
+
+/**
+ * A redirect entry's page on the app's own origin (P068): why it shows nothing, told to the page
+ * that frames it like a content origin's page. Plain, no app chrome; its one script inline under
+ * its hash (the app origin serves no script of Porthole's).
+ */
+export function appStatusPage(
+  status: number,
+  title: string,
+  detail: string,
+  frameAncestors: string,
+  reason: FrameBlock,
+  hostOrigins: readonly string[],
+  link?: { readonly href: string; readonly text: string },
+  method = "GET",
+): Response {
+  const more =
+    link === undefined
+      ? ""
+      : `<p><a href="${escape(link.href)}" target="_top" rel="noopener">${escape(link.text)}</a></p>`;
+  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}a{color:inherit}</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>${more}</main><script>${STATUS_SCRIPT}</script></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'; script-src ${hashOfStatus()}; base-uri 'none'; form-action 'none'; frame-ancestors ${frameAncestors}`,
+      "referrer-policy": "no-referrer",
+      "x-content-type-options": "nosniff",
+      "x-robots-tag": "noindex, nofollow",
+    },
+  });
+}

package/src/server/server.ts

@@ -8,7 +8,8 @@ import {
 } from "../isolation/served.ts";
 import type { FrameLocation, InstanceRef, ServedDocument } from "../isolation/types.ts";
 import { sandboxProxyDocument } from "../mcp/proxy.ts";
-import { createKeys, newTicket, ticketId } from "./keys.ts";
+import { base32, createKeys, newTicket, ticketId } from "./keys.ts";
+import { randomBytes } from "./crypto.ts";
 import { isHostLabel, reservedLabels } from "./naming.ts";
 import { enterPage, pageScript, SESSION_PATH, statusPage } from "./pages.ts";
 import type { FrameBlock } from "../host/types.ts";
@@ -16,6 +17,8 @@ import { memoryTicketStore } from "./tickets.ts";
 import type {
   Access,
   AuthorizeAnswer,
+  EntryState,
+  Grant,
   PortholeServer,
   ServerOptions,
   TicketRecord,
@@ -31,6 +34,15 @@ const PREFIX = "/__porthole/";
 const DOCUMENT_PATH = /^\/__porthole\/d\/([a-z2-7]{16})$/u;
 /** Where a url-mode app's ticket is taken, before the app's own landing path. */
 const ENTER_PATH = "/__porthole/enter";
+/** Where a redirect entry's code is redeemed, before its clean address (P068). */
+const ENTRY_PATH = "/__porthole/entry";
+/** How long a redirect entry may take (the person may sign in on the way), and its code. */
+const ENTRY_STATE_MS = 5 * 60_000;
+const ENTRY_CODE_SECONDS = 60;
+/** How long an entered path is remembered, so an entry that kept no cookie doesn't loop. */
+const ENTERED_SECONDS = 60;
+const NONCE = /^[a-z2-7]{16}$/u;
+const MAX_PATH = 2_048;
 
 const LABEL = /^[a-z2-7]{24}$/u;
 /** A host's opaque subject and reason codes. */
@@ -68,6 +80,8 @@ interface Session {
   readonly x: number;
   readonly a?: 1;
   readonly s?: string;
+  /** The clean path a document was entered at (P068): it is served there by this cookie. */
+  readonly p?: string;
 }
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
@@ -263,6 +277,19 @@ export function createServer(options: ServerOptions): PortholeServer {
     }
   }
   const frameAncestors = options.hostOrigins.join(" ");
+  let authorizeUrl: URL | null = null;
+  if (options.entry !== undefined) {
+    try {
+      authorizeUrl = new URL(options.entry.authorizeUrl);
+    } catch {
+      throw new TypeError("entry.authorizeUrl must be an absolute URL");
+    }
+    if (!options.hostOrigins.includes(authorizeUrl.origin) || authorizeUrl.hash !== "") {
+      throw new TypeError(
+        `entry.authorizeUrl must be on one of the host origins (${options.hostOrigins.join(", ")}), without a fragment`,
+      );
+    }
+  }
 
   const compiled = new Map<string, CompiledConfig>();
   for (const [name, config] of Object.entries(options.configs)) {
@@ -435,7 +462,7 @@ export function createServer(options: ServerOptions): PortholeServer {
    * page that frames it; on a tab of its own, `Lax`. (Engines that keep no cookie in a cross-site
    * frame, measured: WebKit, still get the document, which comes with the ticket's answer.)
    */
-  function sessionCookie(request: Request, record: TicketRecord): string {
+  function sessionCookie(request: Request, record: TicketRecord, path?: string): string {
     const sessionSeconds = record.sessionSeconds ?? DEFAULT_SESSION_SECONDS;
     const session: Session = {
       i: record.instance,
@@ -443,19 +470,30 @@ export function createServer(options: ServerOptions): PortholeServer {
       x: Date.now() + sessionSeconds * 1_000,
       ...(record.anonymous === true ? { a: 1 as const } : {}),
       ...(record.subject === undefined ? {} : { s: record.subject }),
+      ...(path === undefined ? {} : { p: path }),
     };
-    const framed = request.headers.get("sec-fetch-dest") !== "document";
     return [
       `${cookieName(keys.instanceKey(record.instance))}=${keys.sign(session)}`,
       "Path=/",
       "HttpOnly",
       `Max-Age=${sessionSeconds}`,
-      ...(framed
-        ? ["Secure", "SameSite=None", "Partitioned"]
-        : [...(secure ? ["Secure"] : []), "SameSite=Lax"]),
+      ...cookieContext(request),
     ].join("; ");
   }
 
+  /** A cookie's context: a third party's in a frame (partitioned), first-party `Lax` on a tab. */
+  function cookieContext(request: Request): string[] {
+    const framed = request.headers.get("sec-fetch-dest") !== "document";
+    return framed
+      ? ["Secure", "SameSite=None", "Partitioned"]
+      : [...(secure ? ["Secure"] : []), "SameSite=Lax"];
+  }
+
+  /** The cookie a redirect entry's browser holds while it is away (P068), by its nonce. */
+  const nonceCookie = (nonce: string): string => cookieName(`n-${nonce}`);
+  /** What an entered path's nonce cookie says after its code was redeemed: the loop guard. */
+  const enteredMark = (pathname: string): string => `e.${keys.instanceKey({ entered: pathname })}`;
+
   /** The access a request's own cookies give on `label`'s origin, for `key`'s instance or the app. */
   function accessOf(request: Request, label: string, key: string | null): Access | null {
     let best: Access | null = null;
@@ -505,6 +543,47 @@ export function createServer(options: ServerOptions): PortholeServer {
     return best;
   }
 
+  /** The access a request's cookies give to the document entered at `pathname` (P068). */
+  function accessAtPath(request: Request, label: string, pathname: string): Access | null {
+    let best: Access | null = null;
+    for (const [name, value] of cookiesOf(request)) {
+      if (!ourCookie(name)) {
+        continue;
+      }
+      const session = keys.verify(value);
+      if (
+        !isRecord(session) ||
+        session.p !== pathname ||
+        typeof session.w !== "string" ||
+        typeof session.x !== "number" ||
+        session.x <= Date.now() ||
+        (session.s !== undefined && typeof session.s !== "string")
+      ) {
+        continue;
+      }
+      let instance: InstanceRef;
+      try {
+        instance = cleanInstance(session.i);
+        if (instance.document.kind === "external" || nameOf(instance.scope) !== label) {
+          continue;
+        }
+      } catch {
+        continue;
+      }
+      if (best === null || session.x > best.expiresAt) {
+        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;
+  }
+
   /** A taken ticket, if it is good for `label`'s origin. */
   async function take(ticket: string | null, label: string): Promise<TicketRecord | null> {
     if (ticket === null || ticket.length === 0 || ticket.length > 128) {
@@ -573,6 +652,16 @@ export function createServer(options: ServerOptions): PortholeServer {
         "session",
       );
     }
+    return serveAccess(request, access, cookie);
+  }
+
+  /** The document an access opens, once the host's check lets it in. */
+  async function serveAccess(
+    request: Request,
+    access: Access,
+    cookie: string | null,
+  ): Promise<Response> {
+    const method = request.method.toUpperCase();
     const refusal = await denied(request, access);
     if (refusal !== null) {
       return refusal;
@@ -588,6 +677,135 @@ export function createServer(options: ServerOptions): PortholeServer {
     return new Response(method === "HEAD" ? null : served.html, { status: 200, headers });
   }
 
+  /**
+   * A clean address without a cookie for it (P068): off to the host's authorize route with a
+   * 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: Request, url: URL, label: string, to: URL): Response {
+    const method = request.method.toUpperCase();
+    if (method !== "GET" && method !== "HEAD") {
+      return page(
+        401,
+        "Open this from the app",
+        "Open this address in a browser.",
+        method,
+        "session",
+      );
+    }
+    const path = `${url.pathname}${url.search}`;
+    if (path.length > MAX_PATH) {
+      return page(414, "Address too long", "This address is too long to open.", method);
+    }
+    const mark = enteredMark(url.pathname);
+    if (cookiesOf(request).some(([name, value]) => ourCookie(name) && value === mark)) {
+      return page(
+        401,
+        "Open this in a new tab",
+        "This browser keeps no sign-in for it inside a frame.",
+        method,
+        "cookies",
+      );
+    }
+    const nonce = base32(randomBytes(10));
+    const framed = request.headers.get("sec-fetch-dest") !== "document";
+    const state = keys.sign({
+      e: 1,
+      l: label,
+      p: path,
+      n: nonce,
+      x: Date.now() + ENTRY_STATE_MS,
+      f: framed ? 1 : 0,
+    });
+    const location = new URL(to);
+    location.searchParams.set("state", state);
+    return new Response(null, {
+      status: 302,
+      headers: {
+        location: location.href,
+        "set-cookie": [
+          `${nonceCookie(nonce)}=1`,
+          "Path=/",
+          "HttpOnly",
+          `Max-Age=${ENTRY_STATE_MS / 1_000}`,
+          ...cookieContext(request),
+        ].join("; "),
+        "cache-control": "no-store",
+        "referrer-policy": "no-referrer",
+        "x-robots-tag": "noindex, nofollow",
+      },
+    });
+  }
+
+  /**
+   * Redeems a redirect entry's code (P068): once, on its own label, in the browser that began it
+   * (its nonce cookie comes with it). Sets the session and goes to the clean address, the code
+   * gone from the address bar and from any referrer.
+   */
+  async function redeem(request: Request, url: URL, label: string): Promise<Response> {
+    const method = request.method.toUpperCase();
+    if (method !== "GET") {
+      return page(405, "Not allowed", "Open this link in a browser.", method);
+    }
+    const record = await take(url.searchParams.get("code"), label);
+    if (record?.entry === undefined) {
+      return page(
+        403,
+        "This sign-in link has been used",
+        "It works once, for a short time. Open the address again.",
+        method,
+        "session",
+      );
+    }
+    const { nonce, path } = record.entry;
+    const named = nonceCookie(nonce);
+    if (!cookiesOf(request).some(([name, value]) => name === named && value === "1")) {
+      return page(
+        401,
+        "Open this in a new tab",
+        "This browser keeps no sign-in for it inside a frame.",
+        method,
+        "cookies",
+      );
+    }
+    const origin = originOfLabel(label);
+    const target = new URL(path, origin);
+    const access: Access = {
+      instance: record.instance,
+      viewer: record.viewer,
+      origin,
+      expiresAt: Date.now() + (record.sessionSeconds ?? DEFAULT_SESSION_SECONDS) * 1_000,
+      ...(record.anonymous === true ? { anonymous: true } : {}),
+      ...(record.subject === undefined ? {} : { subject: record.subject }),
+    };
+    const refusal = await denied(request, access);
+    if (refusal !== null) {
+      return refusal;
+    }
+    const external = record.instance.document.kind === "external";
+    const headers = new Headers({
+      location: `${origin}${target.pathname}${target.search}`,
+      "cache-control": "no-store",
+      "referrer-policy": "no-referrer",
+      "x-robots-tag": "noindex, nofollow",
+    });
+    headers.append(
+      "set-cookie",
+      sessionCookie(request, record, external ? undefined : target.pathname),
+    );
+    headers.append(
+      "set-cookie",
+      [
+        `${named}=${enteredMark(target.pathname)}`,
+        "Path=/",
+        "HttpOnly",
+        `Max-Age=${ENTERED_SECONDS}`,
+        ...cookieContext(request),
+      ].join("; "),
+    );
+    return new Response(null, { status: 303, headers });
+  }
+
   async function enter(request: Request, url: URL, label: string): Promise<Response> {
     const method = request.method.toUpperCase();
     if (method !== "GET") {
@@ -696,6 +914,68 @@ export function createServer(options: ServerOptions): PortholeServer {
     }
   }
 
+  /** A one-time ticket (or entry code) for an instance the host decided a viewer may see. */
+  async function mint(
+    instance: InstanceRef,
+    grant: Grant,
+    entry?: TicketRecord["entry"],
+  ): Promise<{ readonly clean: InstanceRef; readonly key: string; readonly ticket: string }> {
+    const clean = cleanInstance(instance);
+    check(clean);
+    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 (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, DEFAULT_TICKET_SECONDS, MAX_TICKET_SECONDS, "ttlSeconds");
+    const sessionSeconds = seconds(
+      grant.sessionSeconds,
+      DEFAULT_SESSION_SECONDS,
+      MAX_SESSION_SECONDS,
+      "sessionSeconds",
+    );
+    const key = keys.instanceKey(clean);
+    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 }),
+      ...(entry === undefined ? {} : { p: entry.path }),
+    });
+    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,
+      expiresAt: Date.now() + ttl * 1_000,
+      ...(grant.sessionSeconds === undefined ? {} : { sessionSeconds }),
+      ...(anonymous ? { anonymous: true } : {}),
+      ...(grant.subject === undefined ? {} : { subject: grant.subject }),
+      ...(entry === undefined ? {} : { entry }),
+    });
+    return { clean, key, ticket };
+  }
+
   const underDomain = (host: string): boolean => host === domain || host.endsWith(`.${domain}`);
 
   /**
@@ -749,62 +1029,7 @@ export function createServer(options: ServerOptions): PortholeServer {
     originFor: (scope) => originOfLabel(nameOf(scope)),
 
     async issue(instance, grant): Promise<FrameLocation> {
-      const clean = cleanInstance(instance);
-      check(clean);
-      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 (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,
-        DEFAULT_TICKET_SECONDS,
-        MAX_TICKET_SECONDS,
-        "ttlSeconds",
-      );
-      const sessionSeconds = seconds(
-        grant.sessionSeconds,
-        DEFAULT_SESSION_SECONDS,
-        MAX_SESSION_SECONDS,
-        "sessionSeconds",
-      );
-      const key = keys.instanceKey(clean);
-      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,
-        expiresAt: Date.now() + ttl * 1_000,
-        ...(grant.sessionSeconds === undefined ? {} : { sessionSeconds }),
-        ...(anonymous ? { anonymous: true } : {}),
-        ...(grant.subject === undefined ? {} : { subject: grant.subject }),
-      });
+      const { clean, key, ticket } = await mint(instance, grant);
       const origin = originOfLabel(nameOf(clean.scope));
       const path =
         clean.document.kind === "external"
@@ -813,6 +1038,57 @@ export function createServer(options: ServerOptions): PortholeServer {
       return { url: `${origin}${path}`, origin, reports: true };
     },
 
+    urlOf(scope, path = "/") {
+      if (!path.startsWith("/") || path.startsWith("//") || path.startsWith(PREFIX)) {
+        throw new TypeError("A clean address's path starts with one / and isn't Porthole's own");
+      }
+      return `${originOfLabel(nameOf(scope))}${path}`;
+    },
+
+    entryState(token) {
+      const state = token.length > 8_192 ? null : keys.verify(token);
+      if (
+        !isRecord(state) ||
+        state.e !== 1 ||
+        typeof state.l !== "string" ||
+        !ours(state.l) ||
+        typeof state.p !== "string" ||
+        !state.p.startsWith("/") ||
+        typeof state.n !== "string" ||
+        !NONCE.test(state.n) ||
+        typeof state.x !== "number" ||
+        (state.f !== 0 && state.f !== 1)
+      ) {
+        return null;
+      }
+      return {
+        label: state.l,
+        path: state.p,
+        nonce: state.n,
+        framed: state.f === 1,
+        expired: state.x <= Date.now(),
+      };
+    },
+
+    async enterBy(state: EntryState, instance: InstanceRef, grant: Grant): Promise<string> {
+      if (state.expired) {
+        throw new TypeError("This entry's state has expired: start again from the clean address");
+      }
+      const clean = cleanInstance(instance);
+      if (nameOf(clean.scope) !== state.label) {
+        throw new TypeError("The instance isn't served on the address the entry began at");
+      }
+      const { ticket } = await mint(
+        clean,
+        { ...grant, ttlSeconds: ENTRY_CODE_SECONDS },
+        {
+          path: state.path,
+          nonce: state.nonce,
+        },
+      );
+      return `${originOfLabel(state.label)}${ENTRY_PATH}?code=${ticket}`;
+    },
+
     async access(request) {
       const at = labelOf(request);
       if (at === null || at === "mismatch" || !ours(at.label)) {
@@ -844,6 +1120,9 @@ export function createServer(options: ServerOptions): PortholeServer {
         if (url.pathname === ENTER_PATH) {
           return await enter(request, url, label);
         }
+        if (url.pathname === ENTRY_PATH && authorizeUrl !== null) {
+          return await redeem(request, url, label);
+        }
         const script = pageScript(url.pathname);
         if (script !== null) {
           return script;
@@ -859,8 +1138,21 @@ export function createServer(options: ServerOptions): PortholeServer {
         if (document?.[1] !== undefined) {
           return await serveDocument(request, url, label, document[1]);
         }
+        if (url.pathname.startsWith(PREFIX)) {
+          return page(404, "Nothing here", "This address names no content.", method);
+        }
+        // A clean address (P068): the document entered here, else the app, else entry.
+        if (authorizeUrl !== null) {
+          const entered = accessAtPath(request, label, url.pathname);
+          if (entered !== null) {
+            return await serveAccess(request, entered, null);
+          }
+          if (options.upstream === undefined || accessOf(request, label, null) === null) {
+            return beginEntry(request, url, label, authorizeUrl);
+          }
+        }
         // Without an upstream, only Porthole's own paths are served here: any other is nothing.
-        if (url.pathname.startsWith(PREFIX) || options.upstream === undefined) {
+        if (options.upstream === undefined) {
           return page(404, "Nothing here", "This address names no content.", method);
         }
         return await serveApp(request, label);