@volter/world-runtime 3.0.12 → 3.0.14

package/dist/src/index.d.ts

@@ -44,9 +44,9 @@ export { deployWorld, refreshTwin, adaptersFor, credentialPath, rewrapTwinCreden
 export type { DeployTwinOutcome, MaterializedRoot } from './root.js';
 export { landReceipts, mountWorld, READ_ONLY_HEADER, worldOriginLabel, readServeRecord, refreshSchedule, servedName, serveWorld, sessionsFile, keysFile, TOKEN_HEADER, WorldDoors } from './served-world.js';
 export type { BranchDoors, BranchRow, DoorHost, MountedWorld, ServeRecord, WorldLayout } from './served-world.js';
-export { LocalBranches } from './local-branches.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

@@ -31,9 +31,9 @@ export { fetchFromOrigin, worldOrigin } from "./origin.js";
 export { branchWorld, checkoutWorld } from "./branch.js";
 export { deployWorld, refreshTwin, adaptersFor, credentialPath, rewrapTwinCredentials, credentialPayloadFrom, rootCredentialInput, bindLegacyCredentials, deployTwin, loadWorldChecks, materializeRoots, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, userKekPath } from "./root.js";
 export { landReceipts, mountWorld, READ_ONLY_HEADER, worldOriginLabel, readServeRecord, refreshSchedule, servedName, serveWorld, sessionsFile, keysFile, TOKEN_HEADER, WorldDoors } from "./served-world.js";
-export { LocalBranches } from "./local-branches.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.d.ts

@@ -1,4 +1,15 @@
 import { type BranchDoors, type BranchRow, type MountedWorld } from './served-world.js';
+/** A branch mounted again beside its parent takes the parent's twin versions: it is the parent's config under another
+ *  name and runs on the packages the parent's root installs, so a parent moved to a new twin version (its pin and its
+ *  install, together) never leaves a branch pinning the old one and failing the next boot. */
+export declare function followParentPins(parentRoot: string, branchRoot: string): void;
+/** A write key of a branch, named for the key whose holder made it (the branch's own keys door): what that holder gets in
+ *  place of the branch's token, so the branch refuses it what a key is refused (seals, checks, keys, rules, sessions). */
+export declare function keyOfBranch(branch: {
+    served: string;
+    token: string;
+    handle: (request: Request) => Promise<Response>;
+}, origin: string, maker: string): Promise<string>;
 export type LocalBranchesOptions = {
     /** where branches live: `<dir>/<org>/<world>/` */
     dir: string;

package/dist/src/local-branches.js

@@ -19,6 +19,37 @@ function renamed(config, id, name) {
     }
     return { ...config, id, bare: { ...config.bare, name } };
 }
+/** A branch mounted again beside its parent takes the parent's twin versions: it is the parent's config under another
+ *  name and runs on the packages the parent's root installs, so a parent moved to a new twin version (its pin and its
+ *  install, together) never leaves a branch pinning the old one and failing the next boot. */
+export function followParentPins(parentRoot, branchRoot) {
+    const file = join(branchRoot, stateDirName(), 'world.json');
+    const pinOf = (s) => s.source?.version ?? s.version;
+    const parent = JSON.parse(readFileSync(join(parentRoot, stateDirName(), 'world.json'), 'utf8'));
+    const branch = JSON.parse(readFileSync(file, 'utf8'));
+    const pins = new Map((parent.services ?? []).flatMap((s) => { const pin = pinOf(s); return s.id && pin ? [[s.id, pin]] : []; }));
+    let moved = false;
+    for (const s of branch.services ?? []) {
+        const pin = s.id ? pins.get(s.id) : undefined;
+        if (!pin || pinOf(s) === pin)
+            continue;
+        if (s.source && typeof s.source === 'object')
+            s.source.version = pin;
+        else
+            s.version = pin;
+        moved = true;
+    }
+    if (moved)
+        writeFileSync(file, `${JSON.stringify(branch, null, 2)}\n`);
+}
+/** A write key of a branch, named for the key whose holder made it (the branch's own keys door): what that holder gets in
+ *  place of the branch's token, so the branch refuses it what a key is refused (seals, checks, keys, rules, sessions). */
+export async function keyOfBranch(branch, origin, maker) {
+    const made = await branch.handle(new Request(`${origin}/-/${branch.served}/keys`, { method: 'POST', headers: { [TOKEN_HEADER]: branch.token, 'content-type': 'application/json' }, body: JSON.stringify({ name: `${maker} (made this branch)`.slice(0, 100), scope: 'write' }) }));
+    if (!made.ok)
+        throw new Error(`a key of ${branch.served} for ${maker}: ${await made.text()}`);
+    return (await made.json()).key;
+}
 export class LocalBranches {
     o;
     sweeper = null;
@@ -50,15 +81,20 @@ export class LocalBranches {
     doorsFor(parent) {
         return {
             list: async () => this.list(parent),
-            create: (at, ttl, _origin, parentKey) => this.create(parent, at, ttl, parentKey),
+            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: its own content plane's pass
+            pagesPass: async (name, scope, land, grant) => {
+                const w = this.o.worlds.get(name);
+                return w && this.record(w)?.from === parent ? w.pagesPass(scope, land, grant) : null;
+            },
         };
     }
-    async create(parent, at, ttlSeconds, parentKey) {
+    async create(parent, at, ttlSeconds, parentKey, byKey) {
         this.making.set(parent, (this.making.get(parent) ?? 0) + 1);
         try {
-            return await this.make(parent, at, ttlSeconds, parentKey);
+            return await this.make(parent, at, ttlSeconds, parentKey, byKey);
         }
         finally {
             const left = (this.making.get(parent) ?? 1) - 1;
@@ -68,7 +104,7 @@ export class LocalBranches {
                 this.making.delete(parent);
         }
     }
-    async make(parent, at, ttlSeconds, parentKey) {
+    async make(parent, at, ttlSeconds, parentKey, byKey) {
         const from = this.o.worlds.get(parent);
         if (!from)
             throw new Error(`no world ${parent} here`);
@@ -129,9 +165,11 @@ export class LocalBranches {
             }
             const createdAt = new Date().toISOString();
             const expiresAt = ttlSeconds === null ? null : new Date(Date.now() + ttlSeconds * 1000).toISOString();
-            writeFileSync(join(root, stateDirName(), RECORD), `${JSON.stringify({ from: parent, at: at.instant ? { instant: at.instant } : null, createdAt, expiresAt }, null, 2)}\n`);
+            // 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}` : ''}`);
-            return { name, token: mounted.token, readToken: mounted.readToken, expiresAt };
+            return { name, token: byKey ? await keyOfBranch(mounted, origin, byKey) : mounted.token, readToken: mounted.readToken, expiresAt };
         }
         catch (error) {
             this.o.worlds.delete(name);

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

@@ -57,16 +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>;
+    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>;
@@ -121,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;
@@ -164,13 +188,21 @@ export type BranchDoors = {
         instant?: string;
         live?: boolean;
         label?: string;
-    }, ttlSeconds: number | null, origin: string, parentKey?: string) => Promise<{
+    }, 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>;
+    /** 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
@@ -191,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. */
@@ -426,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,6 +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),
+        pagesPass: (scope, land, grant) => world.pagesPass(scope, land, grant),
         async boot(url) {
             keep();
             const port = Number(new URL(url).port) || 0;
@@ -416,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. */
@@ -669,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 "; "
@@ -719,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);
@@ -864,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
@@ -950,17 +1107,36 @@ export class WorldDoors {
         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 });
@@ -997,7 +1173,7 @@ 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
@@ -1036,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 });
@@ -1150,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
@@ -1838,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)
@@ -1896,7 +2060,7 @@ export class WorldDoors {
             const expiresAt = ttl === null ? undefined : new Date(now + ttl * 1000).toISOString();
             this.keepKeys([...this.keys(), { id: keyId, name: 'a branch (being made)', scope: 'write', hash: keyHash(parentKey), createdAt: new Date(now).toISOString(), createdBy, ...(person ? { for: person } : {}), ...(expiresAt ? { expiresAt } : {}), ...(maker ? { madeWith: maker.id } : {}) }]);
             try {
-                const made = await branches.create(typeof instant === 'string' ? { instant: new Date(Date.parse(instant)).toISOString() } : { ...(body?.live === true ? { live: true } : {}), ...(typeof body?.label === 'string' ? { label: body.label } : {}) }, ttl, url.origin, parentKey);
+                const made = await branches.create(typeof instant === 'string' ? { instant: new Date(Date.parse(instant)).toISOString() } : { ...(body?.live === true ? { live: true } : {}), ...(typeof body?.label === 'string' ? { label: body.label } : {}) }, ttl, url.origin, parentKey, maker ? maker.name : undefined);
                 this.keepKeys(this.keys().map((k) => (k.id === keyId ? { ...k, name: `the branch ${made.name}`, branch: made.name, ...(made.expiresAt ? { expiresAt: made.expiresAt } : {}) } : k)));
                 // a browser's session is answered the branch's read token only: a page views a branch, and the parent's
                 // session removes it, so no write token ever reaches a page's script (or a frame beside it)

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;