@botiverse/porthole 0.1.1 → 0.1.3

package/src/server/index.ts

@@ -9,12 +9,18 @@
  *
  * and calls `issue` from its own authenticated API when a viewer opens served content.
  *
+ * 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).
+ *
  * 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
+ * secret (stable, DNS-safe, not guessable from the scope), or a host's own flat name
+ * (`content.name`, `prefixedName("a-")` for `a-<id>`), with other servers' namespaces reserved (P047). 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;
+ * Tickets: `issue` mints a one-time ticket for an instance and a viewer (or anonymously, for a
+ * public link, P046), 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
@@ -22,11 +28,22 @@
  * content without a valid ticket or cookie gets nothing of the content.
  */
 export { createServer } from "./server.ts";
-export { memoryTicketStore } from "./tickets.ts";
+export {
+  d1TicketSchema,
+  d1TicketStore,
+  memoryTicketStore,
+  type D1Like,
+  type D1StatementLike,
+} from "./tickets.ts";
+export { FRAME_STATUS_METHOD } from "../isolation/types.ts";
+export { isHostLabel, prefixedName } from "./naming.ts";
 export { proxyTo, type ProxyOptions } from "./proxy.ts";
 export type {
   Access,
   ArtifactStore,
+  AuthorizeAnswer,
+  AuthorizeRequest,
+  Authorizer,
   ContentDomain,
   Grant,
   PortholeServer,

package/src/server/keys.ts

@@ -1,4 +1,13 @@
-import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import {
+  base64url,
+  fromBase64url,
+  fromUtf8,
+  hmacSha256,
+  randomBytes,
+  sha256,
+  timingSafeEqual,
+  utf8,
+} from "./crypto.ts";
 
 /**
  * The server's secrets, derived from the one it is given: one key per use, so a value made for
@@ -27,8 +36,6 @@ export function base32(bytes: Uint8Array): string {
   return out;
 }
 
-const base64url = (bytes: Uint8Array): string => Buffer.from(bytes).toString("base64url");
-
 /** JSON with object keys in a fixed order, so equal values always serialize alike. */
 export function canonicalJson(value: unknown): string {
   if (Array.isArray(value)) {
@@ -58,19 +65,17 @@ export function createKeys(secret: Uint8Array): Keys {
   if (secret.byteLength < 32) {
     throw new TypeError("The server's secret must be at least 32 random bytes");
   }
-  const derive = (use: string): Buffer =>
-    createHmac("sha256", secret).update(`porthole/${use}`).digest();
+  const derive = (use: string): Uint8Array => hmacSha256(secret, utf8(`porthole/${use}`));
   const labelKey = derive("label");
   const instanceKey = derive("instance");
   const signKey = derive("session");
-  const mac = (key: Buffer, text: string): Buffer =>
-    createHmac("sha256", key).update(text).digest();
+  const mac = (key: Uint8Array, text: string): Uint8Array => hmacSha256(key, utf8(text));
 
   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");
+      const payload = base64url(utf8(JSON.stringify(value)));
       return `${payload}.${base64url(mac(signKey, payload))}`;
     },
     verify: (token) => {
@@ -79,12 +84,16 @@ export function createKeys(secret: Uint8Array): Keys {
         return null;
       }
       const expected = mac(signKey, payload);
-      const given = Buffer.from(signature, "base64url");
-      if (given.length !== expected.length || !timingSafeEqual(given, expected)) {
+      const given = fromBase64url(signature);
+      if (given === null || !timingSafeEqual(given, expected)) {
+        return null;
+      }
+      const bytes = fromBase64url(payload);
+      if (bytes === null) {
         return null;
       }
       try {
-        return JSON.parse(Buffer.from(payload, "base64url").toString("utf8")) as unknown;
+        return JSON.parse(fromUtf8(bytes)) as unknown;
       } catch {
         return null;
       }
@@ -96,5 +105,4 @@ export function createKeys(secret: Uint8Array): Keys {
 export const newTicket = (): string => `pt_${base32(randomBytes(20))}`;
 
 /** What a ticket is stored under: its hash, so a leaked store holds no usable ticket. */
-export const ticketId = (ticket: string): string =>
-  createHash("sha256").update(ticket).digest("base64url");
+export const ticketId = (ticket: string): string => base64url(sha256(utf8(ticket)));

package/src/server/naming.ts

@@ -0,0 +1,42 @@
+/**
+ * Names for content origins a host chooses itself (P047): flat labels like `a-<id>` under a
+ * shared content domain, next to other servers' namespaces (`<instance>.f.<domain>`).
+ */
+
+/** One lowercase DNS label (a-z 0-9 -, at most 63, no hyphen at either end). */
+const DNS_LABEL = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/u;
+
+/**
+ * Whether a label is one a host may name a content origin with: one lowercase DNS label, and not
+ * of the form IDNA reserves (`xn--`, any `??--`), so a name never displays as something else.
+ */
+export function isHostLabel(label: unknown): label is string {
+  return typeof label === "string" && DNS_LABEL.test(label) && label.slice(2, 4) !== "--";
+}
+
+const PREFIX = /^[a-z][a-z0-9]{0,15}-$/u;
+const ID = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/u;
+
+/**
+ * A naming for `content.name` that puts each scope on `<prefix><scope>` (`prefixedName("a-")`:
+ * scope `k3x9` is served on `a-k3x9.<domain>`). One-to-one, so no two scopes share an origin, and
+ * no name it makes is a reserved one or a keyed default (those have no hyphen). Scopes must
+ * 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 {
+  if (!PREFIX.test(prefix)) {
+    throw new TypeError(
+      "A name prefix is a lowercase letter, then letters or digits, then '-' (a-)",
+    );
+  }
+  return (scope) => {
+    const label = `${prefix}${scope}`;
+    if (!ID.test(scope) || !isHostLabel(label)) {
+      throw new TypeError(
+        `Scope ${JSON.stringify(scope)} can't be named under ${prefix}: lowercase letters, digits and inner hyphens, ${63 - prefix.length} at most`,
+      );
+    }
+    return label;
+  };
+}

package/src/server/pages.ts

@@ -30,13 +30,15 @@ const STATUS_SCRIPT = `(() => {
   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) });
+  const blocked = { state: "blocked", reason: main.dataset.portholeReason || "error", status: Number(main.dataset.portholeStatus) };
+  if (main.dataset.portholeCode) blocked.code = main.dataset.portholeCode;
+  say(blocked);
 })();`;
 
 /**
  * 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.
+ * answer set (WebKit keeps none in a cross-site frame, P025), then, once this page has loaded,
+ * goes on to the app, or says it is blocked and why.
  */
 const ENTER_SCRIPT = `(async () => {
   const main = document.querySelector("[data-porthole-enter]");
@@ -49,6 +51,12 @@ const ENTER_SCRIPT = `(async () => {
     kept = (await fetch(${JSON.stringify(SESSION_PATH)}, { credentials: "same-origin", cache: "no-store" })).ok;
   } catch (_) {}
   if (kept) {
+    // The host counts this page's load, then the app's (P040): leave only once this page has
+    // loaded, or a fast answer would leave first and its load would never be seen.
+    if (document.readyState !== "complete") {
+      await new Promise((resolve) => addEventListener("load", resolve, { once: true }));
+    }
+    await new Promise((resolve) => setTimeout(resolve, 0));
     location.replace(main.dataset.portholeTarget || "/");
     return;
   }
@@ -95,8 +103,9 @@ export function statusPage(
   method = "GET",
   reason: FrameBlock = "error",
   hostOrigins: readonly string[] = [],
+  code?: string,
 ): Response {
-  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>`;
+  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)}"${code === undefined ? "" : ` data-porthole-code="${escape(code)}"`} 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),

package/src/server/server.ts

@@ -9,10 +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 { 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
@@ -25,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;
 
@@ -35,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> =>
@@ -174,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 =
@@ -183,6 +223,12 @@ 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");
@@ -222,8 +268,63 @@ export function createServer(options: ServerOptions): PortholeServer {
     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);
+    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 {
@@ -331,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 [
@@ -356,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;
       }
@@ -366,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;
@@ -390,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;
     }
@@ -432,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);
@@ -444,6 +563,10 @@ export function createServer(options: ServerOptions): PortholeServer {
         "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);
@@ -470,6 +593,16 @@ export function createServer(options: ServerOptions): PortholeServer {
         "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
@@ -539,6 +672,10 @@ export function createServer(options: ServerOptions): PortholeServer {
         "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);
     }
@@ -561,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,
@@ -592,18 +749,27 @@ 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}`
@@ -613,7 +779,11 @@ export function createServer(options: ServerOptions): PortholeServer {
 
     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) {
@@ -624,7 +794,7 @@ 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) {
@@ -636,10 +806,10 @@ export function createServer(options: ServerOptions): PortholeServer {
         }
         if (url.pathname === SESSION_PATH) {
           // Whether this request's cookie opens its origin's app: the entry page asks.
-          return new Response(null, {
-            status: accessOf(request, label, null) === null ? 401 : 204,
-            headers: { "cache-control": "no-store" },
-          });
+          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) {

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;
+      }
+    },
+  };
+}