@volter/world-runtime 3.0.17 → 3.0.19

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

@@ -75,17 +75,19 @@ type PagesGrant = {
     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 */
+    local?: true; /** the hosted site it
+     *  opens (a hostname this World's twins answer), not the content plane */
+    site?: string; /** 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; /** DoorHost.pagesOrigin */
+    browserOrigin?: (served: string) => string | null; /** DoorHost.sitesTemplate */
+    sitesTemplate?: (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 */
@@ -145,9 +147,12 @@ export type DoorHost = {
      *  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;
+    /** Where this host shows the hostnames the World's twins answer: a sites template (world-core siteUrlOf), `{host}`
+     *  nested under the World's origin on this machine (siteOfHost), `{site}` as one label beside it on a hosted World
+     *  (each such site private to the World's people); none where it routes no sites (behind a proxy). */
+    sitesTemplate?: () => string | null;
+    /** Another World's (a branch of this one) sites template, where this host routes its sites. */
+    sitesTemplateOf?: (served: string) => string | null;
     /** The origin another World this host serves (a branch of this one) is reached at, where it has one of its own. */
     originOf?: (served: string) => string | null;
     /** This World is served on this machine's loopback, for the person at it: a page of this World, reached by a
@@ -244,8 +249,18 @@ export declare class WorldDoors {
     /** 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;
+    /** A one-time pass (a minute long) for the content plane or a hosted site; null when its asker holds fifty unused. */
+    private mintPagesPass;
+    /** The hostname a hosted site address names (`{site}` template: `<label>--<world>--<org>.<suffix>`) among those this
+     *  World's twins claim; null for any other address. */
+    /** Whether an address has a hosted site's shape here (`<label>--<world>--<org>.<suffix>`), claimed or not. */
+    private siteShaped;
+    private hostedSiteOf;
     private pagesCookie;
     private pageSession;
+    /** A twin's cookies, kept to the origin answering (the content plane, a hosted site): partitioned as its frames need,
+     *  never set for a parent domain every World shares, and never the World's own session cookies. */
+    private keepCookiesHere;
     /** 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
@@ -360,6 +375,17 @@ export declare class WorldDoors {
         vendor: string;
         hosts: string[];
     }>>;
+    /** What a twin asks an application (`ctx.ask`) that this World can answer truthfully, where no process routes it (a
+     *  hosted World's isolate): a GET or HEAD of a URL whose hostname one of this World's twins answers (its hostsClaimed
+     *  door: a Cloudflare twin's Worker route or custom domain) is that twin's answer, read as a browser reads the site
+     *  here (`site`). Any other question (another method, a hostname no twin claims) is undefined: it goes on as it would
+     *  without this router (the application route, the World's egress rule, the network), never a World-made answer
+     *  dressed as the application's (architecture, "What an author writes, and how"). Given to each twin's fetch as its
+     *  `application` by apps/cloud. */
+    askInWorld(target: string, init: RequestInit): Promise<{
+        status: number;
+        body: string;
+    } | undefined>;
     /** 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. */

package/dist/src/served-world.js

@@ -26,7 +26,7 @@ import { getActiveWorldStore, withHistoryLocks, captureHistory, historyAtInstant
 // to `.volter/token` and `.volter/token.read` (0600).
 // One writer per world by construction: the doors run in this process, serialized per twin.
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
-import { CALLER_HEADER, callerForHeader, newTraceparent, parseTraceparent, traceparentForDelivery, readTwinRequestJournalFrom, assertSafeChangesetName, blobDigest, destinationOf, getActiveBlobStore, journalTwinRequest, loadCheck, twinRequestJournalFailures, openSealedAt, readTwinRequestJournal, serveHttp, twinRequestCredentials, TWIN_PREFIX_HEADER, TWIN_SITES_HEADER, ORIGINAL_PATH_HEADER, validateRemoteOrigin } from '@volter/world-core/runtime';
+import { CALLER_HEADER, callerForHeader, newTraceparent, parseTraceparent, traceparentForDelivery, readTwinRequestJournalFrom, assertSafeChangesetName, blobDigest, destinationOf, getActiveBlobStore, journalTwinRequest, loadCheck, twinRequestJournalFailures, openSealedAt, readTwinRequestJournal, serveHttp, twinRequestCredentials, TWIN_PREFIX_HEADER, TWIN_SITES_HEADER, siteLabel, siteUrlOf, ORIGINAL_PATH_HEADER, validateRemoteOrigin } from '@volter/world-core/runtime';
 import { APP_READ_ENDPOINT_ENV } from "./init.js";
 import { packFacts } from "./pack-facts.js";
 import { grantOf, presentedSecrets, sameSecret, spentPasses, verifyPass } from '@volter/world-access';
@@ -188,7 +188,7 @@ export async function mountWorld(name, opts = {}) {
         clockPath: () => clockFile(worldRoot, name),
         ...(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.sitesTemplate ? { sitesTemplate: () => opts.sitesTemplate(served), sitesTemplateOf: (other) => opts.sitesTemplate(other) } : {}),
         ...(opts.pagesOrigin ? { pagesOrigin: () => opts.pagesOrigin(served) } : {}),
         ...(opts.localTrust ? { localTrust: () => true, ...(opts.localPerson ? { localPerson: () => opts.localPerson } : {}) } : {}),
         ...(opts.serveBranch ? { serveBranch: opts.serveBranch } : {}),
@@ -473,6 +473,11 @@ export class WorldDoors {
         const at = this.host.pagesOrigin?.() ?? null;
         if (at === null)
             return null;
+        const pass = this.mintPagesPass(scope, grant);
+        return pass ? `${at}/-/${this.served}/pages/open#${new URLSearchParams({ pass, land }).toString()}` : null;
+    }
+    /** A one-time pass (a minute long) for the content plane or a hosted site; null when its asker holds fifty unused. */
+    mintPagesPass(scope, grant) {
         const now = Date.now();
         for (const [k, v] of this.pagePasses)
             if (v.until <= now)
@@ -483,19 +488,61 @@ export class WorldDoors {
             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()}`;
+        return pass;
+    }
+    /** The hostname a hosted site address names (`{site}` template: `<label>--<world>--<org>.<suffix>`) among those this
+     *  World's twins claim; null for any other address. */
+    /** Whether an address has a hosted site's shape here (`<label>--<world>--<org>.<suffix>`), claimed or not. */
+    siteShaped(url) {
+        const template = this.host.sitesTemplate?.() ?? null;
+        if (!template || !template.includes('{site}'))
+            return false;
+        const after = new URL(template.replace('{site}', 'x')).host.slice(1);
+        return url.host.endsWith(after) && url.host.length > after.length;
+    }
+    async hostedSiteOf(url) {
+        if (!this.siteShaped(url))
+            return null;
+        const template = this.host.sitesTemplate?.() ?? null;
+        if (!template || !template.includes('{site}'))
+            return null;
+        const after = new URL(template.replace('{site}', 'x')).host.slice(1);
+        if (!url.host.endsWith(after) || url.host.length <= after.length)
+            return null;
+        const label = url.host.slice(0, -after.length);
+        for (const { hosts } of await this.claimedHosts(url.origin))
+            for (const h of hosts)
+                if (siteLabel(h) === label)
+                    return h.toLowerCase();
+        return null;
     }
     pagesCookie(url) { return url.protocol === 'https:' ? '__Host-volter_pages' : 'volter_pages'; }
-    pageSession(request, url) {
+    pageSession(request, url, site) {
         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;
+        // a session opens only where its pass was for: the content plane, or that one hosted site
+        if ((held.site ?? null) !== (site ?? null))
+            return null;
         const { until: _until, ...grant } = held;
         return { id, ...grant };
     }
+    /** A twin's cookies, kept to the origin answering (the content plane, a hosted site): partitioned as its frames need,
+     *  never set for a parent domain every World shares, and never the World's own session cookies. */
+    keepCookiesHere(answer, out) {
+        const cookies = answer.headers.getSetCookie();
+        if (!cookies.length)
+            return;
+        out.delete('set-cookie');
+        for (const c of cookies) {
+            if (/^\s*(?:__Host-)?volter_(?:world|pages)=/i.test(c))
+                continue;
+            out.append('set-cookie', `${c.replace(/;\s*(?:samesite=[^;]*|secure|partitioned|domain=[^;]*)\s*(?=;|$)/gi, '')}; SameSite=None; Secure; Partitioned`);
+        }
+    }
     /** What the content plane answers: its opening page and session, and the twins' pages; no door of the World. */
-    async pagesPlane(request, url) {
+    async pagesPlane(request, url, /** a hosted site served here, not the content plane */ site) {
         const doors = `/-/${this.served}/pages/`;
         const door = url.pathname.startsWith(doors) ? url.pathname.slice(doors.length) : null;
         const own = this.host.browserOrigin?.() ?? null;
@@ -503,7 +550,7 @@ export class WorldDoors {
             // 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' } });
+            return new Response(`<!doctype html><meta charset="utf-8"><title>${this.served}</title><body data-world="${this.served}"${site ? ' data-site="1"' : ''}><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 = `(() => {
@@ -514,7 +561,9 @@ export class WorldDoors {
   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 {}
+  // a hosted site lands anywhere on it; the content plane only under this World
+  const anywhere = document.body.dataset.site === '1';
+  try { const u = new URL(land, location.origin); if (land.startsWith('/') && !/[\\\\\\s]/.test(land) && u.origin === location.origin && (anywhere || 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.'; })
@@ -530,11 +579,11 @@ export class WorldDoors {
             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))
+            if (!given || given.until <= Date.now() || !this.pagesParentLive(given) || (given.site ?? null) !== (site ?? null))
                 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 same = (x) => x.scope === grant.scope && x.session === grant.session && x.asker === grant.asker && x.framer === grant.framer && x.who === grant.who && x.site === grant.site;
             const now = Date.now();
             const found = Object.entries(this.pagesSessions()).find(([, x]) => x.until > now && same(x))?.[0];
             const id = found ?? mintToken('pgs_');
@@ -542,6 +591,29 @@ export class WorldDoors {
             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` } });
         }
+        // A HOSTED SITE: read with a session its World's own origin gave it a pass for (sites/go), never without
+        if (site) {
+            const held = this.pageSession(request, url, site);
+            const back = own ? `${own}/-/${this.served}/sites/go?${new URLSearchParams({ host: site, land: `${url.pathname}${url.search}` }).toString()}` : null;
+            if (!held) {
+                if (request.method === 'GET' && (request.headers.get('accept') ?? '').includes('text/html') && back) {
+                    const shown = site.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+                    return new Response(`<!doctype html><meta charset="utf-8"><title>${shown}</title><body style="font:16px system-ui;margin:3em;color:#555"><p><b>${shown}</b> is a site in the World ${this.served}, shown to its people.</p><p><a href="${back.replace(/&/g, '&amp;')}">Open it from the World</a></p></body>`, { status: 401, headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', 'referrer-policy': 'no-referrer' } });
+                }
+                return Response.json({ error: `${site} is shown to ${this.served}'s people: open it from the World` }, { status: 401 });
+            }
+            // read by the site's own pages, or a person's navigation to it: never by another page of the same domain (the
+            // session's partition is the domain's, which every World's pages share)
+            const fetchSite = request.headers.get('sec-fetch-site');
+            const navigation = ['document', 'iframe'].includes(request.headers.get('sec-fetch-dest') ?? '');
+            if (fetchSite !== 'same-origin' && !(navigation && ['none', 'same-site'].includes(fetchSite ?? '')))
+                return Response.json({ error: `${site} is read by its own pages` }, { status: 403 });
+            const answer = await this.site(request, site);
+            const out = new Headers(answer.headers);
+            out.append('content-security-policy', `frame-ancestors 'self'${held.framer ? ` ${held.framer}` : ''}`);
+            this.keepCookiesHere(answer, out);
+            return new Response(answer.body, { status: answer.status, statusText: answer.statusText, headers: out });
+        }
         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)
@@ -552,12 +624,7 @@ export class WorldDoors {
             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`);
-            }
+            this.keepCookiesHere(answer, out);
             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
@@ -971,6 +1038,33 @@ export class WorldDoors {
         }
         return out;
     }
+    /** What a twin asks an application (`ctx.ask`) that this World can answer truthfully, where no process routes it (a
+     *  hosted World's isolate): a GET or HEAD of a URL whose hostname one of this World's twins answers (its hostsClaimed
+     *  door: a Cloudflare twin's Worker route or custom domain) is that twin's answer, read as a browser reads the site
+     *  here (`site`). Any other question (another method, a hostname no twin claims) is undefined: it goes on as it would
+     *  without this router (the application route, the World's egress rule, the network), never a World-made answer
+     *  dressed as the application's (architecture, "What an author writes, and how"). Given to each twin's fetch as its
+     *  `application` by apps/cloud. */
+    async askInWorld(target, init) {
+        const method = (init.method ?? 'GET').toUpperCase();
+        if (method !== 'GET' && method !== 'HEAD')
+            return undefined;
+        let url;
+        try {
+            url = new URL(target);
+        }
+        catch {
+            return undefined;
+        }
+        if (url.protocol !== 'https:' && url.protocol !== 'http:')
+            return undefined;
+        const host = url.hostname.toLowerCase().replace(/\.$/, '');
+        const claimed = await this.claimedHosts(url.origin);
+        if (!claimed.some(({ hosts }) => hosts.includes(host)))
+            return undefined;
+        const answer = await this.site(new Request(url, { method, headers: init.headers ?? {} }), host);
+        return { status: answer.status, body: await answer.text() };
+    }
     /** 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. */
@@ -1021,6 +1115,11 @@ export class WorldDoors {
                 return Response.json({ ok: true, world: this.served, worlds: [this.served] });
             if (this.onPages(url))
                 return await this.pagesPlane(request, url);
+            const hostedSite = await this.hostedSiteOf(url);
+            if (hostedSite)
+                return await this.pagesPlane(request, url, hostedSite);
+            if (this.siteShaped(url))
+                return Response.json({ error: `no site of ${this.served} at ${url.host}` }, { status: 404 });
             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
@@ -1184,10 +1283,9 @@ export class WorldDoors {
         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
-        const at = this.host.sitesOrigin?.() ?? null;
-        const sites = at ? new URL(at) : null;
-        if (sites)
-            headers.set(TWIN_SITES_HEADER, `${sites.protocol}//{host}.${sites.host}`);
+        const sitesAt = this.host.sitesTemplate?.() ?? null;
+        if (sitesAt)
+            headers.set(TWIN_SITES_HEADER, sitesAt);
         else
             headers.delete(TWIN_SITES_HEADER);
         const body = request.method === 'GET' || request.method === 'HEAD' ? undefined : await request.arrayBuffer();
@@ -1391,6 +1489,31 @@ export class WorldDoors {
         // a browser session is opened by either token: the read token's is how a view-only link opens a vendor's screens
         // the session gate comes first: a page that holds only the cookie (a sibling World's, the same site) can neither
         // re-issue nor end the session through this door
+        // A HOSTED SITE OPENED (`GET sites/go?host=<hostname>&land=<path>`): a person's navigation, handed to the site's own
+        // address with a one-time read pass. A navigation from a sibling address (the site's own page, linking back here) is
+        // taken too: it only opens, in this person's own browser, a read of this World's own site
+        if (kind === 'sites' && name === 'go' && request.method === 'GET') {
+            const fetchSite = request.headers.get('sec-fetch-site');
+            const dest = request.headers.get('sec-fetch-dest');
+            // a person's navigation (from here, from the site's own page linking back, or typed in), or a frame of this World's
+            // own console (its board, its comparison)
+            const navigated = dest === 'document' && ['same-origin', 'same-site', 'none'].includes(fetchSite ?? '');
+            const framed = dest === 'iframe' && fetchSite === 'same-origin';
+            if (via === 'session' && !navigated && !framed)
+                return Response.json({ error: "a hosted site opens on a person's navigation" }, { status: 403 });
+            const template = this.host.sitesTemplate?.() ?? null;
+            const hostname = (url.searchParams.get('host') ?? '').toLowerCase();
+            const claimed = (await this.claimedHosts(url.origin)).some(({ hosts }) => hosts.some((h) => h.toLowerCase() === hostname));
+            const at = template && claimed ? siteUrlOf(template, hostname) : null;
+            if (!at)
+                return Response.json({ error: `${hostname || 'that host'} is no site of ${this.served} shown here` }, { status: 404 });
+            const asked = this.credential(request);
+            const land = url.searchParams.get('land') ?? '/';
+            const passed = this.mintPagesPass('read', { site: hostname, ...(asked.session ? { session: asked.session } : {}), ...(asked.who ? { who: asked.who } : {}), ...(this.host.browserOrigin?.() ? { framer: this.host.browserOrigin() } : {}) });
+            if (!passed)
+                return Response.json({ error: 'too many sites opened at once: try again in a minute' }, { status: 429 });
+            return new Response(null, { status: 303, headers: { location: `${at}/-/${this.served}/pages/open#${new URLSearchParams({ pass: passed, land: land.startsWith('/') ? land : '/' }).toString()}`, 'cache-control': 'no-store', 'referrer-policy': 'no-referrer' } });
+        }
         const foreign = this.crossOriginSession(request, via);
         if (foreign)
             return foreign;
@@ -1984,7 +2107,7 @@ export class WorldDoors {
             }
             catch { /* a World with no local branches */ }
             // each with the origin a browser reaches it at, where this host gives Worlds one (its sites are under it)
-            const rows = (await branches.list()).map((b) => { const origin = this.host.originOf?.(b.name) ?? null; return origin ? { ...b, origin } : b; });
+            const rows = (await branches.list()).map((b) => { const origin = this.host.originOf?.(b.name) ?? null; const sites = this.host.sitesTemplateOf?.(b.name) ?? null; return { ...b, ...(origin ? { origin } : {}), ...(sites ? { sites } : {}) }; });
             return Response.json({ world: this.served, branches: rows, 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
@@ -2068,11 +2191,13 @@ export class WorldDoors {
                 // session removes it, so no write token ever reaches a page's script (or a frame beside it)
                 // `origin`: where the branch's own pages are, when it has an origin of its own (a page moves there to view it)
                 const origin = this.host.originOf?.(made.name) ?? null;
+                const sites = this.host.sitesTemplateOf?.(made.name) ?? null;
+                const where = { ...(origin ? { origin } : {}), ...(sites ? { sites } : {}) };
                 if (via === 'session') {
                     const { token: _write, ...viewed } = made;
-                    return Response.json({ ...viewed, ...(origin ? { origin } : {}) }, { status: 201 });
+                    return Response.json({ ...viewed, ...where }, { status: 201 });
                 }
-                return Response.json({ ...made, ...(origin ? { origin } : {}) }, { status: 201 });
+                return Response.json({ ...made, ...where }, { status: 201 });
             }
             catch (error) {
                 this.keepKeys(this.keys().filter((k) => k.id !== keyId)); // no branch, no key
@@ -2136,8 +2261,20 @@ export class WorldDoors {
     /** Every twin's frames, where each opens here, and each with the changes not yet cut that are its own. */
     async boardFrames(url) {
         const claimed = new Map((await this.claimedHosts(url.origin)).map(({ vendor, hosts }) => [vendor, new Set(hosts)]));
-        const routed = this.host.sitesOrigin?.() ?? null;
-        const sites = routed ? new URL(routed) : null;
+        const sitesAt = this.host.sitesTemplate?.() ?? null;
+        // a site private to the World's people (a `{site}` template: a hosted World) opens through this World's own origin,
+        // which hands its address a one-time read pass (sites/go); one on this machine opens at its address
+        const siteAt = (hostname, rest) => {
+            if (!sitesAt)
+                return null;
+            const direct = siteUrlOf(sitesAt, hostname);
+            if (!direct)
+                return null;
+            if (sitesAt.includes('{host}'))
+                return `${direct}${rest}`;
+            const own = this.host.browserOrigin?.() ?? null;
+            return own ? `${own}/-/${this.served}/sites/go?${new URLSearchParams({ host: hostname, land: rest }).toString()}` : null;
+        };
         const delta = diffWorld(this.name, { root: this.worldRoot });
         const received = new Set(listWorldChangesets({ root: this.worldRoot, world: this.name }).filter((l) => l.changeset.pushedBy).flatMap((l) => l.changeset.actions.map((a) => a.action.id)));
         const changes = delta.actions.filter((a) => !received.has(a.action.id));
@@ -2166,8 +2303,10 @@ export class WorldDoors {
                 let unseen;
                 try {
                     const u = new URL(f.url);
-                    if (claimed.get(vendor)?.has(u.hostname.toLowerCase()))
-                        at = sites ? { site: `${sites.protocol}//${u.hostname.toLowerCase()}.${sites.host}${u.pathname}${u.search}` } : null;
+                    if (claimed.get(vendor)?.has(u.hostname.toLowerCase())) {
+                        const opened = siteAt(u.hostname.toLowerCase(), `${u.pathname}${u.search}`);
+                        at = opened ? { site: opened } : null;
+                    }
                     else if (f.drawn)
                         at = { screen: `${u.pathname}${u.search}` };
                     if (!at)

package/dist/src/world-view.js

@@ -49,10 +49,11 @@ export async function serveWorldView(name, opts = {}) {
     let base = null;
     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;
+    // each site nested under its World's origin (`<hostname>.<world>--<org>.localhost`, siteOfHost)
+    const sitesTemplate = origins && !proxied ? (served) => { const o = port ? localWorldOrigin(served, port) : null; return o ? `http://{host}.${new URL(o).host}` : null; } : undefined;
     // 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 mountAt = (at) => mountWorld(loadWorldConfig(join(at, stateDirName(), 'world.json'), at).config.id, { root: at, branches: (served) => branches.doorsFor(served), ...(browserOrigin ? { browserOrigin } : {}), ...(sitesTemplate ? { sitesTemplate } : {}), ...(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
@@ -94,7 +95,7 @@ export async function serveWorldView(name, opts = {}) {
             switching = false;
         }
     };
-    const mountOpts = { root, branches: (served) => branches.doorsFor(served), ...(browserOrigin ? { browserOrigin } : {}), ...(sitesOrigin ? { sitesOrigin } : {}), ...(pagesOrigin ? { pagesOrigin } : {}), ...(local ? { localTrust: true, ...(opts.localPerson ? { localPerson: opts.localPerson } : {}) } : {}), serveBranch };
+    const mountOpts = { root, branches: (served) => branches.doorsFor(served), ...(browserOrigin ? { browserOrigin } : {}), ...(sitesTemplate ? { sitesTemplate } : {}), ...(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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-runtime",
-  "version": "3.0.17",
+  "version": "3.0.19",
   "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.17",
-    "@volter/world-console": "3.0.12"
+    "@volter/world-core": "3.0.19",
+    "@volter/world-console": "3.0.14"
   },
   "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.17",
+    "@volter/world-core": "3.0.19",
     "pg-gateway": "0.3.0-beta.4",
     "smol-toml": "^1.8.0",
     "yaml": "2.9.0"

package/src/served-world.ts

@@ -26,7 +26,7 @@ import { getActiveWorldStore, withHistoryLocks, captureHistory, historyAtInstant
 // to `.volter/token` and `.volter/token.read` (0600).
 // One writer per world by construction: the doors run in this process, serialized per twin.
 import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync , rmSync} from 'node:fs';
-import { CALLER_HEADER, callerForHeader, newTraceparent, parseTraceparent, traceparentForDelivery, readTwinRequestJournalFrom, type TwinRequestJournalCursor, assertSafeChangesetName, blobDigest, destinationOf, getActiveBlobStore, journalTwinRequest, loadCheck, twinRequestJournalFailures, openSealedAt, readTwinRequestJournal, serveHttp, twinRequestCredentials, TWIN_PREFIX_HEADER, TWIN_SITES_HEADER, ORIGINAL_PATH_HEADER, validateRemoteOrigin, type SealedCredential, type TwinStreamConnection, type TwinStreamSink, type BoardFrame } from '@volter/world-core/runtime';
+import { CALLER_HEADER, callerForHeader, newTraceparent, parseTraceparent, traceparentForDelivery, readTwinRequestJournalFrom, type TwinRequestJournalCursor, assertSafeChangesetName, blobDigest, destinationOf, getActiveBlobStore, journalTwinRequest, loadCheck, twinRequestJournalFailures, openSealedAt, readTwinRequestJournal, serveHttp, twinRequestCredentials, TWIN_PREFIX_HEADER, TWIN_SITES_HEADER, siteLabel, siteUrlOf, ORIGINAL_PATH_HEADER, validateRemoteOrigin, type SealedCredential, type TwinStreamConnection, type TwinStreamSink, type BoardFrame } from '@volter/world-core/runtime';
 import { APP_READ_ENDPOINT_ENV } from './init.ts';
 import { packFacts } from './pack-facts.ts';
 import { grantOf, presentedSecrets, sameSecret, spentPasses, verifyPass, type TrustedIssuer, type WorldCredentials } from '@volter/world-access';
@@ -164,12 +164,13 @@ export type MountedWorld = { name: string; served: string; root: string; readonl
 /** 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
+type PagesGrant = { scope: 'read' | 'write'; session?: string; who?: string; framer?: string; local?: true; /** the hosted site it
+ *  opens (a hostname this World's twins answer), not the content plane */ site?: string; /** 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; /** 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> {
+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.sitesTemplate */ sitesTemplate?: (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) {
@@ -197,7 +198,7 @@ export async function mountWorld(name: string, opts: { /** the platforms whose p
     clockPath: () => clockFile(worldRoot, name),
     ...(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.sitesTemplate ? { sitesTemplate: () => opts.sitesTemplate!(served), sitesTemplateOf: (other: string) => opts.sitesTemplate!(other) } : {}),
     ...(opts.pagesOrigin ? { pagesOrigin: () => opts.pagesOrigin!(served) } : {}),
     ...(opts.localTrust ? { localTrust: () => true, ...(opts.localPerson ? { localPerson: () => opts.localPerson } : {}) } : {}),
     ...(opts.serveBranch ? { serveBranch: opts.serveBranch } : {}),
@@ -355,9 +356,12 @@ export type DoorHost = {
    *  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;
+  /** Where this host shows the hostnames the World's twins answer: a sites template (world-core siteUrlOf), `{host}`
+   *  nested under the World's origin on this machine (siteOfHost), `{site}` as one label beside it on a hosted World
+   *  (each such site private to the World's people); none where it routes no sites (behind a proxy). */
+  sitesTemplate?: () => string | null;
+  /** Another World's (a branch of this one) sites template, where this host routes its sites. */
+  sitesTemplateOf?: (served: string) => string | null;
   /** The origin another World this host serves (a branch of this one) is reached at, where it has one of its own. */
   originOf?: (served: string) => string | null;
   /** This World is served on this machine's loopback, for the person at it: a page of this World, reached by a
@@ -472,6 +476,11 @@ export class WorldDoors {
   pagesPass(scope: 'read' | 'write', land: string, grant: Omit<PagesGrant, 'scope'> = {}): string | null {
     const at = this.host.pagesOrigin?.() ?? null;
     if (at === null) return null;
+    const pass = this.mintPagesPass(scope, grant);
+    return pass ? `${at}/-/${this.served}/pages/open#${new URLSearchParams({ pass, land }).toString()}` : null;
+  }
+  /** A one-time pass (a minute long) for the content plane or a hosted site; null when its asker holds fifty unused. */
+  private mintPagesPass(scope: 'read' | 'write', grant: Omit<PagesGrant, 'scope'>): string | 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';
@@ -479,18 +488,50 @@ export class WorldDoors {
     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()}`;
+    return pass;
+  }
+  /** The hostname a hosted site address names (`{site}` template: `<label>--<world>--<org>.<suffix>`) among those this
+   *  World's twins claim; null for any other address. */
+  /** Whether an address has a hosted site's shape here (`<label>--<world>--<org>.<suffix>`), claimed or not. */
+  private siteShaped(url: URL): boolean {
+    const template = this.host.sitesTemplate?.() ?? null;
+    if (!template || !template.includes('{site}')) return false;
+    const after = new URL(template.replace('{site}', 'x')).host.slice(1);
+    return url.host.endsWith(after) && url.host.length > after.length;
+  }
+  private async hostedSiteOf(url: URL): Promise<string | null> {
+    if (!this.siteShaped(url)) return null;
+    const template = this.host.sitesTemplate?.() ?? null;
+    if (!template || !template.includes('{site}')) return null;
+    const after = new URL(template.replace('{site}', 'x')).host.slice(1);
+    if (!url.host.endsWith(after) || url.host.length <= after.length) return null;
+    const label = url.host.slice(0, -after.length);
+    for (const { hosts } of await this.claimedHosts(url.origin)) for (const h of hosts) if (siteLabel(h) === label) return h.toLowerCase();
+    return null;
   }
   private pagesCookie(url: URL): string { return url.protocol === 'https:' ? '__Host-volter_pages' : 'volter_pages'; }
-  private pageSession(request: Request, url: URL): ({ id: string } & PagesGrant) | null {
+  private pageSession(request: Request, url: URL, site?: string): ({ 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;
+    // a session opens only where its pass was for: the content plane, or that one hosted site
+    if ((held.site ?? null) !== (site ?? null)) return null;
     const { until: _until, ...grant } = held;
     return { id, ...grant };
   }
+  /** A twin's cookies, kept to the origin answering (the content plane, a hosted site): partitioned as its frames need,
+   *  never set for a parent domain every World shares, and never the World's own session cookies. */
+  private keepCookiesHere(answer: Response, out: Headers): void {
+    const cookies = answer.headers.getSetCookie();
+    if (!cookies.length) return;
+    out.delete('set-cookie');
+    for (const c of cookies) {
+      if (/^\s*(?:__Host-)?volter_(?:world|pages)=/i.test(c)) continue;
+      out.append('set-cookie', `${c.replace(/;\s*(?:samesite=[^;]*|secure|partitioned|domain=[^;]*)\s*(?=;|$)/gi, '')}; SameSite=None; Secure; Partitioned`);
+    }
+  }
   /** 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> {
+  private async pagesPlane(request: Request, url: URL, /** a hosted site served here, not the content plane */ site?: string): 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;
@@ -498,7 +539,7 @@ export class WorldDoors {
       // 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>`,
+      return new Response(`<!doctype html><meta charset="utf-8"><title>${this.served}</title><body data-world="${this.served}"${site ? ' data-site="1"' : ''}><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') {
@@ -510,7 +551,9 @@ export class WorldDoors {
   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 {}
+  // a hosted site lands anywhere on it; the content plane only under this World
+  const anywhere = document.body.dataset.site === '1';
+  try { const u = new URL(land, location.origin); if (land.startsWith('/') && !/[\\\\\\s]/.test(land) && u.origin === location.origin && (anywhere || 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.'; })
@@ -525,10 +568,10 @@ export class WorldDoors {
       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 });
+      if (!given || given.until <= Date.now() || !this.pagesParentLive(given) || (given.site ?? null) !== (site ?? null)) 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 same = (x: PagesGrant): boolean => x.scope === grant.scope && x.session === grant.session && x.asker === grant.asker && x.framer === grant.framer && x.who === grant.who && x.site === grant.site;
       const now = Date.now();
       const found = Object.entries(this.pagesSessions()).find(([, x]) => x.until > now && same(x))?.[0];
       const id = found ?? mintToken('pgs_');
@@ -536,6 +579,28 @@ export class WorldDoors {
       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` } });
     }
+    // A HOSTED SITE: read with a session its World's own origin gave it a pass for (sites/go), never without
+    if (site) {
+      const held = this.pageSession(request, url, site);
+      const back = own ? `${own}/-/${this.served}/sites/go?${new URLSearchParams({ host: site, land: `${url.pathname}${url.search}` }).toString()}` : null;
+      if (!held) {
+        if (request.method === 'GET' && (request.headers.get('accept') ?? '').includes('text/html') && back) {
+          const shown = site.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+          return new Response(`<!doctype html><meta charset="utf-8"><title>${shown}</title><body style="font:16px system-ui;margin:3em;color:#555"><p><b>${shown}</b> is a site in the World ${this.served}, shown to its people.</p><p><a href="${back.replace(/&/g, '&amp;')}">Open it from the World</a></p></body>`, { status: 401, headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', 'referrer-policy': 'no-referrer' } });
+        }
+        return Response.json({ error: `${site} is shown to ${this.served}'s people: open it from the World` }, { status: 401 });
+      }
+      // read by the site's own pages, or a person's navigation to it: never by another page of the same domain (the
+      // session's partition is the domain's, which every World's pages share)
+      const fetchSite = request.headers.get('sec-fetch-site');
+      const navigation = ['document', 'iframe'].includes(request.headers.get('sec-fetch-dest') ?? '');
+      if (fetchSite !== 'same-origin' && !(navigation && ['none', 'same-site'].includes(fetchSite ?? ''))) return Response.json({ error: `${site} is read by its own pages` }, { status: 403 });
+      const answer = await this.site(request, site);
+      const out = new Headers(answer.headers);
+      out.append('content-security-policy', `frame-ancestors 'self'${held.framer ? ` ${held.framer}` : ''}`);
+      this.keepCookiesHere(answer, out);
+      return new Response(answer.body, { status: answer.status, statusText: answer.statusText, headers: out });
+    }
     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;
@@ -545,11 +610,7 @@ export class WorldDoors {
       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`);
-      }
+      this.keepCookiesHere(answer, out);
       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
@@ -879,6 +940,26 @@ export class WorldDoors {
     return out;
   }
 
+  /** What a twin asks an application (`ctx.ask`) that this World can answer truthfully, where no process routes it (a
+   *  hosted World's isolate): a GET or HEAD of a URL whose hostname one of this World's twins answers (its hostsClaimed
+   *  door: a Cloudflare twin's Worker route or custom domain) is that twin's answer, read as a browser reads the site
+   *  here (`site`). Any other question (another method, a hostname no twin claims) is undefined: it goes on as it would
+   *  without this router (the application route, the World's egress rule, the network), never a World-made answer
+   *  dressed as the application's (architecture, "What an author writes, and how"). Given to each twin's fetch as its
+   *  `application` by apps/cloud. */
+  async askInWorld(target: string, init: RequestInit): Promise<{ status: number; body: string } | undefined> {
+    const method = (init.method ?? 'GET').toUpperCase();
+    if (method !== 'GET' && method !== 'HEAD') return undefined;
+    let url: URL;
+    try { url = new URL(target); } catch { return undefined; }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') return undefined;
+    const host = url.hostname.toLowerCase().replace(/\.$/, '');
+    const claimed = await this.claimedHosts(url.origin);
+    if (!claimed.some(({ hosts }) => hosts.includes(host))) return undefined;
+    const answer = await this.site(new Request(url, { method, headers: init.headers ?? {} }), host);
+    return { status: answer.status, body: await answer.text() };
+  }
+
   /** 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. */
@@ -914,6 +995,9 @@ 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);
+      const hostedSite = await this.hostedSiteOf(url);
+      if (hostedSite) return await this.pagesPlane(request, url, hostedSite);
+      if (this.siteShaped(url)) return Response.json({ error: `no site of ${this.served} at ${url.host}` }, { status: 404 });
       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
@@ -1048,9 +1132,8 @@ export class WorldDoors {
     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
-    const at = this.host.sitesOrigin?.() ?? null;
-    const sites = at ? new URL(at) : null;
-    if (sites) headers.set(TWIN_SITES_HEADER, `${sites.protocol}//{host}.${sites.host}`); else headers.delete(TWIN_SITES_HEADER);
+    const sitesAt = this.host.sitesTemplate?.() ?? null;
+    if (sitesAt) headers.set(TWIN_SITES_HEADER, sitesAt); else headers.delete(TWIN_SITES_HEADER);
     const body = request.method === 'GET' || request.method === 'HEAD' ? undefined : await request.arrayBuffer();
     const answer = await twin(new Request(`${url.origin}/${tail.join('/')}${url.search}`, { method: request.method, headers, ...(body === undefined ? {} : { body }), redirect: 'manual' }));
     // an upgrade the twin answered (a tunnel's control or visitor socket) goes back as it is
@@ -1214,6 +1297,28 @@ export class WorldDoors {
     // a browser session is opened by either token: the read token's is how a view-only link opens a vendor's screens
     // the session gate comes first: a page that holds only the cookie (a sibling World's, the same site) can neither
     // re-issue nor end the session through this door
+    // A HOSTED SITE OPENED (`GET sites/go?host=<hostname>&land=<path>`): a person's navigation, handed to the site's own
+    // address with a one-time read pass. A navigation from a sibling address (the site's own page, linking back here) is
+    // taken too: it only opens, in this person's own browser, a read of this World's own site
+    if (kind === 'sites' && name === 'go' && request.method === 'GET') {
+      const fetchSite = request.headers.get('sec-fetch-site');
+      const dest = request.headers.get('sec-fetch-dest');
+      // a person's navigation (from here, from the site's own page linking back, or typed in), or a frame of this World's
+      // own console (its board, its comparison)
+      const navigated = dest === 'document' && ['same-origin', 'same-site', 'none'].includes(fetchSite ?? '');
+      const framed = dest === 'iframe' && fetchSite === 'same-origin';
+      if (via === 'session' && !navigated && !framed) return Response.json({ error: "a hosted site opens on a person's navigation" }, { status: 403 });
+      const template = this.host.sitesTemplate?.() ?? null;
+      const hostname = (url.searchParams.get('host') ?? '').toLowerCase();
+      const claimed = (await this.claimedHosts(url.origin)).some(({ hosts }) => hosts.some((h) => h.toLowerCase() === hostname));
+      const at = template && claimed ? siteUrlOf(template, hostname) : null;
+      if (!at) return Response.json({ error: `${hostname || 'that host'} is no site of ${this.served} shown here` }, { status: 404 });
+      const asked = this.credential(request);
+      const land = url.searchParams.get('land') ?? '/';
+      const passed = this.mintPagesPass('read', { site: hostname, ...(asked.session ? { session: asked.session } : {}), ...(asked.who ? { who: asked.who } : {}), ...(this.host.browserOrigin?.() ? { framer: this.host.browserOrigin!()! } : {}) });
+      if (!passed) return Response.json({ error: 'too many sites opened at once: try again in a minute' }, { status: 429 });
+      return new Response(null, { status: 303, headers: { location: `${at}/-/${this.served}/pages/open#${new URLSearchParams({ pass: passed, land: land.startsWith('/') ? land : '/' }).toString()}`, 'cache-control': 'no-store', 'referrer-policy': 'no-referrer' } });
+    }
     const foreign = this.crossOriginSession(request, via);
     if (foreign) return foreign;
     // a named key is an app's: it opens no browser session (which would outlive the key and could make keys of its own),
@@ -1673,7 +1778,7 @@ export class WorldDoors {
       let named: Array<{ name: string; running: boolean }> = [];
       try { named = listWorlds(this.worldRoot).map((w) => ({ name: w.name, running: w.running })); } catch { /* a World with no local branches */ }
       // each with the origin a browser reaches it at, where this host gives Worlds one (its sites are under it)
-      const rows = (await branches.list()).map((b) => { const origin = this.host.originOf?.(b.name) ?? null; return origin ? { ...b, origin } : b; });
+      const rows = (await branches.list()).map((b) => { const origin = this.host.originOf?.(b.name) ?? null; const sites = this.host.sitesTemplateOf?.(b.name) ?? null; return { ...b, ...(origin ? { origin } : {}), ...(sites ? { sites } : {}) }; });
       return Response.json({ world: this.served, branches: rows, 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
@@ -1737,8 +1842,10 @@ export class WorldDoors {
         // session removes it, so no write token ever reaches a page's script (or a frame beside it)
         // `origin`: where the branch's own pages are, when it has an origin of its own (a page moves there to view it)
         const origin = this.host.originOf?.(made.name) ?? null;
-        if (via === 'session') { const { token: _write, ...viewed } = made; return Response.json({ ...viewed, ...(origin ? { origin } : {}) }, { status: 201 }); }
-        return Response.json({ ...made, ...(origin ? { origin } : {}) }, { status: 201 });
+        const sites = this.host.sitesTemplateOf?.(made.name) ?? null;
+        const where = { ...(origin ? { origin } : {}), ...(sites ? { sites } : {}) };
+        if (via === 'session') { const { token: _write, ...viewed } = made; return Response.json({ ...viewed, ...where }, { status: 201 }); }
+        return Response.json({ ...made, ...where }, { status: 201 });
       } catch (error) {
         this.keepKeys(this.keys().filter((k) => k.id !== keyId)); // no branch, no key
         return Response.json({ error: error instanceof Error ? error.message : String(error) }, { status: 409 });
@@ -1797,8 +1904,17 @@ export class WorldDoors {
   /** Every twin's frames, where each opens here, and each with the changes not yet cut that are its own. */
   private async boardFrames(url: URL): Promise<{ delta: ReturnType<typeof diffWorld>; frames: Array<{ frame: Record<string, unknown> & { vendor: string; id: string }; mine: Array<ReturnType<typeof diffWorld>['actions'][number]> }> }> {
     const claimed = new Map((await this.claimedHosts(url.origin)).map(({ vendor, hosts }) => [vendor, new Set(hosts)]));
-    const routed = this.host.sitesOrigin?.() ?? null;
-    const sites = routed ? new URL(routed) : null;
+    const sitesAt = this.host.sitesTemplate?.() ?? null;
+    // a site private to the World's people (a `{site}` template: a hosted World) opens through this World's own origin,
+    // which hands its address a one-time read pass (sites/go); one on this machine opens at its address
+    const siteAt = (hostname: string, rest: string): string | null => {
+      if (!sitesAt) return null;
+      const direct = siteUrlOf(sitesAt, hostname);
+      if (!direct) return null;
+      if (sitesAt.includes('{host}')) return `${direct}${rest}`;
+      const own = this.host.browserOrigin?.() ?? null;
+      return own ? `${own}/-/${this.served}/sites/go?${new URLSearchParams({ host: hostname, land: rest }).toString()}` : null;
+    };
     const delta = diffWorld(this.name, { root: this.worldRoot });
     const received = new Set(listWorldChangesets({ root: this.worldRoot, world: this.name }).filter((l) => l.changeset.pushedBy).flatMap((l) => l.changeset.actions.map((a) => a.action.id)));
     const changes = delta.actions.filter((a) => !received.has(a.action.id));
@@ -1823,7 +1939,7 @@ export class WorldDoors {
         let unseen: 'not-drawn' | 'sites-not-routed' | undefined;
         try {
           const u = new URL(f.url);
-          if (claimed.get(vendor)?.has(u.hostname.toLowerCase())) at = sites ? { site: `${sites.protocol}//${u.hostname.toLowerCase()}.${sites.host}${u.pathname}${u.search}` } : null;
+          if (claimed.get(vendor)?.has(u.hostname.toLowerCase())) { const opened = siteAt(u.hostname.toLowerCase(), `${u.pathname}${u.search}`); at = opened ? { site: opened } : null; }
           else if (f.drawn) at = { screen: `${u.pathname}${u.search}` };
           if (!at) unseen = claimed.get(vendor)?.has(u.hostname.toLowerCase()) ? 'sites-not-routed' : 'not-drawn';
         } catch { at = null; unseen = 'not-drawn'; }

package/src/world-view.ts

@@ -50,10 +50,11 @@ export async function serveWorldView(name: string, opts: { /** the person signed
   let base: string | null = null;
   const browserOrigin = origins ? (served: string) => (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: string) => (port ? localWorldOrigin(served, port) : null) : undefined;
+  // each site nested under its World's origin (`<hostname>.<world>--<org>.localhost`, siteOfHost)
+  const sitesTemplate = origins && !proxied ? (served: string) => { const o = port ? localWorldOrigin(served, port) : null; return o ? `http://{host}.${new URL(o).host}` : null; } : undefined;
   // the content plane beside each World's origin (`<world>--<org>--pages.localhost`): its twins' pages, apart from its doors
   const pagesOrigin = origins && !proxied ? (served: string) => (port ? pagesOriginOf(served, 'http:', 'localhost', port) : null) : undefined;
-  const mountAt = (at: string): Promise<MountedWorld> => 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 mountAt = (at: string): Promise<MountedWorld> => mountWorld(loadWorldConfig(join(at, stateDirName(), 'world.json'), at).config.id, { root: at, branches: (served) => branches.doorsFor(served), ...(browserOrigin ? { browserOrigin } : {}), ...(sitesTemplate ? { sitesTemplate } : {}), ...(pagesOrigin ? { pagesOrigin } : {}), ...(local ? { localTrust: true, ...(opts.localPerson ? { localPerson: opts.localPerson } : {}) } : {}) });
   const branches: LocalBranches = 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
@@ -84,7 +85,7 @@ export async function serveWorldView(name: string, opts: { /** the person signed
       if (branch === loadWorldConfig(join(root, stateDirName(), 'world.json'), root).config.id) rmSync(current, { force: true }); else writeFileSync(current, `${branch}\n`);
     } finally { switching = false; }
   };
-  const mountOpts = { root, branches: (served: string) => branches.doorsFor(served), ...(browserOrigin ? { browserOrigin } : {}), ...(sitesOrigin ? { sitesOrigin } : {}), ...(pagesOrigin ? { pagesOrigin } : {}), ...(local ? { localTrust: true, ...(opts.localPerson ? { localPerson: opts.localPerson } : {}) } : {}), serveBranch };
+  const mountOpts = { root, branches: (served: string) => branches.doorsFor(served), ...(browserOrigin ? { browserOrigin } : {}), ...(sitesTemplate ? { sitesTemplate } : {}), ...(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);