@volter/world-runtime 3.0.13 → 3.0.14

package/dist/src/world-origins.js

@@ -10,6 +10,27 @@ export function localWorldOrigin(served, port, base = LOCAL_ORIGIN_BASE) {
     const label = worldOriginLabel(served);
     return label ? `http://${label}.${base}:${port}` : null;
 }
+/** THE CONTENT PLANE's label beside a World's own: `<world>--<org>--pages`, where a browser sees the World's twins'
+ *  pages apart from its doors and its session. A World of an org named `pages` (`<world>--pages`) is no content plane:
+ *  its label names no World once the suffix is taken off, so it falls through to the World it is. */
+export const PAGES_LABEL_SUFFIX = '--pages';
+/** The content plane's origin for `served` on a host whose World origins are `<label>.<base>`, or null when its names
+ *  make no label. */
+export function pagesOriginOf(served, protocol, base, port) {
+    const label = worldOriginLabel(served);
+    return label && label.length + PAGES_LABEL_SUFFIX.length <= 63 ? `${protocol}//${label}${PAGES_LABEL_SUFFIX}.${base}${port ? `:${port}` : ''}` : null;
+}
+/** Which World's content plane a request's host names, or undefined for any other host. */
+export function pagesOfHost(hostname, served, base = LOCAL_ORIGIN_BASE) {
+    const suffix = `${PAGES_LABEL_SUFFIX}.${base}`;
+    if (!hostname.endsWith(suffix))
+        return undefined;
+    const label = hostname.slice(0, -suffix.length);
+    for (const name of served)
+        if (worldOriginLabel(name) === label)
+            return name;
+    return undefined;
+}
 /** Which World a request's host names: undefined for a host that is not a World's origin (the host's
  *  own, path-addressed), null for a World-origin-shaped host naming no World served here. */
 export function worldOfHost(hostname, served, base = LOCAL_ORIGIN_BASE) {

package/dist/src/world-view.js

@@ -8,7 +8,7 @@ import { join, resolve } from 'node:path';
 import { serveHttp, stateDirName } from '@volter/world-core/runtime';
 import { followParentPins, LocalBranches } from "./local-branches.js";
 import { mountWorld } from "./served-world.js";
-import { localWorldOrigin, pathOfWorld, siteOfHost, worldDoorUnderConsole, worldOfHost } from "./world-origins.js";
+import { localWorldOrigin, pagesOfHost, pagesOriginOf, pathOfWorld, siteOfHost, worldDoorUnderConsole, worldOfHost } from "./world-origins.js";
 export const VIEW_CONSOLE_BASE = '/-/console';
 /** The branch Worlds already under `dir` (`<dir>/<org>/<world>/.volter/world.json`). */
 function branchRoots(dir) {
@@ -50,7 +50,9 @@ export async function serveWorldView(name, opts = {}) {
     const browserOrigin = origins ? (served) => (proxied && (base === null || served === base) ? proxied.origin : port ? localWorldOrigin(served, port) : null) : undefined;
     // sites are routed at each World's own *.localhost origin, never behind the proxy
     const sitesOrigin = origins && !proxied ? (served) => (port ? localWorldOrigin(served, port) : null) : undefined;
-    const mountAt = (at) => mountWorld(loadWorldConfig(join(at, stateDirName(), 'world.json'), at).config.id, { root: at, branches: (served) => branches.doorsFor(served), ...(browserOrigin ? { browserOrigin } : {}), ...(sitesOrigin ? { sitesOrigin } : {}), ...(local ? { localTrust: true, ...(opts.localPerson ? { localPerson: opts.localPerson } : {}) } : {}) });
+    // the content plane beside each World's origin (`<world>--<org>--pages.localhost`): its twins' pages, apart from its doors
+    const pagesOrigin = origins && !proxied ? (served) => (port ? pagesOriginOf(served, 'http:', 'localhost', port) : null) : undefined;
+    const mountAt = (at) => mountWorld(loadWorldConfig(join(at, stateDirName(), 'world.json'), at).config.id, { root: at, branches: (served) => branches.doorsFor(served), ...(browserOrigin ? { browserOrigin } : {}), ...(sitesOrigin ? { sitesOrigin } : {}), ...(pagesOrigin ? { pagesOrigin } : {}), ...(local ? { localTrust: true, ...(opts.localPerson ? { localPerson: opts.localPerson } : {}) } : {}) });
     const branches = new LocalBranches({ dir: join(root, stateDirName(), 'branches'), origin: () => loopback, worlds, mount: mountAt, ...(opts.announce ? { announce: opts.announce } : {}) });
     // THE WORLD'S OWN BRANCHES, one served at a time: serving another stops this one's twins and starts that one's under the
     // same served name (its tokens and sessions are the World's, so the page stays open); `.volter/current` follows, as
@@ -92,7 +94,7 @@ export async function serveWorldView(name, opts = {}) {
             switching = false;
         }
     };
-    const mountOpts = { root, branches: (served) => branches.doorsFor(served), ...(browserOrigin ? { browserOrigin } : {}), ...(sitesOrigin ? { sitesOrigin } : {}), ...(local ? { localTrust: true, ...(opts.localPerson ? { localPerson: opts.localPerson } : {}) } : {}), serveBranch };
+    const mountOpts = { root, branches: (served) => branches.doorsFor(served), ...(browserOrigin ? { browserOrigin } : {}), ...(sitesOrigin ? { sitesOrigin } : {}), ...(pagesOrigin ? { pagesOrigin } : {}), ...(local ? { localTrust: true, ...(opts.localPerson ? { localPerson: opts.localPerson } : {}) } : {}), serveBranch };
     let world = await mountWorld(name, mountOpts);
     base = world.served;
     worlds.set(world.served, world);
@@ -116,6 +118,10 @@ export async function serveWorldView(name, opts = {}) {
             const site = origins && !proxied ? siteOfHost(at.hostname, worlds.keys()) : undefined;
             if (site)
                 return worlds.get(site.world).site(request, site.site);
+            // a World's content plane serves that World's twins' pages and nothing else of this view's (no console)
+            const pagesFor = origins && !proxied ? pagesOfHost(at.hostname, worlds.keys()) : undefined;
+            if (pagesFor)
+                return path === '/-/ping' ? Response.json({ ok: true, worlds: [pagesFor] }) : worlds.get(pagesFor).handle(request);
             const own = origins ? (proxied && at.host === proxied.host ? base : worldOfHost(at.hostname, worlds.keys())) : undefined;
             if (own === null)
                 return Response.json({ error: `no world at ${at.host}` }, { status: 404 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-runtime",
-  "version": "3.0.13",
+  "version": "3.0.14",
   "description": "World configs for twins: boot named local runtimes, allocate ports, generate world.env/instance.json, and run apps against fake-key twin worlds.",
   "keywords": [
     "twin",
@@ -68,14 +68,14 @@
     "node": ">=22.3"
   },
   "peerDependencies": {
-    "@volter/world-core": "3.0.13",
-    "@volter/world-console": "3.0.8"
+    "@volter/world-core": "3.0.14",
+    "@volter/world-console": "3.0.9"
   },
   "dependencies": {
     "@electric-sql/pglite": "0.5.8",
     "@electric-sql/pglite-pgvector": "0.0.9",
     "@volter/world-access": "3.0.1",
-    "@volter/world-core": "3.0.13",
+    "@volter/world-core": "3.0.14",
     "pg-gateway": "0.3.0-beta.4",
     "smol-toml": "^1.8.0",
     "yaml": "2.9.0"

package/src/index.ts

@@ -168,7 +168,7 @@ export { landReceipts, mountWorld, READ_ONLY_HEADER, worldOriginLabel, readServe
 export type { BranchDoors, BranchRow, DoorHost, MountedWorld, ServeRecord, WorldLayout } from './served-world.ts';
 export { followParentPins, LocalBranches } from './local-branches.ts';
 export { serveWorldView, VIEW_CONSOLE_BASE } from './world-view.ts';
-export { LOCAL_ORIGIN_BASE, localWorldOrigin, pathOfWorld, siteOfHost, worldDoorUnderConsole, worldOfHost } from './world-origins.ts';
+export { LOCAL_ORIGIN_BASE, localWorldOrigin, pagesOfHost, pagesOriginOf, pathOfWorld, siteOfHost, worldDoorUnderConsole, worldOfHost } from './world-origins.ts';
 export type { ViewConsole, WorldView } from './world-view.ts';
 export type { LocalBranchesOptions } from './local-branches.ts';
 export type { ServedWorld } from './served-world.ts';

package/src/init.ts

@@ -1272,6 +1272,7 @@ credentials/
 token
 token.read
 sessions.json
+pages-sessions.json
 keys.json
 `;
 

package/src/local-branches.ts

@@ -93,13 +93,10 @@ export class LocalBranches {
       list: async () => this.list(parent),
       create: (at, ttl, _origin, parentKey, byKey) => this.create(parent, at, ttl, parentKey, byKey),
       remove: async (name) => { const w = this.o.worlds.get(name); if (!w || this.record(w)?.from !== parent) return false; await this.remove(name); return true; },
-      // a branch of this parent only, served in this process beside it
-      show: async (name, request, vendor, rest, prefix) => {
+      // a branch of this parent only, served in this process beside it: its own content plane's pass
+      pagesPass: async (name, scope, land, grant) => {
         const w = this.o.worlds.get(name);
-        const r = w ? this.record(w) : null;
-        if (!w || r?.from !== parent) return Response.json({ error: `no branch ${name} of ${parent}` }, { status: 404 });
-        if (!r.at?.instant || r.at.label || r.at.live) return Response.json({ error: `${name} is not a copy as of an instant: its pages are shown at its own address` }, { status: 403 });
-        return await w.shown(request, vendor, rest, prefix);
+        return w && this.record(w)?.from === parent ? w.pagesPass(scope, land, grant) : null;
       },
     };
   }
@@ -161,7 +158,7 @@ export class LocalBranches {
       if (clock) { const file = clockFile(root, id); mkdirSync(dirname(file), { recursive: true }); writeFileSync(file, `${clock}\n`); }
       const createdAt = new Date().toISOString();
       const expiresAt = ttlSeconds === null ? null : new Date(Date.now() + ttlSeconds * 1000).toISOString();
-      // what it was made as (a pull request's preview is labelled and may be live): what may be shown of it rests on that
+      // what it was made as (a pull request's preview is labelled and may be live)
       const made = { ...(at.instant ? { instant: at.instant } : {}), ...(at.label ? { label: at.label } : {}), ...(at.live ? { live: true } : {}) };
       writeFileSync(join(root, stateDirName(), RECORD), `${JSON.stringify({ from: parent, at: Object.keys(made).length ? made : null, createdAt, expiresAt } satisfies BranchRecord, null, 2)}\n`);
       this.o.announce?.(`branch   ${name}  of ${parent}${at.instant ? ` as of ${at.instant}` : ''}${expiresAt ? `, until ${expiresAt}` : ''}`);

package/src/served-world.ts

@@ -159,11 +159,17 @@ function configRefFor(worldRoot: string, name: string): string {
 /** A world mounted by a host. `token`/`readToken` read the CURRENT tokens (rotate changes them);
  *  `twins()` names the world's twins once booted; `rotate()` mints both tokens anew — the old die
  *  with the call — and keeps them beside the world like `boot` does. */
-export type MountedWorld = { name: string; served: string; root: string; readonly token: string; readonly readToken: string; twins: () => string[]; rotate: () => { token: string; readToken: string }; handle: (request: Request) => Promise<Response>; /** a hostname this World's twins answer, as a browser reads it (siteOfHost) */ site: (request: Request, host: string) => Promise<Response>; /** WorldDoors.shown */ shown: (request: Request, vendor: string, rest: string, prefix: string) => Promise<Response>; boot: (url: string) => Promise<void>; stop: () => Promise<void> };
+export type MountedWorld = { name: string; served: string; root: string; readonly token: string; readonly readToken: string; twins: () => string[]; rotate: () => { token: string; readToken: string }; handle: (request: Request) => Promise<Response>; /** a hostname this World's twins answer, as a browser reads it (siteOfHost) */ site: (request: Request, host: string) => Promise<Response>; /** WorldDoors.pagesPass */ pagesPass: (scope: 'read' | 'write', land: string, grant?: { who?: string; framer?: string; asker?: string }) => string | null; boot: (url: string) => Promise<void>; stop: () => Promise<void> };
 /** A browser session a World keeps: its scope, when it ends, and the person a pass named, when one did. */
+/** What a content-plane pass, and the session it opens, carry: its scope; the control session that asked (the content
+ *  session ends with it; none when the World's token asked); the person; the console that frames it; and whether it
+ *  is this machine's own page (attributed to the machine). */
+type PagesGrant = { scope: 'read' | 'write'; session?: string; who?: string; framer?: string; local?: true; /** a parent World's session that asked
+ *  for a branch's page, as an opaque mark: the branch keeps one content session per asker and caps passes by it, but
+ *  cannot tell when it ends, so such a session lasts an hour */ asker?: string };
 type HeldSession = { scope: 'read' | 'write'; until: number; /** opened by this machine's own page (localSession) */ local?: true; who?: string; /** the platform whose pass opened it */ issuer?: string; /** the person's subject there */ sub?: string; /** the read key a shared link opened it with: it lasts only while that key does */ key?: string };
 
-export async function mountWorld(name: string, opts: { /** the platforms whose passes open this World */ passIssuers?: TrustedIssuer[]; root?: string; /** the host's branches of this World, by its served name */ branches?: (served: string) => BranchDoors | undefined; /** the origin a browser reaches this World at, when the host gives each World one */ browserOrigin?: (served: string) => string | null; /** DoorHost.sitesOrigin */ sitesOrigin?: (served: string) => string | null; /** served on this machine's loopback: its own pages need no token (DoorHost.localTrust) */ localTrust?: boolean; /** the person signed in on this machine: its own page acts as them (DoorHost.localPerson) */ localPerson?: string; /** DoorHost.serveBranch */ serveBranch?: (branch: string) => Promise<void> } = {}): Promise<MountedWorld> {
+export async function mountWorld(name: string, opts: { /** the platforms whose passes open this World */ passIssuers?: TrustedIssuer[]; root?: string; /** the host's branches of this World, by its served name */ branches?: (served: string) => BranchDoors | undefined; /** the origin a browser reaches this World at, when the host gives each World one */ browserOrigin?: (served: string) => string | null; /** DoorHost.sitesOrigin */ sitesOrigin?: (served: string) => string | null; /** DoorHost.pagesOrigin */ pagesOrigin?: (served: string) => string | null; /** served on this machine's loopback: its own pages need no token (DoorHost.localTrust) */ localTrust?: boolean; /** the person signed in on this machine: its own page acts as them (DoorHost.localPerson) */ localPerson?: string; /** DoorHost.serveBranch */ serveBranch?: (branch: string) => Promise<void> } = {}): Promise<MountedWorld> {
   const worldRoot = resolve(opts.root ?? process.cwd());
   const configRef = configRefFor(worldRoot, name);
   if (loadWorldConfig(configRef, worldRoot).config.resources) {
@@ -192,6 +198,7 @@ export async function mountWorld(name: string, opts: { /** the platforms whose p
     ...(opts.branches?.(served) ? { branches: opts.branches(served)! } : {}),
     ...(opts.browserOrigin ? { browserOrigin: () => opts.browserOrigin!(served), originOf: (other: string) => opts.browserOrigin!(other) } : {}),
     ...(opts.sitesOrigin ? { sitesOrigin: () => opts.sitesOrigin!(served) } : {}),
+    ...(opts.pagesOrigin ? { pagesOrigin: () => opts.pagesOrigin!(served) } : {}),
     ...(opts.localTrust ? { localTrust: () => true, ...(opts.localPerson ? { localPerson: () => opts.localPerson } : {}) } : {}),
     ...(opts.serveBranch ? { serveBranch: opts.serveBranch } : {}),
     ...(opts.passIssuers?.length ? { passIssuers: () => opts.passIssuers! } : {}),
@@ -215,7 +222,7 @@ export async function mountWorld(name: string, opts: { /** the platforms whose p
     rotate: () => { world.retoken(mintToken('tok_'), mintToken('tok_r_')); keep(); return { token: world.token, readToken: world.readToken }; },
     handle: (request) => world.handle(request),
     site: (request, host) => world.site(request, host),
-    shown: (request, vendor, rest, prefix) => world.shown(request, vendor, rest, prefix),
+    pagesPass: (scope, land, grant) => world.pagesPass(scope, land, grant),
     async boot(url) {
       keep();
       const port = Number(new URL(url).port) || 0;
@@ -344,6 +351,10 @@ export type DoorHost = {
    *  host gives each World one: its session lives only there (docs/contributing/architecture.md,
    *  "Viewing a World"). Null, or absent, on a host whose Worlds share one origin. */
   browserOrigin?: () => string | null;
+  /** THE CONTENT PLANE: the origin this World's twins' pages are shown at for a browser (`<world>--<org>--pages`), apart
+   *  from the origin of its doors and its session (docs/contributing/architecture.md, "Viewing a World"): a twin's page
+   *  runs there with a session that uses the twins and opens no door. Null, or absent, where Worlds share one origin. */
+  pagesOrigin?: () => string | null;
   /** The origin under which this host routes the hostnames the World's twins answer, each at `<hostname>.<origin's host>`
    *  (siteOfHost); none where it routes no sites (behind a proxy, on a hosted World). */
   sitesOrigin?: () => string | null;
@@ -377,9 +388,9 @@ export type BranchDoors = {
   create: (at: { instant?: string; live?: boolean; label?: string }, ttlSeconds: number | null, origin: string, parentKey?: string, /** the name of the key that made it: whoever holds a key gets a key of the branch (named for it),
    *  never the branch's own token, so the branch's doors refuse it what a key is refused */ byKey?: string) => Promise<{ name: string; token: string; readToken: string; expiresAt: string | null }>;
   remove: (name: string) => Promise<boolean>;
-  /** a page of a branch, read as its parent shows it (a vendor's screen at `prefix`, the parent's own path for it): where
-   *  the host holds the branch beside its parent; absent, a branch's pages are seen only at the branch's own address */
-  show?: (name: string, request: Request, vendor: string, rest: string, prefix: string) => Promise<Response>;
+  /** the address that opens a branch's content plane with a one-time pass at `scope`, landing on `land` (a path of the
+   *  branch): how its parent's console frames the branch's pages beside its own (the comparison) */
+  pagesPass?: (name: string, scope: 'read' | 'write', land: string, grant?: { who?: string; framer?: string; asker?: string }) => Promise<string | null>;
 };
 
 /** A World's browser-origin label, `<world>--<org>`, or null when its names cannot make one (a DNS
@@ -420,7 +431,133 @@ export class WorldDoors {
   constructor(readonly name: string, readonly worldRoot: string, readonly configRef: string, readonly served: string, private readonly host: DoorHost, token: string, readToken: string) { this.token = token; this.readToken = readToken; }
   /** New tokens; a request presenting the old ones is refused from the next call on. */
   // new tokens end everything the old ones reached: every session and every named key
-  retoken(token: string, readToken: string): void { this.token = token; this.readToken = readToken; this.endSessions(); this.keepKeys([]); }
+  retoken(token: string, readToken: string): void { this.token = token; this.readToken = readToken; this.endSessions(); this.keepKeys([]); this.keepPagesSessions({}); this.pagePasses.clear(); }
+
+  /** THE CONTENT PLANE (DoorHost.pagesOrigin): a browser sees this World's twins' pages at an origin apart from its doors
+   *  and its session, so a twin's page (another app's content, a pack's markup) runs with nothing that opens a door. A
+   *  page there holds a session of its own, opened from a one-time pass the World's own origin gives its session or
+   *  token: it uses the twins at its scope and nothing else. One per session that gave it a pass (every frame of a board
+   *  shares it), kept in the World's store, ended with that session; framed only by the console that asked. */
+  private onPages(url: URL): boolean { const at = this.host.pagesOrigin?.() ?? null; return at !== null && url.host === new URL(at).host; }
+  private readonly pagePasses = new Map<string, PagesGrant & { until: number }>();
+  private pagesPath(): string { return join(this.worldRoot, stateDirName(), 'pages-sessions.json'); }
+  private pagesHeld: Record<string, PagesGrant & { until: number }> | null = null;
+  private pagesSessions(): Record<string, PagesGrant & { until: number }> {
+    if (this.pagesHeld === null) { try { this.pagesHeld = JSON.parse(getActiveWorldStore().read(this.pagesPath()) ?? '{}') as Record<string, PagesGrant & { until: number }>; } catch { this.pagesHeld = {}; } }
+    return this.pagesHeld;
+  }
+  private keepPagesSessions(all: Record<string, PagesGrant & { until: number }>): void {
+    const now = Date.now();
+    this.pagesHeld = Object.fromEntries(Object.entries(all).filter(([, x]) => x.until > now).sort(([, a], [, b]) => b.until - a.until).slice(0, 2000));
+    getActiveWorldStore().write(this.pagesPath(), `${JSON.stringify(this.pagesHeld)}\n`, { secret: true });
+    // never committed, as a World's other sessions are not: a `.volter/.gitignore` written before this file existed names it
+    if (!this.pagesIgnored) {
+      this.pagesIgnored = true;
+      const ignore = join(this.worldRoot, stateDirName(), '.gitignore');
+      const held = getActiveWorldStore().read(ignore);
+      if (held !== null && !held.split('\n').includes('pages-sessions.json')) getActiveWorldStore().write(ignore, `${held.replace(/\n?$/, '\n')}pages-sessions.json\n`);
+    }
+  }
+  private pagesIgnored = false;
+  /** The origin of the World this one is a branch of, whose console frames its pages beside its own: none for a World
+   *  that is no branch (its record, written by the host that made it). */
+  private parentOrigin(): string | null {
+    try { const from = (JSON.parse(getActiveWorldStore().read(join(this.worldRoot, stateDirName(), 'branch.json')) ?? 'null') as { from?: string } | null)?.from; return from ? this.host.originOf?.(from) ?? null : null; } catch { return null; }
+  }
+  /** Whether what gave a content session its pass still stands: the control session that asked (ended, signed out, or
+   *  its shared link revoked, the content session ends with it), or this World's token (rotated, every one ends). */
+  private pagesParentLive(grant: PagesGrant): boolean { return grant.session === undefined || this.issued().session(grant.session) !== null; }
+  /** The address that opens this World's content plane for a minute's one-time pass and lands on `land` (a path of this
+   *  World); null where the World has no content plane, or the asker holds fifty passes not yet used. */
+  pagesPass(scope: 'read' | 'write', land: string, grant: Omit<PagesGrant, 'scope'> = {}): string | null {
+    const at = this.host.pagesOrigin?.() ?? null;
+    if (at === null) return null;
+    const now = Date.now();
+    for (const [k, v] of this.pagePasses) if (v.until <= now) this.pagePasses.delete(k);
+    const askerOf = (g: Omit<PagesGrant, 'scope'>): string => g.session ?? g.asker ?? g.framer ?? 'token';
+    const asker = askerOf(grant);
+    if ([...this.pagePasses.values()].filter((v) => askerOf(v) === asker).length >= 50 || this.pagePasses.size >= 5000) return null;
+    const pass = mintToken('pass_');
+    this.pagePasses.set(pass, { ...grant, scope, until: now + 60_000 });
+    return `${at}/-/${this.served}/pages/open#${new URLSearchParams({ pass, land }).toString()}`;
+  }
+  private pagesCookie(url: URL): string { return url.protocol === 'https:' ? '__Host-volter_pages' : 'volter_pages'; }
+  private pageSession(request: Request, url: URL): ({ id: string } & PagesGrant) | null {
+    const id = new RegExp(`(?:^|;\\s*)${this.pagesCookie(url)}=([^;]+)`).exec(request.headers.get('cookie') ?? '')?.[1];
+    const held = id && Object.hasOwn(this.pagesSessions(), id) ? this.pagesSessions()[id]! : undefined;
+    if (!id || !held || held.until <= Date.now() || !this.pagesParentLive(held)) return null;
+    const { until: _until, ...grant } = held;
+    return { id, ...grant };
+  }
+  /** What the content plane answers: its opening page and session, and the twins' pages; no door of the World. */
+  private async pagesPlane(request: Request, url: URL): Promise<Response> {
+    const doors = `/-/${this.served}/pages/`;
+    const door = url.pathname.startsWith(doors) ? url.pathname.slice(doors.length) : null;
+    const own = this.host.browserOrigin?.() ?? null;
+    if (door === 'open' && request.method === 'GET') {
+      // framed by this World's console, or its parent's (a comparison frames its branch's pages); the pages it opens are
+      // framed only by the console that asked
+      const consoles = [own, this.parentOrigin()].filter((x): x is string => Boolean(x)).join(' ') || "'none'";
+      return new Response(`<!doctype html><meta charset="utf-8"><title>${this.served}</title><body data-world="${this.served}"><script src="${doors}open.js"></script></body>`,
+        { headers: { 'content-type': 'text/html; charset=utf-8', 'content-security-policy': `default-src 'none'; script-src 'self'; connect-src 'self'; base-uri 'none'; frame-ancestors ${consoles}`, 'cache-control': 'no-store', 'referrer-policy': 'no-referrer' } });
+    }
+    if (door === 'open.js' && request.method === 'GET') {
+      const script = `(() => {
+  const world = document.body.dataset.world;
+  const carried = new URLSearchParams(location.hash.slice(1));
+  history.replaceState(null, '', location.pathname);
+  const pass = carried.get('pass') || '';
+  const land = carried.get('land') || '';
+  // resolved as the browser will (encoded dots too), on this origin and under this World
+  let to = null;
+  try { const u = new URL(land, location.origin); if (land.startsWith('/') && !/[\\\\\\s]/.test(land) && u.origin === location.origin && u.pathname.startsWith('/' + world + '/')) to = u.pathname + u.search; } catch {}
+  if (!pass || !to) { document.body.textContent = 'Nothing to open.'; return; }
+  fetch('/-/' + world + '/pages/session', { method: 'POST', headers: { 'x-volter-pages-pass': pass } })
+    .then((r) => { if (r.ok) location.replace(to); else document.body.textContent = 'This World did not open.'; })
+    .catch(() => { document.body.textContent = 'This World did not answer.'; });
+})();
+`;
+      return new Response(script, { headers: { 'content-type': 'text/javascript; charset=utf-8', 'cache-control': 'no-store' } });
+    }
+    if (door === 'session' && request.method === 'POST') {
+      // only this plane's own opening page asks (a browser sets the header; a page elsewhere cannot)
+      if (request.headers.get('sec-fetch-site') !== 'same-origin') return Response.json({ error: 'the content plane opens its session from its own page' }, { status: 403 });
+      const pass = request.headers.get('x-volter-pages-pass') ?? '';
+      const given = this.pagePasses.get(pass);
+      this.pagePasses.delete(pass);
+      if (!given || given.until <= Date.now() || !this.pagesParentLive(given)) return Response.json({ error: 'that pass is used or expired: open the page again from the World' }, { status: 401 });
+      const { until: _until, ...grant } = given;
+      // one content session per asker at a scope and framer: a board's frames opening together share it
+      const same = (x: PagesGrant): boolean => x.scope === grant.scope && x.session === grant.session && x.asker === grant.asker && x.framer === grant.framer && x.who === grant.who;
+      const now = Date.now();
+      const found = Object.entries(this.pagesSessions()).find(([, x]) => x.until > now && same(x))?.[0];
+      const id = found ?? mintToken('pgs_');
+      // twelve hours from its last opening while the session that asked stands; an hour where that cannot be known
+      this.keepPagesSessions({ ...this.pagesSessions(), [id]: { ...grant, until: now + (grant.session !== undefined || grant.asker === undefined ? 12 : 1) * 3_600_000 } });
+      return Response.json({ world: this.served, scope: grant.scope }, { headers: { 'set-cookie': `${this.pagesCookie(url)}=${id}; Path=/; HttpOnly; Secure; SameSite=None; Partitioned` } });
+    }
+    if (url.pathname.startsWith(`/${this.served}/`) && !url.pathname.startsWith(`/${this.served}/.well-known/`)) {
+      const answer = await this.wire(request, url, url.pathname.slice(`/${this.served}/`.length));
+      if (answer.status === 101) return answer;
+      const out = new Headers(answer.headers);
+      // framed by the console whose session asked, and by the page itself
+      const framer = this.pageSession(request, url)?.framer ?? own;
+      out.append('content-security-policy', `frame-ancestors 'self'${framer ? ` ${framer}` : ''}`);
+      // a twin's own sign-in kept in the frame a console shows it in, which may be another site (each *.localhost is):
+      // its cookies are partitioned by that console, as this plane's own session is
+      const cookies = answer.headers.getSetCookie();
+      if (cookies.length) {
+        out.delete('set-cookie');
+        for (const c of cookies) out.append('set-cookie', `${c.replace(/;\s*(?:samesite=[^;]*|secure|partitioned)\s*(?=;|$)/gi, '')}; SameSite=None; Secure; Partitioned`);
+      }
+      return new Response(answer.body, { status: answer.status, statusText: answer.statusText, headers: out });
+    }
+    // a navigation elsewhere (a twin sending the person to its root, `/`) goes to the World's own origin, as it always did
+    if (own && request.method === 'GET' && ['document', 'iframe'].includes(request.headers.get('sec-fetch-dest') ?? '') && !url.pathname.startsWith('/-/')) {
+      return new Response(null, { status: 303, headers: { location: `${own}${url.pathname}${url.search}`, 'cache-control': 'no-store' } });
+    }
+    return Response.json({ error: `this origin shows ${this.served}'s pages only` }, { status: 404 });
+  }
 
   /** BROWSER SESSIONS: the session cookie carries an opaque id, never a token, so a leaked cookie is one session and
    *  not the World's write token; rotating the tokens ends every session. Kept in the World's store, so a restart
@@ -613,6 +750,9 @@ export class WorldDoors {
     };
   }
   private credential(request: Request): { scope: 'write' | 'read' | null; via: 'token' | 'key' | 'session' | null; token: string | null; /** the session's id, when the session opened it */ session?: string; /** who the session is */ who?: string } {
+    // on the content plane only its own session counts: a page there presents nothing that opens a door
+    const at = new URL(request.url);
+    if (this.onPages(at)) { const held = this.pageSession(request, at); return held ? { scope: held.scope, via: 'session', token: null, session: `pages:${held.id}`, ...(held.who ? { who: held.who } : {}) } : { scope: null, via: null, token: null }; }
     const presented = presentedSecrets(request.headers, { token: TOKEN_HEADER, twinsKey: TWINS_KEY_HEADER });
     const name = this.sessionCookieName(new URL(request.url));
     // the name is one of two fixed literals (sessionCookieName); the separator browsers use is "; "
@@ -658,7 +798,7 @@ export class WorldDoors {
     const cred = this.credential(request);
     if (cred.scope === null) return null;
     // this machine's own page with no one signed in here is this machine; another session with no name is just that
-    if (cred.via === 'session') return cred.who ? `person:${cred.who}` : cred.session && this.sessions()[cred.session]?.local ? 'machine' : 'person';
+    if (cred.via === 'session') return cred.who ? `person:${cred.who}` : cred.session && (cred.session.startsWith('pages:') ? this.pagesSessions()[cred.session.slice(6)]?.local : this.sessions()[cred.session]?.local) ? 'machine' : 'person';
     // a key acts as itself, for its person (docs/contributing/architecture.md, "Who acted is recorded")
     if (cred.via === 'key') { const held = this.keyOf(cred.token); const person = held ? this.keyName(held) : undefined; return held ? `key:${held.name}${person ? ` for:${person}` : ''}` : 'key'; }
     return cred.scope === 'read' ? 'token:read' : 'token';
@@ -739,25 +879,6 @@ export class WorldDoors {
     return out;
   }
 
-  /** A vendor's page of this World as another World shows it at `prefix` (a parent showing its branch, the comparison's
-   *  "before"): read with this World's read token (a twin that enforces the read scope refuses any write), its links
-   *  minted under `prefix`.
-   *  The host calls it for the parent, which has checked its own caller; nothing of this World's session is involved. */
-  async shown(request: Request, vendor: string, rest: string, prefix: string): Promise<Response> {
-    if (request.method !== 'GET' && request.method !== 'HEAD') return Response.json({ error: "a copy's pages are read: GET and HEAD" }, { status: 405 });
-    if (!this.host.ready()) return Response.json({ error: 'booting', world: this.served }, { status: 503, headers: { 'retry-after': '1' } });
-    // a twin's pages only: a link forwards to the vendor itself, never something shown on another World's origin
-    if (this.link(vendor) || !this.host.twinFetch(vendor)) return Response.json({ error: `no twin "${vendor}" in ${this.served}` }, { status: 404 });
-    const url = new URL(request.url);
-    // only what a browser's read of a page says, as a site's read (site()): never a caller's credential, cookie, or
-    // the signed-address headers a session may not name
-    const headers = new Headers();
-    for (const name of ['accept', 'accept-language', 'if-none-match', 'if-modified-since', 'range', 'user-agent', 'sec-fetch-dest']) { const v = request.headers.get(name); if (v !== null) headers.set(name, v); }
-    headers.set(TOKEN_HEADER, this.readToken);
-    const at = new URL(`${url.origin}/${this.served}/${vendor}/${rest}${url.search}`);
-    return await this.wire(new Request(at, { method: request.method, headers, redirect: 'manual' }), at, `${vendor}/${rest}`, prefix);
-  }
-
   /** A hostname one of this World's twins answers (its hostsClaimed door lists it), read as a browser reads it there:
    *  the request goes to that twin with the hostname as its original host, as the injector routes it inside the World.
    *  Reads only: the site is the twin's state as the World holds it, never a way to write it. */
@@ -792,6 +913,7 @@ export class WorldDoors {
       const url = new URL(request.url);
       const prefix = `/${this.served}/`;
       if (url.pathname === '/-/ping') return Response.json({ ok: true, world: this.served, worlds: [this.served] });
+      if (this.onPages(url)) return await this.pagesPlane(request, url);
       if (url.pathname.startsWith(`/-/${this.served}/`)) return await this.door(request, url, url.pathname.slice(`/-/${this.served}/`.length));
       // the attach manifest (@volter/world-core/attach, VOLTER_WORLD=<this World's URL>): every twin at its
       // place under this World, and the token the injector carries to them — the presented one
@@ -865,19 +987,36 @@ export class WorldDoors {
   }
 
   /** The vendor wire: `/<org>/<world>/<vendor>/<rest>` → the twin's own URL. */
-  private async wire(request: Request, url: URL, rest: string, /** the path its twin's pages are shown at, when not this World's own */ shownAt?: string): Promise<Response> {
+  private async wire(request: Request, url: URL, rest: string): Promise<Response> {
     const [vendor, ...tail] = rest.split('/');
     const { scope, via } = this.credential(request);
     const manifestAsk = request.method === 'GET' && tail.join('/').replace(/\/+$/, '') === 'twin';
+    const browserAt = this.host.browserOrigin?.() ?? null;
+    if (scope === null && this.onPages(url) && browserAt && request.method === 'GET' && ['document', 'iframe'].includes(request.headers.get('sec-fetch-dest') ?? '')) {
+      return new Response(null, { status: 303, headers: { location: `${browserAt}${url.pathname}${url.search}`, 'cache-control': 'no-store' } });
+    }
     if (scope === null && !manifestAsk) return Response.json({ error: 'token required' }, { status: 401 });
     const foreign = this.crossOriginSession(request, via);
     if (foreign) return foreign;
     const reads = request.method === 'GET' || request.method === 'HEAD';
+    // THE TWO PLANES: a browser's session never sees a twin's page on the World's own origin. Its navigation there goes to
+    // the content plane with a pass (a frame or a tab alike); anything else its pages would send is refused. A page on the
+    // content plane that has no session yet is sent back here to get one
+    const navigation = request.method === 'GET' && ['document', 'iframe'].includes(request.headers.get('sec-fetch-dest') ?? '');
+    const pagesAt = this.host.pagesOrigin?.() ?? null;
+    if (pagesAt !== null && !this.onPages(url) && via === 'session') {
+      const asked = this.credential(request);
+      const to = navigation ? this.pagesPass(scope!, `${url.pathname}${url.search}`, { ...(asked.session ? { session: asked.session } : {}), ...(asked.who ? { who: asked.who } : {}), ...(this.host.browserOrigin?.() ? { framer: this.host.browserOrigin!()! } : {}), ...(asked.session && this.sessions()[asked.session]?.local ? { local: true as const } : {}) }) : null;
+      if (to) return new Response(null, { status: 303, headers: { location: to, 'cache-control': 'no-store', 'referrer-policy': 'no-referrer' } });
+      return Response.json({ error: `${this.served}'s twins' pages are shown at ${pagesAt}` }, { status: 403 });
+    }
     // A LINK: a path of this World that forwards to the vendor itself with the credential sealed beside
     // the World (the World holds the key; its callers hold the World's token). Journaled as a twin's request is.
     // a person's browser opening a page at the twin's place (a navigation, or the frame the console shows it in)
     const page = request.method === 'GET' && ['document', 'iframe'].includes(request.headers.get('sec-fetch-dest') ?? '');
     const link = this.link(vendor!);
+    // a link spends the World's sealed vendor credential: never from the content plane, where any twin's markup runs
+    if (link && this.onPages(url)) return Response.json({ error: `${vendor} is linked to the vendor itself: it is used through the World's own origin` }, { status: 404 });
     if (link) {
       if (scope === 'read' && !reads) return Response.json({ error: 'the read token opens only reads' }, { status: 403 });
       return await this.forward(request, url, tail.join('/'), vendor!, link.origin);
@@ -902,10 +1041,10 @@ export class WorldDoors {
     // that would write for its caller is refused too); at any other, its GET passes as it always has
     if (enforced) headers.set(READ_ONLY_HEADER, '1');
     // the browser's World session is the World's credential, never the twin's (a tunnel would hand it on)
-    const cookies = (headers.get('cookie') ?? '').split(/;\s*/).filter((c) => c && !/^(?:__Host-)?volter_world=/.test(c));
+    const cookies = (headers.get('cookie') ?? '').split(/;\s*/).filter((c) => c && !/^(?:__Host-)?volter_(?:world|pages)=/.test(c));
     if (cookies.length) headers.set('cookie', cookies.join('; ')); else headers.delete('cookie');
     // the twin is mounted under this World's path: live URLs it mints must carry it (twinPublicBase)
-    headers.set(TWIN_PREFIX_HEADER, shownAt ?? `/${this.served}/${vendor}`);
+    headers.set(TWIN_PREFIX_HEADER, `/${this.served}/${vendor}`);
     headers.set('x-forwarded-host', url.host); headers.set('x-forwarded-proto', url.protocol.replace(':', ''));
     // where this World shows the hostnames its twins answer, for a page that links one (twinSiteUrl): under its own
     // origin on this machine (siteOfHost); a World without one shows none
@@ -931,9 +1070,9 @@ export class WorldDoors {
     // above): caches keep them apart
     out.append('vary', 'Sec-Fetch-Dest');
     const setCookies = answer.headers.getSetCookie();
-    if (setCookies.some((c) => /^\s*(?:__Host-)?volter_world=/i.test(c))) {
+    if (setCookies.some((c) => /^\s*(?:__Host-)?volter_(?:world|pages)=/i.test(c))) {
       out.delete('set-cookie');
-      for (const c of setCookies) if (!/^\s*(?:__Host-)?volter_world=/i.test(c)) out.append('set-cookie', c);
+      for (const c of setCookies) if (!/^\s*(?:__Host-)?volter_(?:world|pages)=/i.test(c)) out.append('set-cookie', c);
     }
     return new Response(answer.body, { status: answer.status, headers: out });
   }
@@ -1024,36 +1163,6 @@ export class WorldDoors {
     // ending a browser's session needs no token: it only clears the caller's own cookie, which never
     // reaches these /-/ paths, so a page holding just the session could not otherwise sign out
     const sessionPath = path.replace(/\/+$/, '');
-    // THE HAND-OFF: a page of no UI that opens this World's session from the token in its fragment, then goes to the page
-    // of this World it names (`land`): how a page elsewhere links to this World's own pages (the console's comparison
-    // opening a vendor's page in a copy of the World, read only). The token never reaches the server in a URL; its script
-    // is a file of this origin, so the page keeps a strict policy. It is never framed: a session opened in another
-    // site's frame is not this World's own page's
-    if (sessionPath === 'session/hand-off' && request.method === 'GET') {
-      return new Response(`<!doctype html><meta charset="utf-8"><title>${this.served}</title><body data-world="${this.served}"><script src="/-/${this.served}/session/hand-off.js"></script></body>`,
-        { headers: { 'content-type': 'text/html; charset=utf-8', 'content-security-policy': "default-src 'none'; script-src 'self'; connect-src 'self'; base-uri 'none'; frame-ancestors 'none'", 'cache-control': 'no-store', 'referrer-policy': 'no-referrer' } });
-    }
-    if (sessionPath === 'session/hand-off.js' && request.method === 'GET') {
-      const script = `(() => {
-  const world = document.body.dataset.world;
-  const carried = new URLSearchParams(location.hash.slice(1));
-  history.replaceState(null, '', location.pathname);
-  const token = carried.get('token') || '';
-  const land = carried.get('land') || '';
-  // resolved as the browser will (encoded dots too), on this origin and under this World
-  let to = null;
-  try { const u = new URL(land, location.origin); if (land.startsWith('/') && !/[\\\\\\s]/.test(land) && u.origin === location.origin && u.pathname.startsWith('/' + world + '/')) to = u.pathname + u.search; } catch {}
-  const open = () => fetch('/-/' + world + '/session', { method: 'POST', headers: { 'x-volter-token': token } });
-  if (!token || !to) { document.body.textContent = 'Nothing to open.'; return; }
-  // a session this browser already holds here is kept: a page elsewhere cannot replace, downgrade or fix it
-  fetch('/-/' + world + '/session')
-    .then((held) => (held.ok ? held : open()))
-    .then((r) => { if (r.ok) location.replace(to); else document.body.textContent = 'This World did not open.'; })
-    .catch(() => { document.body.textContent = 'This World did not answer.'; });
-})();
-`;
-      return new Response(script, { headers: { 'content-type': 'text/javascript; charset=utf-8', 'cache-control': 'no-store' } });
-    }
     // a person signing in from a page (the console's form, posted to this origin): the token in the
     // form body, the session set here, then on to a page of this World
     // a form or beacon from another site never opens or ends a session here (the console, on this host's
@@ -1113,29 +1222,6 @@ export class WorldDoors {
     if (kind === 'session' && !name && request.method === 'POST' && via === 'key' && scope !== 'read') return Response.json({ error: 'a key opens no browser session: open the World with its token, or from the platform' }, { status: 403 });
     if (kind === 'session' && !name && (request.method === 'POST' || request.method === 'DELETE')) return this.session(request, url, scope, via === 'key' ? this.presentedKey(request) : undefined);
     if (kind === 'keys') return this.keysDoor(request, name, scope, via, this.credential(request).session);
-    // A COPY'S PAGES SHOWN HERE: `copies/<branch>/<vendor>/…`, a vendor's page in a branch of this World, read on this
-    // World's origin under its caller's credential (the comparison frames its "before" beside "now" this way: the
-    // branch's own session opens only on the branch's own pages). Only a copy as of an instant, which only a writer of
-    // this World makes, so its pages run here with nothing a stranger wrote (a labelled or live branch, a pull request's
-    // preview written by the app it tests, is shown at its own address). Read only; no cookie the copy sets is kept
-    if (kind === 'copies' && name && verb) {
-      const show = this.host.branches?.show;
-      if (!show) return Response.json({ error: "this host shows a copy's pages only at the copy's own address" }, { status: 501 });
-      const [org] = this.served.split('/');
-      // the path after the vendor as it came, empty segments and a trailing slash kept (an object key may hold `//`)
-      const full = `${org}/${name}`;
-      // made by the World's token or a person's session: a key's copy is written by whoever holds the key, and its pages
-      // would run here under the viewer's session
-      const madeBy = this.keys().find((k) => k.branch === full && (!k.expiresAt || Date.parse(k.expiresAt) > Date.now()))?.createdBy?.via;
-      if (madeBy !== 'token' && madeBy !== 'session') return Response.json({ error: `${full} was not made by this World's token or a person here: its pages are shown at its own address` }, { status: 403 });
-      // the path after the vendor as it came (empty segments and a trailing slash kept: an object key may hold `//`)
-      const exact = /^copies\/[^/]+\/[^/]+(?:\/(.*))?$/.exec(path);
-      if (!exact) return Response.json({ error: 'copies/<branch>/<vendor>/<path>' }, { status: 404 });
-      const answer = await show(full, request, verb, exact[1] ?? '', `/-/${this.served}/copies/${name}/${verb}`);
-      if (answer.status < 200) return Response.json({ error: "a copy's pages are read, never upgraded" }, { status: 400 });
-      const out = new Headers(answer.headers); out.delete('set-cookie');
-      return new Response(answer.body, { status: answer.status, statusText: answer.statusText, headers: out });
-    }
     if (scope === 'read' && request.method !== 'GET') return Response.json({ error: 'the read token opens only reads' }, { status: 403 });
 
     if (kind === 'clock') return await this.clockDoor(request, name);
@@ -1588,6 +1674,20 @@ export class WorldDoors {
       try { named = listWorlds(this.worldRoot).map((w) => ({ name: w.name, running: w.running })); } catch { /* a World with no local branches */ }
       return Response.json({ world: this.served, branches: await branches.list(), checkedOut: this.name, named, canServe: this.host.serveBranch !== undefined });
     }
+    // A BRANCH'S PAGES (`GET branches/<org>/<branch>/pages?land=<path>`): a navigation to the branch's own content plane
+    // with a one-time read pass, for a person or the World's token: how the console frames a branch's page beside this
+    // World's (its comparison); the branch's pages never run on this World's origin
+    if (rest.length === 3 && rest[2] === 'pages' && request.method === 'GET') {
+      if (via !== 'session' && via !== 'token') return Response.json({ error: "a branch's pages open for a person or the World's token" }, { status: 403 });
+      const name = `${decodeURIComponent(rest[0]!)}/${decodeURIComponent(rest[1]!)}`;
+      if (!(await branches.list()).some((b) => b.name === name)) return Response.json({ error: `no branch ${name} of ${this.served}` }, { status: 404 });
+      const land = url.searchParams.get('land') ?? `/${name}/`;
+      const asked = this.credential(request);
+      const mark = asked.session ? createHash('sha256').update(`${this.served}\0${asked.session}`).digest('base64url').slice(0, 22) : 'token';
+      const to = branches.pagesPass ? await branches.pagesPass(name, 'read', land, { asker: mark, ...(asked.who ? { who: asked.who } : {}), ...(this.host.browserOrigin?.() ? { framer: this.host.browserOrigin!()! } : {}) }) : null;
+      if (!to) return Response.json({ error: `this host shows ${name}'s pages only at its own address` }, { status: 501 });
+      return new Response(null, { status: 303, headers: { location: to, 'cache-control': 'no-store', 'referrer-policy': 'no-referrer' } });
+    }
     // SERVE ANOTHER NAMED BRANCH here (`POST branches/<branch>/serve`): only who may write the World switches what it serves
     if (rest.length === 2 && rest[1] === 'serve' && request.method === 'POST') {
       if (!this.host.serveBranch) return Response.json({ error: `this host serves ${this.served} on one branch` }, { status: 404 });

package/src/world-origins.ts

@@ -13,6 +13,25 @@ export function localWorldOrigin(served: string, port: number, base = LOCAL_ORIG
   return label ? `http://${label}.${base}:${port}` : null;
 }
 
+/** THE CONTENT PLANE's label beside a World's own: `<world>--<org>--pages`, where a browser sees the World's twins'
+ *  pages apart from its doors and its session. A World of an org named `pages` (`<world>--pages`) is no content plane:
+ *  its label names no World once the suffix is taken off, so it falls through to the World it is. */
+export const PAGES_LABEL_SUFFIX = '--pages';
+/** The content plane's origin for `served` on a host whose World origins are `<label>.<base>`, or null when its names
+ *  make no label. */
+export function pagesOriginOf(served: string, protocol: string, base: string, port?: number | string): string | null {
+  const label = worldOriginLabel(served);
+  return label && label.length + PAGES_LABEL_SUFFIX.length <= 63 ? `${protocol}//${label}${PAGES_LABEL_SUFFIX}.${base}${port ? `:${port}` : ''}` : null;
+}
+/** Which World's content plane a request's host names, or undefined for any other host. */
+export function pagesOfHost(hostname: string, served: Iterable<string>, base = LOCAL_ORIGIN_BASE): string | undefined {
+  const suffix = `${PAGES_LABEL_SUFFIX}.${base}`;
+  if (!hostname.endsWith(suffix)) return undefined;
+  const label = hostname.slice(0, -suffix.length);
+  for (const name of served) if (worldOriginLabel(name) === label) return name;
+  return undefined;
+}
+
 /** Which World a request's host names: undefined for a host that is not a World's origin (the host's
  *  own, path-addressed), null for a World-origin-shaped host naming no World served here. */
 export function worldOfHost(hostname: string, served: Iterable<string>, base = LOCAL_ORIGIN_BASE): string | null | undefined {