@botiverse/porthole 0.1.1 → 0.1.2

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

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`). */