@volter/world-runtime 3.0.13 → 3.0.15

package/dist/src/index.d.ts

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

package/dist/src/index.js

@@ -33,7 +33,7 @@ export { deployWorld, refreshTwin, adaptersFor, credentialPath, rewrapTwinCreden
 export { landReceipts, mountWorld, READ_ONLY_HEADER, worldOriginLabel, readServeRecord, refreshSchedule, servedName, serveWorld, sessionsFile, keysFile, TOKEN_HEADER, WorldDoors } from "./served-world.js";
 export { followParentPins, LocalBranches } from "./local-branches.js";
 export { serveWorldView, VIEW_CONSOLE_BASE } from "./world-view.js";
-export { LOCAL_ORIGIN_BASE, localWorldOrigin, pathOfWorld, siteOfHost, worldDoorUnderConsole, worldOfHost } from "./world-origins.js";
+export { LOCAL_ORIGIN_BASE, localWorldOrigin, pagesOfHost, pagesOriginOf, pathOfWorld, siteOfHost, worldDoorUnderConsole, worldOfHost } from "./world-origins.js";
 export { CONSOLE_BASE, consoleRedirect, serveConsoleApart, serveConsoleFor } from "./console-apart.js";
 export { assertWorldStateRemovable } from "./ancestry.js";
 export { withoutVaultSignIn } from "./runtime.js";

package/dist/src/init.d.ts

@@ -227,7 +227,7 @@ export declare function renderEnvFile(plan: InitPlan): string;
 /** Write the plan's two artifacts. Byte-identical for the same repo + catalog: sorted keys, no
  * timestamps, no absolute paths inside the files. */
 /** What `.volter/.gitignore` says: the story is committed, the running state never is. */
-export declare const STATE_GITIGNORE = "# Volter: the world's running state and live env \u2014 never committed. world.json, handlers/ and seeds/ are the story.\nworlds/\ncurrent\n*.env\ncredentials/\ntoken\ntoken.read\nsessions.json\nkeys.json\n";
+export declare const STATE_GITIGNORE = "# Volter: the world's running state and live env \u2014 never committed. world.json, handlers/ and seeds/ are the story.\nworlds/\ncurrent\n*.env\ncredentials/\ntoken\ntoken.read\nsessions.json\npages-sessions.json\nkeys.json\n";
 export declare function writeWorldInit(plan: InitPlan, options?: {
     force?: boolean;
 }): void;

package/dist/src/init.js

@@ -1087,6 +1087,7 @@ credentials/
 token
 token.read
 sessions.json
+pages-sessions.json
 keys.json
 `;
 export function writeWorldInit(plan, options = {}) {

package/dist/src/local-branches.js

@@ -84,15 +84,10 @@ export class LocalBranches {
             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;
             },
         };
     }
@@ -170,7 +165,7 @@ export class LocalBranches {
             }
             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 }, null, 2)}\n`);
             this.o.announce?.(`branch   ${name}  of ${parent}${at.instant ? ` as of ${at.instant}` : ''}${expiresAt ? `, until ${expiresAt}` : ''}`);

package/dist/src/served-world.d.ts

@@ -57,17 +57,36 @@ export type MountedWorld = {
         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>;
+    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;
+};
 export declare function mountWorld(name: string, opts?: {
     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) */
+    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>;
@@ -122,6 +141,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;
@@ -173,9 +196,13 @@ export type BranchDoors = {
         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
  *  label: lowercase letters, digits and single hyphens, 63 at most). A host maps a label back by the
@@ -196,6 +223,31 @@ export declare class WorldDoors {
     constructor(name: string, worldRoot: string, configRef: string, served: string, host: DoorHost, token: string, readToken: string);
     /** New tokens; a request presenting the old ones is refused from the next call on. */
     retoken(token: string, readToken: string): void;
+    /** 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;
+    private readonly pagePasses;
+    private pagesPath;
+    private pagesHeld;
+    private pagesSessions;
+    private keepPagesSessions;
+    private pagesIgnored;
+    /** 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;
+    /** 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;
+    /** 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;
+    private pagesCookie;
+    private pageSession;
+    /** What the content plane answers: its opening page and session, and the twins' pages; no door of the World. */
+    private pagesPlane;
     /** 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
      *  keeps them; each lasts 30 days from its opening. */
@@ -308,11 +360,6 @@ export declare class WorldDoors {
         vendor: string;
         hosts: string[];
     }>>;
-    /** 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. */
-    shown(request: Request, vendor: string, rest: string, prefix: string): Promise<Response>;
     /** 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. */
@@ -436,3 +483,4 @@ export declare function localWorld(target: string): {
     served: string;
     instance: WorldInstance;
 };
+export {};

package/dist/src/served-world.js

@@ -189,6 +189,7 @@ export async function mountWorld(name, opts = {}) {
         ...(opts.branches?.(served) ? { branches: opts.branches(served) } : {}),
         ...(opts.browserOrigin ? { browserOrigin: () => opts.browserOrigin(served), originOf: (other) => 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 } : {}),
@@ -213,7 +214,7 @@ export async function mountWorld(name, opts = {}) {
         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;
@@ -417,7 +418,154 @@ export class WorldDoors {
     }
     /** 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, readToken) { this.token = token; this.readToken = readToken; this.endSessions(); this.keepKeys([]); }
+    retoken(token, readToken) { 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. */
+    onPages(url) { const at = this.host.pagesOrigin?.() ?? null; return at !== null && url.host === new URL(at).host; }
+    pagePasses = new Map();
+    pagesPath() { return join(this.worldRoot, stateDirName(), 'pages-sessions.json'); }
+    pagesHeld = null;
+    pagesSessions() {
+        if (this.pagesHeld === null) {
+            try {
+                this.pagesHeld = JSON.parse(getActiveWorldStore().read(this.pagesPath()) ?? '{}');
+            }
+            catch {
+                this.pagesHeld = {};
+            }
+        }
+        return this.pagesHeld;
+    }
+    keepPagesSessions(all) {
+        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`);
+        }
+    }
+    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). */
+    parentOrigin() {
+        try {
+            const from = JSON.parse(getActiveWorldStore().read(join(this.worldRoot, stateDirName(), 'branch.json')) ?? '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). */
+    pagesParentLive(grant) { 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, land, grant = {}) {
+        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) => 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()}`;
+    }
+    pagesCookie(url) { return url.protocol === 'https:' ? '__Host-volter_pages' : 'volter_pages'; }
+    pageSession(request, url) {
+        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. */
+    async pagesPlane(request, url) {
+        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) => 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) => 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
      *  keeps them; each lasts 30 days from its opening. */
@@ -670,6 +818,12 @@ export class WorldDoors {
         };
     }
     credential(request) {
+        // 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 "; "
@@ -720,7 +874,7 @@ export class WorldDoors {
             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';
+            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);
@@ -817,31 +971,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, vendor, rest, prefix) {
-        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. */
@@ -890,6 +1019,8 @@ export class WorldDoors {
             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
@@ -972,21 +1103,40 @@ export class WorldDoors {
         return enforced;
     }
     /** The vendor wire: `/<org>/<world>/<vendor>/<rest>` → the twin's own URL. */
-    async wire(request, url, rest, /** the path its twin's pages are shown at, when not this World's own */ shownAt) {
+    async wire(request, url, rest) {
         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 } : {}) }) : 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 });
@@ -1023,13 +1173,13 @@ export class WorldDoors {
         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
@@ -1062,10 +1212,10 @@ 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))
+                if (!/^\s*(?:__Host-)?volter_(?:world|pages)=/i.test(c))
                     out.append('set-cookie', c);
         }
         return new Response(answer.body, { status: answer.status, headers: out });
@@ -1176,35 +1326,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
@@ -1282,34 +1403,6 @@ export class WorldDoors {
             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')
@@ -1892,6 +1985,23 @@ export class WorldDoors {
             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)

package/dist/src/world-origins.d.ts

@@ -2,6 +2,15 @@ export declare const LOCAL_ORIGIN_BASE = "localhost";
 /** The origin a browser reaches `served` at on a local host listening on `port`, or null when its
  *  names make no label. */
 export declare function localWorldOrigin(served: string, port: number, base?: string): string | 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 declare 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 declare function pagesOriginOf(served: string, protocol: string, base: string, port?: number | string): string | null;
+/** Which World's content plane a request's host names, or undefined for any other host. */
+export declare function pagesOfHost(hostname: string, served: Iterable<string>, base?: string): string | 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 declare function worldOfHost(hostname: string, served: Iterable<string>, base?: string): string | null | undefined;