@volter/world-runtime 2.0.1 → 2.0.2

package/src/served-world.ts

@@ -1,4 +1,4 @@
-import { getActiveWorldStore, withAncestryLock, captureHistory, historyDigest, historyEntries, historyLength, readHistoryView, worldPaths, type HistoryReference } from '@volter/world-core';
+import { getActiveWorldStore, withAncestryLock, captureHistory, historyAtInstant, historyDigest, historyEntries, historyLength, readHistoryView, worldPaths, type HistoryReference } from '@volter/world-core';
 // A SERVED WORLD (docs/reference/http-api.md#a-served-world): `volter world serve` puts a world at
 // `http://<host>:<port>/<org>/<world>/`. Each twin's vendor API is under its vendor id — the
 // addressed grammar RH2 depends on — and the world's own doors are under `/-/<org>/<world>/`:
@@ -14,23 +14,33 @@ import { getActiveWorldStore, withAncestryLock, captureHistory, historyDigest, h
 //   GET/PUT twins/<vendor>/root      the vendor's real account behind the twin (PUT null clears)
 //   PUT  twins/<vendor>/credential   seal the credential; GET answers only that one is sealed
 //   POST twins/<vendor>/refresh      observe the root now
-// Tokens ride `x-volter-token`: the token opens everything, the read token only GET. `serve` mints
-// both, prints them once and writes them to `.volter/token` and `.volter/token.read` (0600).
+// and what a person looks into it through (docs/contributing/architecture.md, "Viewing a World"):
+//   GET  map | timeline | diff       every twin and what it holds; the logs merged newest first; the changes since the base
+//   GET/PUT clock, POST clock/advance   the frozen instant every twin stamps from, forward only
+//   GET/POST branches, DELETE branches/<org>/<world>   the host's branches of this World ("as of" views)
+//   GET  history?at=<instant>        each twin's history cut at an instant (where such a branch starts)
+//   GET  /<org>/<world>/<vendor>/mirror/   the twin's mirror, keyless: the vendor's own UI over this World's wire
+// Tokens ride `x-volter-token`: the token opens everything, the read token only reads — on the vendor
+// wire, a twin that enforces it (`requestScopes: ['read']`) is handed the read token's other requests
+// marked read-only and refuses the writes itself. `serve` mints both, prints them once and writes them
+// 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 { blobDigest, getActiveBlobStore, loadCheck, mirrorShellUnder, openSealedCredential, readTwinRequestJournal, sealingKey, serveHttp, TWIN_PREFIX_HEADER, validateRemoteOrigin, type SealedCredential, type TwinStreamConnection, type TwinStreamSink } from '@volter/world-core';
 import { APP_READ_ENDPOINT_ENV } from './init.ts';
+import { grantOf, presentedSecrets, sameSecret, spentPasses, verifyPass, type TrustedIssuer, type WorldCredentials } from '@volter/world-access';
+import { createHash } from 'node:crypto';
 import { dirname, join, resolve } from 'node:path';
 import {
-  appendActionIfAbsent, branchEntries, confirmAction, readTree, stateDirName, wholeLog, worldNow,
+  appendActionIfAbsent, branchEntries, branchLogPath, branchMetaPath, confirmAction, parentLogPath, readTree, stateDirName, wholeLog, worldNow,
   parentEntries, rebaseBranch, type Changeset, type Entry, type Receipt, type RootConfig,
 } from '@volter/world-core';
-import { approveWorldChangeset, createWorldChangeset, findWorldChangeset, listWorldChangesets, pushWorldChangeset, verifyWorldChangeset, worldChangesetsDir } from './changeset.ts';
+import { approveWorldChangeset, createWorldChangeset, diffWorld, findWorldChangeset, listWorldChangesets, pushWorldChangeset, verifyWorldChangeset, worldChangesetsDir } from './changeset.ts';
 import { fetchFromOrigin } from './origin.ts';
 import { CONSOLE_BASE, consoleRedirect, serveConsoleApart, type ConsoleMount } from './console-apart.ts';
 import { loadWorldConfig } from './configs.ts';
-import { adaptersFor, packMirrorExports, credentialPath, credentialPayloadFrom, deployTwin, deployWorld, loadWorldChecks, twinSigningSecret, materializeRoots, refreshPosture, refreshTwin, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, spanMs } from './root.ts';
-import { downWorld, statusWorld, upWorld } from './runtime.ts';
+import { adaptersFor, credentialPath, packMirror, type PackMirror, credentialPayloadFrom, deployTwin, deployWorld, loadWorldChecks, twinSigningSecret, materializeRoots, refreshPosture, refreshTwin, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, spanMs } from './root.ts';
+import { clockFile, downWorld, statusWorld, upWorld } from './runtime.ts';
 import type { WorldInstance } from './schema.ts';
 
 export const TOKEN_HEADER = 'x-volter-token';
@@ -64,6 +74,24 @@ export function readServeRecord(worldRoot: string): ServeRecord | null {
 
 export type ServedWorld = { url: string; base: string; name: string; port: number; token: string; readToken: string; console: string | null; stop: () => Promise<void> };
 
+/** Where a World keeps its browser sessions (WorldDoors): a host that rotates the tokens without the doors at hand
+ *  clears it itself. */
+export function sessionsFile(worldRoot: string): string { return join(worldRoot, stateDirName(), 'sessions.json'); }
+/** Where a World keeps its named keys (their hashes, never a key): `.volter/keys.json`. */
+export function keysFile(worldRoot: string): string { return join(worldRoot, stateDirName(), 'keys.json'); }
+/** A named key as the World keeps it: the SHA-256 of the key, what it may do, and when it was made and last used. */
+type HeldKey = { id: string; name: string; scope: 'read' | 'write'; hash: string; createdAt: string; lastUsedAt?: string;
+  /** who made it: the World's token, or a person's session (the subject a pass named, and its platform) */
+  createdBy?: { via: 'token' } | { via: 'session'; sub?: string; who?: string; issuer?: string } | { via: 'key'; keyId: string };
+  /** the person it was made for, when the World's token made it on their behalf (a platform, for a command) */
+  for?: string;
+  /** after this it opens nothing */
+  expiresAt?: string;
+  /** the branch this key is the parent's key of: the branch reaches its parent with it, and goes when it goes */
+  branch?: string;
+  /** the key that made that branch: revoking it removes the branch too */
+  madeWith?: string };
+const keyHash = (key: string): string => createHash('sha256').update(key).digest('hex');
 function mintToken(prefix: string): string { return `${prefix}${Buffer.from(crypto.getRandomValues(new Uint8Array(24))).toString('base64url')}`; }
 function writeSecret(path: string, value: string): void { mkdirSync(dirname(path), { recursive: true }); writeFileSync(path, `${value}\n`, { mode: 0o600 }); chmodSync(path, 0o600); }
 
@@ -85,7 +113,10 @@ function configRefFor(worldRoot: string, name: string): string {
  *  `twins()` names the world's twins once booted; `rotate()` mints both tokens anew — the old die
  *  with the call — and keeps them beside the world like `boot` does. */
 export type MountedWorld = { name: string; served: string; root: string; readonly token: string; readonly readToken: string; twins: () => string[]; rotate: () => { token: string; readToken: string }; handle: (request: Request) => Promise<Response>; boot: (url: string) => Promise<void>; stop: () => Promise<void> };
-export async function mountWorld(name: string, opts: { root?: string } = {}): Promise<MountedWorld> {
+/** A browser session a World keeps: its scope, when it ends, and the person a pass named, when one did. */
+type HeldSession = { scope: 'read' | 'write'; until: number; 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; /** served on this machine's loopback: its own pages need no token (DoorHost.localTrust) */ localTrust?: boolean } = {}): Promise<MountedWorld> {
   const worldRoot = resolve(opts.root ?? process.cwd());
   const configRef = configRefFor(worldRoot, name);
   if (loadWorldConfig(configRef, worldRoot).config.resources) {
@@ -110,6 +141,15 @@ export async function mountWorld(name: string, opts: { root?: string } = {}): Pr
       const declared = loadWorldConfig(configRef, worldRoot).config.services.find((s) => s.id === vendor)?.colocate?.scenarioPath;
       return declared ? resolve(worldRoot, declared) : null;
     },
+    // a local mirror is the pack's own, built by its builder (at serve under Bun, prebuilt under Node)
+    mirror: (vendor, file) => localMirrorFile(worldRoot, vendor, file),
+    hasMirror: async (vendor) => (await localMirror(worldRoot, vendor)) !== null,
+    mirrorSignIn: async (vendor, as, ctx) => { const mirror = await localMirror(worldRoot, vendor); try { return (await mirror?.signIn?.(as, ctx)) ?? null; } catch { return null; } },
+    clockPath: () => clockFile(worldRoot, name),
+    ...(opts.branches?.(served) ? { branches: opts.branches(served)! } : {}),
+    ...(opts.browserOrigin ? { browserOrigin: () => opts.browserOrigin!(served), originOf: (other: string) => opts.browserOrigin!(other) } : {}),
+    ...(opts.localTrust ? { localTrust: () => true } : {}),
+    ...(opts.passIssuers?.length ? { passIssuers: () => opts.passIssuers! } : {}),
     // a local twin is its own process: the wire forwards to the port it listens on
     twinFetch: (vendor) => {
       const target = instance?.services[vendor]?.url;
@@ -145,6 +185,29 @@ export async function mountWorld(name: string, opts: { root?: string } = {}): Pr
   };
 }
 
+/** A local World's mirrors: each pack's builders, found once per process, and each client built once. */
+const localMirrors = new Map<string, Promise<PackMirror | null>>();
+const builtMirrorFiles = new Map<string, Promise<string | null>>();
+function localMirror(worldRoot: string, vendor: string): Promise<PackMirror | null> {
+  const key = `${worldRoot}\0${vendor}`;
+  let held = localMirrors.get(key);
+  if (!held) { held = packMirror(vendor, worldRoot).catch(() => null); localMirrors.set(key, held); }
+  return held;
+}
+async function localMirrorFile(worldRoot: string, vendor: string, file: string): Promise<Response | null> {
+  const mirror = await localMirror(worldRoot, vendor);
+  if (!mirror) return null;
+  if (file === 'index.html') return new Response(mirror.html(), { headers: { 'content-type': 'text/html; charset=utf-8' } });
+  const build = file === 'assets/app.js' ? mirror.client : file === 'assets/styles.css' ? mirror.styles : undefined;
+  if (!build) return null;
+  const key = `${worldRoot}\0${vendor}\0${file}`;
+  let held = builtMirrorFiles.get(key);
+  // a failed build is not kept: the next request builds again
+  if (!held) { held = build().catch(() => { builtMirrorFiles.delete(key); return null; }); builtMirrorFiles.set(key, held); }
+  const body = await held;
+  return body === null ? null : new Response(body, { headers: { 'content-type': file.endsWith('.css') ? 'text/css; charset=utf-8' : 'text/javascript; charset=utf-8' } });
+}
+
 /** Boot the world (state kept) and serve it on its own port. Announces and returns after boot; `stop` downs the world. */
 export async function serveWorld(name: string, opts: { root?: string; port?: number; host?: string; consolePort?: number; announce?: (info: { name: string; base: string; token: string; readToken: string; console: string | null }) => void } = {}): Promise<ServedWorld> {
   const mounted = await mountWorld(name, opts);
@@ -213,14 +276,224 @@ export type DoorHost = {
   /** Where this host reads a twin's scenario (the handlers document a generative twin serves from,
    *  re-read on every request), or null when the twin takes none here. */
   scenarioPath?: (vendor: string) => string | null;
+  /** A twin's mirror as its pack builds it: `index.html` (the shell) or `assets/<file>`, or null when
+   *  the twin has none here. Every host answers the same mount (`/<served>/<vendor>/mirror/`); only
+   *  where the files come from differs (built at serve under Bun, prebuilt under Node, static assets
+   *  on Cloudflare). */
+  mirror?: (vendor: string, file: string) => Promise<Response | null>;
+  /** Whether the twin has a mirror on this host, without building it. */
+  hasMirror?: (vendor: string) => boolean | Promise<boolean>;
+  /** The account and token a twin's screens open signed in as, resolved by its pack from the twin's state at `root`
+   *  for the account the World's config names (`signIn.as`); null when the pack cannot, or has no such account. */
+  mirrorSignIn?: (vendor: string, as: string, ctx: { root: string; twin: (path: string, init?: RequestInit) => Promise<Response> }) => Promise<{ account: string; token: string } | null>;
+  /** Where this World's clock lives in its store (the file every twin reads `worldNow()` from). */
+  clockPath?: () => string;
+  /** The origin a browser reaches this World at (`http://<world>--<org>.localhost:<port>`), when the
+   *  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 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
+   *  loopback name, is given the World's session without a token (`localSession`). A remote host leaves it absent,
+   *  and its pages sign in with a token. */
+  localTrust?: () => boolean;
+  /** The platforms whose passes open this World (docs/contributing/architecture.md, "The hosted product"): a person a
+   *  trusted platform signed a pass for is given a session of the pass's scope. Absent, or empty, no pass opens it. */
+  passIssuers?: () => TrustedIssuer[];
+  /** This World's branches, where the host can make them (a branch is another World, so making one
+   *  is the host's act); absent, the branches doors answer 404. */
+  branches?: BranchDoors;
+};
+
+/** A branch as its parent lists it. */
+export type BranchRow = { name: string; from: string; at: { instant?: string; live?: boolean; label?: string } | null; createdAt: string; expiresAt: string | null };
+/** What a host does for a World's branches doors. `create` makes a World cloned from this one at
+ *  `at` (its history cut at that instant), removed when `ttlSeconds` runs out; `origin` is where the
+ *  request reached this World (a host whose branches clone over its public URL uses it). */
+export type BranchDoors = {
+  list: () => Promise<BranchRow[]>;
+  /** `parentKey`: the key the branch reaches this World with (never this World's own token), made for whoever asked */
+  create: (at: { instant?: string; live?: boolean; label?: string }, ttlSeconds: number | null, origin: string, parentKey?: string) => Promise<{ name: string; token: string; readToken: string; expiresAt: string | null }>;
+  remove: (name: string) => Promise<boolean>;
 };
 
+/** 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
+ *  Worlds it serves, never by parsing it. */
+export function worldOriginLabel(served: string): string | null {
+  const [org, world] = served.split('/');
+  const part = /^[a-z0-9](?:[a-z0-9]|-(?!-))*[a-z0-9]$|^[a-z0-9]$/;
+  if (!org || !world || !part.test(org) || !part.test(world)) return null;
+  const label = `${world}--${org}`;
+  return label.length <= 63 ? label : null;
+}
+
+/** The header the doors set on a read-scope request to a twin: the twin refuses the caller's writes
+ *  and still makes the vendor's own moves. It only restricts, so a twin trusts it without a token. */
+export const READ_ONLY_HEADER = 'x-volter-read-only';
+const MIRROR_ASSET = /^assets\/[A-Za-z0-9._-]+$/;
+const SPAN = /^(\d+(?:\.\d+)?)(s|m|h|d)$/;
+const SPAN_MS = { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 } as const;
+/** A W3C traceparent's trace id, or null when the value is not one. */
+function traceIdOf(traceparent: unknown): string | null {
+  const m = typeof traceparent === 'string' ? /^[0-9a-f]{2}-([0-9a-f]{32})-[0-9a-f]{16}-[0-9a-f]{2}$/.exec(traceparent) : null;
+  return m && !/^0+$/.test(m[1]!) ? m[1]! : null;
+}
+type TimelineRow = { twin: string; position: number; entry: Entry };
+/** Timeline order, newest first: by the entry's instant, then twin, then position. */
+function newerFirst(a: { at: string; twin: string; position: number }, b: { at: string; twin: string; position: number }): number {
+  return b.at.localeCompare(a.at) || b.twin.localeCompare(a.twin) || b.position - a.position;
+}
+
 export class WorldDoors {
   private readonly queues = new Map<string, Promise<unknown>>();
   token: string; readToken: string;
   constructor(readonly name: string, readonly worldRoot: string, readonly configRef: string, readonly served: string, private readonly host: DoorHost, token: string, readToken: string) { this.token = token; this.readToken = readToken; }
   /** New tokens; a request presenting the old ones is refused from the next call on. */
-  retoken(token: string, readToken: string): void { this.token = token; this.readToken = readToken; }
+  // new tokens end everything the old ones reached: every session and every named key
+  retoken(token: string, readToken: string): void { this.token = token; this.readToken = readToken; this.endSessions(); this.keepKeys([]); this.signIns.clear(); }
+
+  /** 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. */
+  private sessionsPath(): string { return sessionsFile(this.worldRoot); }
+  private held: Record<string, HeldSession> | null = null;
+  private sessions(): Record<string, HeldSession> {
+    if (this.held === null) { try { this.held = JSON.parse(getActiveWorldStore().read(this.sessionsPath()) ?? '{}') as Record<string, HeldSession>; } catch { this.held = {}; } }
+    return this.held;
+  }
+  private keepSessions(all: Record<string, HeldSession>): void {
+    const now = Date.now();
+    // the expired go, and at most the 100 newest are kept (a browser that keeps losing its cookie cannot grow it)
+    this.held = Object.fromEntries(Object.entries(all).filter(([, s]) => s.until > now).sort(([, a], [, b]) => b.until - a.until).slice(0, 100));
+    getActiveWorldStore().write(this.sessionsPath(), `${JSON.stringify(this.held)}\n`, { secret: true });
+  }
+  /** A new session of `scope`: its id, the cookie's value. A token's lasts 30 days; a person's from a pass, `who`,
+   *  lasts as long as the pass's platform says (twelve hours), so a person removed there loses it within the day. */
+  private openSession(scope: 'read' | 'write', person?: { who: string; ttlMs: number; issuer: string; sub?: string }, key?: { id: string; until: number }): string {
+    const id = mintToken('ses_');
+    let held = this.sessions();
+    // a person holds at most five sessions here: passes (anyone's with one) never crowd out everyone else's
+    if (person) { const theirs = Object.entries(held).filter(([, x]) => x.who === person.who).sort(([, a], [, b]) => b.until - a.until); if (theirs.length >= 5) { const drop = new Set(theirs.slice(4).map(([k]) => k)); held = Object.fromEntries(Object.entries(held).filter(([k]) => !drop.has(k))); } }
+    const until = Math.min(Date.now() + (person?.ttlMs ?? 30 * 86_400_000), key?.until ?? Infinity);
+    this.keepSessions({ ...held, [id]: { scope, until, ...(person ? { who: person.who, issuer: person.issuer, ...(person.sub ? { sub: person.sub } : {}) } : {}), ...(key ? { key: key.id } : {}) } });
+    return id;
+  }
+  /** NAMED KEYS: what an app or a script holds (docs/contributing/architecture.md, "The hosted product"), each named
+   *  when made, shown once, kept only as its hash, and revoked alone; the World's two tokens stay its first keys. */
+  private heldKeys: HeldKey[] | null = null;
+  private keys(): HeldKey[] {
+    if (this.heldKeys === null) { try { this.heldKeys = JSON.parse(getActiveWorldStore().read(keysFile(this.worldRoot)) ?? '[]') as HeldKey[]; } catch { this.heldKeys = []; } }
+    return this.heldKeys;
+  }
+  private keepKeys(all: HeldKey[]): void { this.heldKeys = all; getActiveWorldStore().write(keysFile(this.worldRoot), `${JSON.stringify(all)}\n`, { secret: true }); }
+  /** When a key was last used, to the minute (a key in constant use is not a write per request). */
+  private touchKey(key: HeldKey): void {
+    const now = new Date(); if (key.lastUsedAt && now.getTime() - Date.parse(key.lastUsedAt) < 60_000) return;
+    this.keepKeys(this.keys().map((k) => (k.id === key.id ? { ...k, lastUsedAt: now.toISOString() } : k)));
+  }
+  /** `GET|POST /-/<world>/keys`, `DELETE /-/<world>/keys/<id>`, `DELETE /-/<world>/keys?person=<sub>`: named keys are
+   *  managed with write access by the World's token or a person's session, never by a key (a key cannot make a key
+   *  that outlives it). Each records who made it and whom it is for; the token may give one an end and a person, and
+   *  revoke every key made by or for a person (their leaving the org). */
+  /** The person a key is for: whom it was made for, else the person whose session made it. */
+  private keyPerson(k: HeldKey): string | undefined { return k.for ?? (k.createdBy?.via === 'session' ? k.createdBy.sub : undefined); }
+  /** Revoke the keys `pick` names, and what they reach: the branches whose parent key goes, and the branches (with their
+   *  keys) a revoked key made. Answers the revoked keys' ids. */
+  private async revokeKeys(pick: (k: HeldKey) => boolean): Promise<string[]> {
+    const gone = this.keys().filter(pick);
+    const ids = new Set(gone.map((k) => k.id));
+    const also = this.keys().filter((k) => !ids.has(k.id) && k.madeWith !== undefined && ids.has(k.madeWith)); // branches a revoked key made
+    for (const k of also) ids.add(k.id);
+    this.keepKeys(this.keys().filter((k) => !ids.has(k.id)));
+    // the keys are gone whatever a removal answers; a branch that stays is said, not hidden (its parent key no longer opens this World)
+    for (const k of [...gone, ...also]) if (k.branch) await this.host.branches?.remove(k.branch).catch((error: unknown) => { console.error(`${this.served}: branch ${k.branch} stays after its key was revoked: ${error instanceof Error ? error.message : String(error)}`); return false; });
+    return [...ids];
+  }
+  private async keysDoor(request: Request, id: string | undefined, scope: 'read' | 'write', via: 'token' | 'key' | 'session' | null, session?: string): Promise<Response> {
+    if (scope !== 'write') return Response.json({ error: 'keys are managed with write access' }, { status: 403 });
+    if (via === 'key') return Response.json({ error: 'a key manages no keys: use the World\'s token, or its page' }, { status: 403 });
+    const now = Date.now();
+    const live = (): HeldKey[] => this.keys().filter((k) => !k.expiresAt || Date.parse(k.expiresAt) > now);
+    const view = (k: HeldKey) => ({ id: k.id, name: k.name, scope: k.scope, createdAt: k.createdAt, lastUsedAt: k.lastUsedAt ?? null, expiresAt: k.expiresAt ?? null, for: k.for ?? null, person: this.keyPerson(k) ?? null, branch: k.branch ?? null, createdBy: k.createdBy?.via === 'session' ? (k.createdBy.who ?? k.createdBy.sub ?? 'a person') : k.createdBy?.via === 'key' ? `the key ${k.createdBy.keyId}` : k.createdBy ? 'the World\'s token' : null });
+    const person = (k: HeldKey): string | undefined => this.keyPerson(k);
+    if (!id && request.method === 'GET') return Response.json({ keys: live().map(view) });
+    if (!id && request.method === 'POST') {
+      const body = (await request.json().catch(() => ({}))) as { name?: unknown; scope?: unknown; for?: unknown; expiresAt?: unknown; replace?: unknown };
+      const name = typeof body.name === 'string' ? body.name.trim().slice(0, 80) : '';
+      if (!name) return Response.json({ error: 'a key needs a name: what holds it (an app, a CI job, a laptop)' }, { status: 400 });
+      const keyScope = body.scope === 'read' ? 'read' : 'write';
+      // a session a platform's pass opened makes no keys: a key outlives the session, and a script on this origin (a
+      // stored page) could make one in the person's name. Keys for a platform's Worlds are made on the platform.
+      const opener = via === 'session' && session ? this.sessions()[session] : undefined;
+      if (opener?.issuer) return Response.json({ error: 'a key for this World is made on the platform it was opened from, not from a browser session here', platform: opener.issuer }, { status: 403 });
+      // `for`, `replace` and an end are the token's to give (a platform making a command's key for a person)
+      if ((body.for !== undefined || body.replace !== undefined) && via !== 'token') return Response.json({ error: 'for and replace are the World token\'s' }, { status: 403 });
+      const forWhom = typeof body.for === 'string' && /^[A-Za-z0-9:._@-]{1,160}$/.test(body.for) ? body.for : undefined;
+      let expiresAt: string | undefined;
+      if (body.expiresAt !== undefined) { const t = typeof body.expiresAt === 'string' ? Date.parse(body.expiresAt) : NaN; if (!(t > now)) return Response.json({ error: 'expiresAt: an ISO instant in the future' }, { status: 400 }); expiresAt = new Date(t).toISOString(); }
+      // replace: the key of the same name for the same person goes (one command, one key: asking again does not pile them up)
+      let kept = live(); if (body.replace === true) kept = kept.filter((k) => !(k.name === name && person(k) === forWhom));
+      if (kept.length >= 200) return Response.json({ error: 'this World holds 200 keys: revoke some first' }, { status: 409 });
+      const opened = via === 'session' && session ? this.sessions()[session] : undefined;
+      const createdBy: HeldKey['createdBy'] = via === 'session' ? { via: 'session', ...(opened?.sub ? { sub: opened.sub } : {}), ...(opened?.who ? { who: opened.who } : {}), ...(opened?.issuer ? { issuer: opened.issuer } : {}) } : { via: 'token' };
+      const key = mintToken('tok_k_');
+      const held: HeldKey = { id: mintToken('key_').slice(0, 20), name, scope: keyScope, hash: keyHash(key), createdAt: new Date(now).toISOString(), createdBy, ...(forWhom ? { for: forWhom } : {}), ...(expiresAt ? { expiresAt } : {}) };
+      this.keepKeys([...kept, held]);
+      return Response.json({ ...view(held), key }, { status: 201, headers: { 'cache-control': 'no-store' } });
+    }
+    if (!id && request.method === 'DELETE') {
+      // every key made by or for a person: their leaving the org ends what they hold here (the token's act)
+      const who = new URL(request.url).searchParams.get('person');
+      if (via !== 'token' || !who) return Response.json({ error: 'DELETE /keys?person=<subject>, with the World\'s token' }, { status: via !== 'token' ? 403 : 400 });
+      // their keys, the parent keys of the branches they made, and those branches
+      return Response.json({ revoked: await this.revokeKeys((k) => person(k) === who) });
+    }
+    if (id && request.method === 'DELETE') {
+      const found = this.keys().find((k) => k.id === id);
+      if (!found) return Response.json({ error: `no key ${id}` }, { status: 404 });
+      // a branch's parent key takes its branch with it, and a key takes the branches it made
+      await this.revokeKeys((k) => k.id === id);
+      return Response.json({ revoked: id, name: found.name });
+    }
+    return Response.json({ error: 'keys: GET or POST /keys, DELETE /keys/<id> or /keys?person=<subject>' }, { status: 405 });
+  }
+  /** Passes this World has already spent: each opens one session. */
+  private readonly spent = spentPasses();
+  /** A PASS opens a session: a person a trusted platform signed a pass for, into this World, at its own origin, asked
+   *  from its own page (the console reads the pass from its address's fragment and posts it here). */
+  /** The org its host records as this World's owner (`<state>/owner`, written at its making or its claim), or null. */
+  private recordedOwner(): string | null { try { const o = getActiveWorldStore().read(join(this.worldRoot, stateDirName(), 'owner'))?.trim() ?? ''; return /^[A-Za-z0-9_-]{1,80}$/.test(o) ? o : null; } catch { return null; } }
+  private async passSession(request: Request, url: URL, pass: string): Promise<Response> {
+    const issuers = this.host.passIssuers?.() ?? [];
+    if (issuers.length === 0) return Response.json({ error: `${this.served} trusts no platform's passes` }, { status: 401 });
+    const own = this.host.browserOrigin?.() ?? null;
+    // a pass opens only a World with an origin of its own: on a shared origin every other World's pages would reach the
+    // session it opened
+    if (own === null) return Response.json({ error: `${this.served} has no origin of its own, where a pass could open it` }, { status: 409 });
+    if (this.sessionCookieName(url) === null) return Response.json({ error: `${this.served}'s browser session lives at its own origin`, origin: own }, { status: 409 });
+    const checked = await verifyPass(pass, { issuers, world: this.served, audience: own, seen: this.spent });
+    if (!checked.ok) return Response.json({ error: `that pass does not open ${this.served}: ${checked.reason}` }, { status: 401 });
+    // a World its host records an owner for opens only for that org: a platform that holds the World under another org
+    // (a slug taken again, a claim gone wrong) cannot open it
+    const owner = this.recordedOwner();
+    if (owner !== null && checked.claims.org !== owner) return Response.json({ error: `that pass does not open ${this.served}: it names another org than the one that owns it` }, { status: 401 });
+    const who = checked.claims.email ?? checked.claims.name ?? checked.claims.sub;
+    const cookie = this.sessionCookie(url, this.openSession(checked.claims.scope, { who, ttlMs: 12 * 3_600_000, issuer: checked.claims.iss, sub: checked.claims.sub }))!;
+    // `issuer`: the platform the pass came from, verified, which the page offers as the way back (never an address from
+    // its own URL, which anyone can write)
+    return Response.json({ world: this.served, scope: checked.claims.scope, who, issuer: checked.claims.iss, origin: own }, { headers: { 'set-cookie': cookie } });
+  }
+  /** A named key that still opens this World: not revoked, not expired. */
+  private liveKey(id: string): boolean { const k = this.keys().find((x) => x.id === id); return !!k && (!k.expiresAt || Date.parse(k.expiresAt) > Date.now()); }
+  /** The named key a request presents, with the end of its life. */
+  private presentedKey(request: Request): { id: string; until: number } | undefined {
+    const token = this.credential(request).token; const k = token ? this.keys().find((x) => sameSecret(keyHash(token), x.hash)) : undefined;
+    return k ? { id: k.id, until: k.expiresAt ? Date.parse(k.expiresAt) : Infinity } : undefined;
+  }
+  private endSession(id: string | null): void { if (id && id in this.sessions()) { const { [id]: _ended, ...rest } = this.sessions(); this.keepSessions(rest); } }
+  private endSessions(): void { if (Object.keys(this.sessions()).length) this.keepSessions({}); }
   /** The world's twins, by vendor, once booted. */
   twins(): string[] { return Object.keys(this.up().services); }
   private up(): WorldLayout { return this.host.layout(); }
@@ -228,29 +501,74 @@ export class WorldDoors {
   /** The world's token, presented the way the app's SDK presents a credential: the world's own header,
    *  the injector's `x-twins-key` (a zero-edit app keeps its SDK's own Authorization), `Bearer <token>`,
    *  GitHub's `token <token>`, or the password half of `Basic` (Jira's email:token). */
-  private scope(request: Request): 'write' | 'read' | null { return this.match(request)?.scope ?? null; }
-  /** The World token the request presented, in whichever form, and the scope it opens. */
-  private match(request: Request): { scope: 'write' | 'read'; token: string; fromSession: boolean } | null {
-    const authorization = request.headers.get('authorization') ?? '';
-    const bearer = /^(?:Bearer|token)\s+(\S+)$/i.exec(authorization)?.[1];
-    const basic = /^Basic\s+(\S+)$/i.exec(authorization)?.[1];
-    const basicSecret = basic ? (() => { try { const text = Buffer.from(basic, 'base64').toString('utf8'); const i = text.indexOf(':'); return i >= 0 ? text.slice(i + 1) : text; } catch { return undefined; } })() : undefined;
-    // a browser holding a session for this World (POST …/session): what a mirror page reads the wire with
-    const cookie = /(?:^|;\s*)volter_world=([^;]+)/.exec(request.headers.get('cookie') ?? '')?.[1];
-    // every form presented is a candidate: a mirror page sends the VENDOR's bearer (the X token its
-    // sign-in holds) beside the World's session cookie, and the cookie is what opens the World
-    const headed = [request.headers.get(TOKEN_HEADER), request.headers.get(TWINS_KEY_HEADER), bearer, basicSecret];
-    const session = cookie ? decodeURIComponent(cookie) : null;
-    for (const [scope, token] of [['write', this.token], ['read', this.readToken]] as const) {
-      if (headed.includes(token)) return { scope, token, fromSession: false };
-      if (session === token) return { scope, token, fromSession: true };
-    }
-    return null;
+  private scope(request: Request): 'write' | 'read' | null { return this.credential(request).scope; }
+  /** The request's scope, whether it came by a token the caller presented or by a browser's session
+   *  (the cookie `POST …/session` set), and the token that opened it. Every form presented is a
+   *  candidate: a mirror page sends the VENDOR's bearer (the token its sign-in holds) beside the World's
+   *  session cookie, and the cookie is what opens the World. With a browser origin of its own
+   *  (`browserOrigin`), a World honours its session only on that origin: a session cookie on any other
+   *  (a host's shared origin, path-addressed) opens nothing. */
+  /** What this World issued, for world-access to decide a grant against: its two tokens, its named keys, its sessions. */
+  private issued(): WorldCredentials {
+    return {
+      world: this.served, token: this.token, readToken: this.readToken,
+      // a NAMED KEY (an app's or a script's, revoked alone): known by its hash; it acts as the token of its scope
+      key: (p) => { if (!p.startsWith('tok_k_')) return null; const held = this.keys().find((k) => sameSecret(keyHash(p), k.hash)); if (!held || (held.expiresAt && Date.parse(held.expiresAt) <= Date.now())) return null; this.touchKey(held); return held.scope; },
+      // a session a shared link's read key opened ends with that key: revoked or expired, it opens nothing
+      session: (id) => { const opened = Object.hasOwn(this.sessions(), id) ? this.sessions()[id]! : null; return opened && opened.until > Date.now() && (!opened.key || this.liveKey(opened.key)) ? opened : null; },
+    };
+  }
+  private credential(request: Request): { scope: 'write' | 'read' | null; via: 'token' | 'key' | 'session' | null; token: string | null; /** the session's id, when the session opened it */ session?: string; /** who the session is */ who?: string } {
+    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 "; "
+    const cookie = name === null ? undefined : new RegExp(`(?:^|;\\s*)${name}=([^;]+)`).exec(request.headers.get('cookie') ?? '')?.[1];
+    // the decision is world-access's (the architecture's "access is decided in one place"); this World says what it issued
+    const grant = grantOf(presented, cookie ? decodeURIComponent(cookie) : null, this.issued());
+    if (!grant) return { scope: null, via: presented.length ? 'token' : null, token: null };
+    // `token` is only ever the secret the caller presented (a named key is answered as itself): the World's own tokens
+    // never reach a key's or a session's holder
+    if (grant.via === 'session') return { scope: grant.scope, via: 'session', token: null, session: grant.session!, ...(grant.who ? { who: grant.who } : {}) };
+    return { scope: grant.scope, via: grant.via === 'key' ? 'key' : 'token', token: grant.presented ?? null };
+  }
+  /** The session cookie's name where `url` reached this World, or null where a session opens nothing:
+   *  on the World's own origin a host-only cookie (`__Host-` over https); without an origin of its own,
+   *  the path-scoped cookie a shared origin has always carried. */
+  private sessionCookieName(url: URL): string | null {
+    const own = this.host.browserOrigin?.() ?? null;
+    if (own === null) return 'volter_world';
+    if (url.host !== new URL(own).host) return null;
+    return url.protocol === 'https:' ? '__Host-volter_world' : 'volter_world';
+  }
+  /** The session cookie for `url`, set to `value`: host-only over the whole origin on the World's own
+   *  origin (a `__Host-` cookie must be), scoped to the World's paths on a shared one. Null where a
+   *  session opens nothing (another World's origin). */
+  private sessionCookie(url: URL, value: string, extra = ''): string | null {
+    const name = this.sessionCookieName(url);
+    if (name === null) return null;
+    const own = this.host.browserOrigin?.() ?? null;
+    return `${name}=${value}; Path=${own ? '/' : `/${this.served}/`}; HttpOnly; SameSite=Strict${url.protocol === 'https:' ? '; Secure' : ''}${extra}`;
+  }
+  /** A browser's session opens the World only to the World's own pages: a request the session cookie carries must
+   *  say `Sec-Fetch-Site: same-origin` (a browser sets it; a page cannot), or be a read the person navigated to
+   *  (`none`: a typed or bookmarked address). Another page of the same site (a sibling World's origin shares its
+   *  suffix) is refused its reads too, so a twin that echoes the caller's Origin with credentials cannot hand one
+   *  World's data to another World's page; a request with no header fails closed. Null when it may pass. */
+  private crossOriginSession(request: Request, via: 'token' | 'key' | 'session' | null): Response | null {
+    if (via !== 'session') return null;
+    const site = request.headers.get('sec-fetch-site');
+    if (site === 'same-origin') return null;
+    const read = request.method === 'GET' || request.method === 'HEAD';
+    if (read && site === 'none') return null;
+    return Response.json({ error: read
+      ? "a World's browser session reads only for the World's own pages or an address typed in (Sec-Fetch-Site: same-origin or none)"
+      : "a World's browser session writes only from the World's own pages (Sec-Fetch-Site: same-origin)" }, { status: 403 });
   }
   /** Open one connection on a byte-stream door for the holder of the World's (write) token; null when
    *  the token is not the World's or the World has no such stream. */
   openStream(token: string, id: string, sink: TwinStreamSink, peer: string): TwinStreamConnection | null {
-    if (token !== this.token || !this.host.openStream || !(id in (this.host.streams?.() ?? {}))) return null;
+    // the World's write token or a write key opens a stream (world-access decides, as for every door)
+    if (grantOf([token], null, this.issued())?.scope !== 'write' || !this.host.openStream || !(id in (this.host.streams?.() ?? {}))) return null;
     return this.host.openStream(id, sink, peer);
   }
   private serialized<T>(key: string, fn: () => Promise<T>): Promise<T> {
@@ -276,8 +594,8 @@ export class WorldDoors {
       // place under this World, and the token the injector carries to them — the presented one
       if (url.pathname === `${prefix}.well-known/volter-world` && request.method === 'GET') {
         // the manifest hands its caller the token it presented; a session's token is HttpOnly, never echoed to script
-        const matched = this.match(request);
-        if (matched === null || matched.fromSession) return Response.json({ error: 'token required' }, { status: 401 });
+        const matched = this.credential(request);
+        if (matched.token === null || matched.via === 'session') return Response.json({ error: 'token required' }, { status: 401 });
         const presented = matched.token;
         const vendors = Object.fromEntries(Object.keys(this.up().services).map((v) => [v, `${url.origin}/${this.served}/${v}`]));
         // a stream is reached through the attacher's loopback bridge (@volter/world-core/stream-bridge):
@@ -288,35 +606,127 @@ export class WorldDoors {
         const endpoints = Object.fromEntries(Object.keys(vendors).flatMap((v) => { const name = APP_READ_ENDPOINT_ENV[v]?.injectEnv; return name ? [[name, vendors[v]!]] : []; }));
         return Response.json({ name: this.served, vendors, ca: null, proxy: null, env: { ...endpoints, VOLTER_TWINS_KEY: presented }, ...(Object.keys(streams).length ? { streams } : {}) });
       }
-      if (url.pathname.startsWith(prefix)) return await this.wire(request, url, url.pathname.slice(prefix.length));
+      if (url.pathname.startsWith(prefix)) {
+        const rest = url.pathname.slice(prefix.length);
+        const mirror = /^([a-z0-9_-]+)\/mirror(?:\/(.*))?$/.exec(rest);
+        if (mirror) return await this.mirror(request, url, mirror[1]!, mirror[2] ?? '');
+        return await this.wire(request, url, rest);
+      }
       return Response.json({ error: `not this world: serving /${this.served}/` }, { status: 404 });
     } catch (error) {
       return Response.json({ error: error instanceof Error ? error.message : String(error) }, { status: 500 });
     }
   }
 
+  /** THE MIRROR MOUNT: `/<served>/<vendor>/mirror/` and `…/mirror/assets/<file>`, keyless and GET only —
+   *  the pack's own shell and client. The shell's <base> is the twin's place in this World, so the
+   *  mirror reads and writes the World's wire with the browser's session (`POST …/session`); any
+   *  other path under mirror/ is one of the mirror's own routes (a reloaded deep link) and gets the
+   *  shell. A link is not a twin and has no mirror. */
+  private async mirror(request: Request, url: URL, vendor: string, rest: string, /** answered at the twin's place (the vendor's site) */ atSite = false): Promise<Response> {
+    if (request.method !== 'GET' && request.method !== 'HEAD') return Response.json({ error: 'the mirror mount serves the shell and its assets only' }, { status: 405, headers: { allow: 'GET, HEAD' } });
+    const isAsset = MIRROR_ASSET.test(rest);
+    if (rest.startsWith('assets/') && !isAsset) return Response.json({ error: 'no such asset' }, { status: 404 });
+    if (!this.up().services[vendor] || !this.host.mirror) return Response.json({ error: `no mirror for ${vendor} in ${this.served}` }, { status: 404 });
+    const file = await this.host.mirror(vendor, isAsset ? rest : 'index.html');
+    if (!file || file.status !== 200) return Response.json({ error: isAsset ? 'no such asset' : `no mirror for ${vendor} in ${this.served}` }, { status: 404 });
+    if (isAsset) return file;
+    // the shell's own address is the vendor's site at the twin's place (wire, above): a page opened here goes there, so
+    // a mirror that routes by its path sees its home, not `mirror/` (the browser keeps any `#/…` route)
+    if (rest === '' && !atSite && ['document', 'iframe'].includes(request.headers.get('sec-fetch-dest') ?? '')) return new Response(null, { status: 302, headers: { location: `/${this.served}/${vendor}/${url.search}` } });
+    // the shell's <base> is the twin's place under this World (its reads go to the World's wire), its assets stay under
+    // mirror/, and its `#/…` links keep working under that base (world-core mirror-shell.ts)
+    let html = mirrorShellUnder(await file.text(), `/${this.served}/${vendor}/`);
+    // SIGNED IN AS the config says (`signIn.as`): the screens are handed the account and a credential the World minted
+    // for it, before they start. Only to a request that may write this World (a read link signs no one in, and minting
+    // is a write), on the vendor's site (never the keyless mount), at the World's own origin: a shared origin's other
+    // pages, and a rebound name reaching this port, are not this World's pages. Checked here, whoever called.
+    const own = this.host.browserOrigin?.() ?? null;
+    const signs = atSite && own !== null && url.host === new URL(own).host && this.credential(request).scope === 'write';
+    const as = signs ? loadWorldConfig(this.configRef, this.worldRoot).config.services.find((s) => s.id === vendor)?.signIn?.as : undefined;
+    const given = as ? await this.signedIn(vendor, as, url.origin) : null;
+    if (given) {
+      // data, never markup: every character that could end the script or the line is escaped, and the replacement is a
+      // function, so no `$&` or `$'` in a value is expanded into the page
+      const data = JSON.stringify({ account: given.account, token: given.token }).replace(/[<>&\u2028\u2029]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+      html = html.replace(/<script/i, (tag) => `<script>window.__VOLTER_SIGN_IN__=${data};</script>${tag}`);
+    }
+    // where the console lives on the World's own origin, only that origin frames the World's pages (no clickjacking);
+    // a page that carries a credential is never stored, and differs by who asked
+    return new Response(html, { status: 200, headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': given ? 'no-store, private' : 'no-cache', vary: given ? 'Sec-Fetch-Dest, Cookie, Authorization' : 'Sec-Fetch-Dest', ...(own ? { 'content-security-policy': "frame-ancestors 'self'" } : {}) } });
+  }
+
+  /** A vendor's screens' sign-in (`signIn.as`), once per account every twelve hours while this World is served (rotating the
+   *  tokens forgets them): the pack finds the account and mints its credential through the twin's own doors; a failure
+   *  is not kept, so the next page asks again. An account or credential that is not plain printable text is refused. */
+  private readonly signIns = new Map<string, Promise<{ account: string; token: string } | null>>();
+  private readonly signInAt = new Map<string, number>();
+  private signedIn(vendor: string, as: string, origin: string): Promise<{ account: string; token: string } | null> {
+    const key = `${vendor}\0${as}`;
+    if (Date.now() - (this.signInAt.get(key) ?? 0) > 43_200_000) this.signIns.delete(key);
+    let held = this.signIns.get(key);
+    if (!held) {
+      this.signInAt.set(key, Date.now());
+      const twin = this.host.twinFetch(vendor);
+      held = !twin || !this.host.mirrorSignIn ? Promise.resolve(null) : this.host.mirrorSignIn(vendor, as, {
+        root: this.controlRoot(vendor),
+        twin: (path, init) => twin(new Request(`${origin}${path.startsWith('/') ? path : `/${path}`}`, init)),
+      }).then((given) => (given && /^[\x21-\x7e]{1,512}$/.test(given.token) && /^[^\x00-\x1f\x7f]{1,256}$/.test(given.account) ? given : null)).catch(() => null);
+      this.signIns.set(key, held);
+      void held.then((given) => { if (!given) this.signIns.delete(key); });
+    }
+    return held;
+  }
+
+  /** Whether a twin enforces a read-scope request itself (its manifest names `requestScopes: ['read']`):
+   *  only then may the read token reach it with anything but GET or HEAD. Asked once per twin. */
+  private readonly readEnforced = new Map<string, { enforced: boolean; at: number }>();
+  private async enforcesRead(vendor: string, twin: (request: Request) => Promise<Response>, origin: string): Promise<boolean> {
+    // asked again after a minute: a twin that was down, or a pack swapped under a running World, is seen
+    const known = this.readEnforced.get(vendor);
+    if (known !== undefined && Date.now() - known.at < 60_000) return known.enforced;
+    let enforced = false;
+    try {
+      const answer = await twin(new Request(`${origin}/twin`, { headers: { [READ_ONLY_HEADER]: '1' } }));
+      if (answer.ok) {
+        const scopes = ((await answer.json()) as { requestScopes?: unknown }).requestScopes;
+        enforced = Array.isArray(scopes) && scopes.includes('read');
+      }
+    } catch { enforced = false; }
+    this.readEnforced.set(vendor, { enforced, at: Date.now() });
+    return enforced;
+  }
+
   /** The vendor wire: `/<org>/<world>/<vendor>/<rest>` → the twin's own URL. */
   private async wire(request: Request, url: URL, rest: string): Promise<Response> {
     const [vendor, ...tail] = rest.split('/');
-    if (tail[0] === 'mirror') return await this.mirror(request, vendor!, tail.slice(1).join('/'));
-    const scope = this.scope(request);
+    const { scope, via } = this.credential(request);
     const manifestAsk = request.method === 'GET' && tail.join('/').replace(/\/+$/, '') === 'twin';
     if (scope === null && !manifestAsk) return Response.json({ error: 'token required' }, { status: 401 });
-    if (scope === 'read' && request.method !== 'GET' && request.method !== 'HEAD') return Response.json({ error: 'the read token opens only reads' }, { status: 403 });
+    const foreign = this.crossOriginSession(request, via);
+    if (foreign) return foreign;
+    const reads = request.method === 'GET' || request.method === 'HEAD';
     // 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). Stateless, no log.
-    // a person's browser landing on a twin's root (a mirror that moved to a `#/…` route by assigning
-    // location, which resolves against the twin's <base>) is sent to the mirror; the browser keeps the hash
-    if (request.method === 'GET' && tail.join('/') === '' && request.headers.get('sec-fetch-dest') === 'document' && this.up().services[vendor!] && (await this.hasMirror(vendor!))) {
-      return new Response(null, { status: 302, headers: { location: `/${this.served}/${vendor}/mirror/` } });
-    }
+    // 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!);
-    if (link) return await this.forward(request, url, tail.join('/'), vendor!, link.origin);
+    if (link) {
+      if (scope === 'read' && !reads) return Response.json({ error: 'the read token opens only reads' }, { status: 403 });
+      return await this.forward(request, url, tail.join('/'), vendor!, link.origin);
+    }
     const twin = this.host.twinFetch(vendor!);
     if (!twin) return Response.json({ error: `no twin "${vendor}" in ${this.served}` }, { status: 404 });
+    // THE READ SCOPE: the twin is told the request is read-only and refuses the caller's writes itself
+    // (a Slack read over POST passes, a post is refused); a twin that cannot enforce that gets reads only
+    const enforced = scope === 'read' && (await this.enforcesRead(vendor!, twin, url.origin));
+    if (scope === 'read' && !reads && !enforced) return Response.json({ error: 'the read token opens only reads' }, { status: 403 });
     const headers = new Headers(request.headers); headers.delete(TOKEN_HEADER); headers.delete(TWINS_KEY_HEADER); headers.delete('host');
+    // at a twin that enforces the read scope, every request of the read token is marked read-only (a GET
+    // that would write for its caller is refused too); at any other, its GET passes as it always has
+    if (enforced) headers.set(READ_ONLY_HEADER, '1');
     // the browser's World session is the World's credential, never the twin's (a tunnel would hand it on)
-    const cookies = (headers.get('cookie') ?? '').split(/;\s*/).filter((c) => c && !c.startsWith('volter_world='));
+    const cookies = (headers.get('cookie') ?? '').split(/;\s*/).filter((c) => c && !/^(?:__Host-)?volter_world=/.test(c));
     if (cookies.length) headers.set('cookie', cookies.join('; ')); else headers.delete('cookie');
     // the twin is mounted under this World's path: live URLs it mints must carry it (twinPublicBase)
     headers.set(TWIN_PREFIX_HEADER, `/${this.served}/${vendor}`);
@@ -325,38 +735,40 @@ export class WorldDoors {
     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
     if (answer.status === 101) return answer;
+    // THE VENDOR'S SITE: a page the twin does not serve as a page itself (it serves an OAuth screen, a redirect) is the
+    // vendor's own screens, the mirror, answered at that very address: the twin's place is the vendor's site, and a
+    // mirror's routes are real URLs, reloadable and linkable, as a dev server falls back to its app for unknown pages
+    const servedAsPage = (answer.status >= 300 && answer.status < 400) || (answer.status < 300 && (answer.headers.get('content-type') ?? '').includes('text/html'));
+    // a credential reached it: the manifest's keyless GET never becomes a page (and never signs anyone in). A resource
+    // the twin answers (a JSON link, a stored file, a PDF: 2xx) opened in a tab is that resource, as the vendor's own
+    // address would be; an address it refuses or has nothing at (a browser brings no vendor token), and the site's
+    // home, are the screens
+    const unanswered = answer.status >= 400 || tail.join('/') === '';
+    if (page && scope !== null && !servedAsPage && unanswered && (await this.host.hasMirror?.(vendor!))) {
+      await answer.body?.cancel().catch(() => undefined);
+      return await this.mirror(request, url, vendor!, '', true);
+    }
     // staleness is a fact on the wire: a twin with a root says when the vendor was last observed
     const out = new Headers(answer.headers);
     const observedAt = this.observedAt(vendor!);
     if (observedAt) out.set('x-volter-observed-at', observedAt);
+    // served on the World's origin beside its session: a twin's bytes are never sniffed into a script or a page,
+    // and a twin cannot set (fix, shadow or clear) the World's own session cookie
+    out.set('x-content-type-options', 'nosniff');
+    // a stored file opened as a page (an uploaded SVG, an XML document) runs nothing on the World's origin: sandboxed, it is
+    // an origin of its own with no scripts, so it can neither read the session's World nor make it a key
+    const type = (answer.headers.get('content-type') ?? '').toLowerCase();
+    if (page && answer.status < 300 && /^(image\/svg\+xml|application\/xhtml\+xml|text\/xml|application\/xml)\b/.test(type)) out.set('content-security-policy', 'sandbox');
+    // a page and an API call to one address are answered differently (the vendor's site): 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))) {
+      out.delete('set-cookie');
+      for (const c of setCookies) if (!/^\s*(?:__Host-)?volter_world=/i.test(c)) out.append('set-cookie', c);
+    }
     return new Response(answer.body, { status: answer.status, headers: out });
   }
 
-  /** Whether the twin's pack ships a mirror (its vendor's UI over this World's state). */
-  private async hasMirror(vendor: string): Promise<boolean> {
-    const mod = await packMirrorExports(vendor, this.worldRoot).catch(() => null);
-    return !!mod && Object.keys(mod).some((n) => /^\w+MirrorHtml$/.test(n)) && Object.keys(mod).some((n) => /^build\w+MirrorClient$/.test(n));
-  }
-
-  /** THE MIRROR MOUNT, as the hosted World serves it (apps/cloud supervisor.ts): `/<org>/<world>/<vendor>/mirror/`
-   *  and `…/mirror/assets/*`, keyless, GET only — the pack's own shell and bundle. The shell's <base> is the
-   *  twin's place under this World, so its reads go to the keyed wire with the browser's World session. */
-  private async mirror(request: Request, vendor: string, rest: string): Promise<Response> {
-    if (request.method !== 'GET') return Response.json({ error: 'the mirror mount serves the shell and its assets only' }, { status: 404 });
-    const isAsset = /^assets\/[A-Za-z0-9._-]+$/.test(rest);
-    if (rest.startsWith('assets/') && !isAsset) return Response.json({ error: 'no such asset' }, { status: 404 });
-    if (!this.up().services[vendor]) return Response.json({ error: 'no mirror for this twin' }, { status: 404 });
-    const mod = await packMirrorExports(vendor, this.worldRoot);
-    const pick = (re: RegExp) => { const k = mod && Object.keys(mod).find((n) => re.test(n) && typeof mod[n] === 'function'); return k ? (mod![k] as () => string | Promise<string>) : undefined; };
-    const html = pick(/^\w+MirrorHtml$/); const client = pick(/^build\w+MirrorClient$/); const styles = pick(/^\w+MirrorStyles$/);
-    if (!html || !client) return Response.json({ error: 'no mirror for this twin' }, { status: 404 });
-    if (rest === 'assets/app.js') return new Response(await client(), { headers: { 'content-type': 'text/javascript; charset=utf-8' } });
-    if (rest === 'assets/styles.css' && styles) return new Response(await styles(), { headers: { 'content-type': 'text/css; charset=utf-8' } });
-    if (isAsset) return Response.json({ error: 'no such asset' }, { status: 404 });
-    const shell = mirrorShellUnder(await html(), `/${this.served}/${vendor}/`);
-    return new Response(shell, { headers: { 'content-type': 'text/html; charset=utf-8' } });
-  }
-
   private linksPath(): string { return join(this.worldRoot, stateDirName(), 'links.json'); }
   /** The World's links: name → the vendor origin it forwards to. */
   links(): Record<string, { origin: string }> {
@@ -419,28 +831,79 @@ export class WorldDoors {
     // 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
     // next port, is same-site)
-    const crossSite = request.headers.get('sec-fetch-site') === 'cross-site';
+    // With an origin of its own, a World's session is opened and ended only from its own pages (or an address typed
+    // in): a sibling World is the same site and must not end or re-issue it (a logout CSRF). A request that says
+    // nothing (not a browser) is left to the token the form carries.
+    const site = request.headers.get('sec-fetch-site');
+    const crossSite = this.host.browserOrigin?.() ? site !== null && site !== 'same-origin' && site !== 'none' : site === 'cross-site';
     if (sessionPath === 'session' && request.method === 'POST' && (request.headers.get('content-type') ?? '').startsWith('application/x-www-form-urlencoded')) {
       if (crossSite) return new Response('A session is opened from this host\'s own pages.', { status: 403, headers: { 'content-type': 'text/plain; charset=utf-8' } });
       const form = new URLSearchParams(await request.text());
       const token = form.get('token') ?? '';
-      if (token !== this.token && token !== this.readToken) return new Response('That token does not open this World.', { status: 401, headers: { 'content-type': 'text/plain; charset=utf-8' } });
+      // the token or a named key typed into the form, decided by world-access as every door's is
+      const found = token ? grantOf([token], null, this.issued()) : null;
+      // the World's token opens a session here; a named key is an app's and opens none, except a READ key (a shared
+      // read-only link), whose session is bound to it as the header door's is: read only, ended with the key
+      const granted = found?.via === 'token' || (found?.via === 'key' && found.scope === 'read') ? found : null;
+      if (!granted) return new Response('That token does not open this World.', { status: 401, headers: { 'content-type': 'text/plain; charset=utf-8' } });
+      if (this.sessionCookieName(url) === null) return new Response(`${this.served}'s browser session lives at its own origin: ${this.host.browserOrigin?.() ?? ''}`, { status: 409, headers: { 'content-type': 'text/plain; charset=utf-8' } });
+      const bound = granted.via === 'key' ? ((k) => (k ? { id: k.id, until: k.expiresAt ? Date.parse(k.expiresAt) : Infinity } : undefined))(this.keys().find((x) => sameSecret(keyHash(token), x.hash))) : undefined;
+      if (granted.via === 'key' && !bound) return new Response('That token does not open this World.', { status: 401, headers: { 'content-type': 'text/plain; charset=utf-8' } });
+      const cookie = this.sessionCookie(url, this.openSession(granted.scope, undefined, bound));
+      // a World with an origin of its own keeps its session there: asked elsewhere, it says where
+      if (cookie === null) return new Response(`${this.served}'s browser session lives at its own origin: ${this.host.browserOrigin?.() ?? ''}`, { status: 409, headers: { 'content-type': 'text/plain; charset=utf-8' } });
       const next = form.get('next') ?? '';
       // the path the browser would land on, normalized (%2e%2e resolves), and only inside this World
       const landing = (() => { try { const at = new URL(next, url.origin); return at.origin === url.origin ? at.pathname : ''; } catch { return ''; } })();
       const to = next.startsWith('/') && !next.startsWith('//') && !/[\\\s]/.test(next) && landing.startsWith(`/${this.served}/`) ? landing : `/${this.served}/`;
-      const secure = url.protocol === 'https:' ? '; Secure' : '';
-      return new Response(null, { status: 303, headers: { location: to, 'set-cookie': `volter_world=${encodeURIComponent(token)}; Path=/${this.served}/; HttpOnly; SameSite=Strict${secure}` } });
+      return new Response(null, { status: 303, headers: { location: to, 'set-cookie': cookie } });
     }
     if (((sessionPath === 'session' && request.method === 'DELETE') || (sessionPath === 'session/end' && request.method === 'POST')) && !crossSite) {
-      const secure = url.protocol === 'https:' ? '; Secure' : '';
-      return new Response(JSON.stringify({ world: this.served, ended: true }), { status: 200, headers: { 'content-type': 'application/json', 'set-cookie': `volter_world=; Path=/${this.served}/; HttpOnly; SameSite=Strict; Max-Age=0${secure}` } });
+      this.endSession(this.credential(request).session ?? null);
+      const cookie = this.sessionCookie(url, '', '; Max-Age=0');
+      return new Response(JSON.stringify({ world: this.served, ended: true }), { status: 200, headers: { 'content-type': 'application/json', ...(cookie ? { 'set-cookie': cookie } : {}) } });
+    }
+    // a person arriving from a platform with a pass: from this World's own page only (the pass is in its fragment)
+    const pass = request.headers.get('x-volter-pass');
+    if (pass !== null && sessionPath === 'session' && request.method === 'POST') {
+      if (crossSite || (this.host.browserOrigin?.() && site !== 'same-origin')) return Response.json({ error: "a pass opens a session from this World's own page" }, { status: 403 });
+      return await this.passSession(request, url, pass);
     }
-    const scope = this.scope(request);
+    const { scope, via } = this.credential(request);
+    // a local World's own page asking for its session with nothing to show: it is the person at this machine
+    if (scope === null && sessionPath === 'session' && request.method === 'POST' && this.localPage(request, url)) return this.localSession(url);
     if (scope === null) return Response.json({ error: 'token required' }, { status: 401 });
-    if (scope === 'read' && request.method !== 'GET') return Response.json({ error: 'the read token opens only reads' }, { status: 403 });
     const parts = path.split('/').filter(Boolean);
     const [kind, name, verb] = parts;
+    // a browser session is opened by either token: the read token's is how a view-only link opens a mirror
+    // 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
+    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),
+    // except a READ key, which is how a shared read-only link opens the World's pages: its session reads only, makes no
+    // keys, and ends when the key is revoked or expires
+    if (kind === 'session' && !name && request.method === 'POST' && via === 'key' && scope !== 'read') return Response.json({ error: 'a key opens no browser session: open the World with its token, or from the platform' }, { status: 403 });
+    if (kind === 'session' && !name && (request.method === 'POST' || request.method === 'DELETE')) return this.session(request, url, scope, via === 'key' ? this.presentedKey(request) : undefined);
+    if (kind === 'keys') return this.keysDoor(request, name, scope, via, this.credential(request).session);
+    if (scope === 'read' && request.method !== 'GET') return Response.json({ error: 'the read token opens only reads' }, { status: 403 });
+
+    if (kind === 'clock') return await this.clockDoor(request, name);
+    if (kind === 'branches') return await this.branchesDoor(request, url, parts.slice(1), via);
+    // each twin's history cut at an instant: where a branch "as of" that instant starts
+    if (kind === 'history' && !name && request.method === 'GET') {
+      const instant = url.searchParams.get('at') ?? '';
+      if (Number.isNaN(Date.parse(instant))) return Response.json({ error: 'history?at=<ISO-8601 instant>' }, { status: 400 });
+      const views: Record<string, HistoryReference> = {};
+      withAncestryLock(() => { for (const vendor of Object.keys(this.up().services)) views[vendor] = historyAtInstant(this.stateOf(vendor), instant, this.controlRoot(vendor)); });
+      return Response.json({ world: this.served, at: new Date(Date.parse(instant)).toISOString(), views });
+    }
+    if (kind === 'map' && !name && request.method === 'GET') return Response.json(await this.map());
+    if (kind === 'timeline' && !name && request.method === 'GET') return this.timeline(url);
+    if (kind === 'diff' && !name && request.method === 'GET') {
+      const delta = diffWorld(this.name, { root: this.worldRoot });
+      return Response.json({ world: this.served, base: { id: delta.base.id, at: delta.base.createdAt ?? null }, changes: delta.actions.map((a) => ({ twin: a.service, entry: a.action })) });
+    }
 
     if (kind === 'log' && name && request.method === 'GET') {
       const state = this.stateOf(name);
@@ -480,13 +943,6 @@ export class WorldDoors {
       if (!body.as) return Response.json({ error: 'approve: { as, note? }' }, { status: 400 });
       return Response.json(approveWorldChangeset(name, { root: this.worldRoot, world: this.name, principal: body.as, ...(body.note ? { note: body.note } : {}) }));
     }
-    // a browser session for this World: the presented token as an HttpOnly cookie scoped to the World's
-    // paths, so a page served under it (a twin's mirror) reads the wire as the token's holder
-    if (kind === 'session' && !name && request.method === 'POST') {
-      const presented = this.match(request)!.token;
-      const secure = url.protocol === 'https:' ? '; Secure' : '';
-      return new Response(JSON.stringify({ world: this.served, scope }), { status: 200, headers: { 'content-type': 'application/json', 'set-cookie': `volter_world=${encodeURIComponent(presented)}; Path=/${this.served}/; HttpOnly; SameSite=Strict${secure}` } });
-    }
     if (kind === 'links' && !name && request.method === 'GET') return Response.json({ links: this.links() });
     if (kind === 'links' && name && request.method === 'PUT') {
       if (!/^[a-z0-9][a-z0-9_-]{0,63}$/.test(name) || this.up().services[name]) return Response.json({ error: 'a link is named [a-z0-9_-] and is not a twin of this World' }, { status: 400 });
@@ -525,11 +981,12 @@ export class WorldDoors {
       const key = (): string => { const t = store.read(tokenPath)?.trim(); if (!t) throw new Error(`${this.served} has no origin — PUT /-/${this.served}/origin { url, token }`); return t; };
       if (!name && request.method === 'GET') return Response.json({ origin: statusWorld(this.name, this.worldRoot).origin ?? null });
       if (!name && request.method === 'PUT') {
-        const body = (await request.json()) as { url?: string; token?: string };
+        const body = (await request.json()) as { url?: string; token?: string; views?: Record<string, HistoryReference> };
         const at = /^(https?:\/\/[^/]+)\/([a-z0-9][a-z0-9_-]*\/[a-z0-9][a-z0-9_-]*)\/?$/i.exec(body.url ?? '');
-        if (!at || !body.token) return Response.json({ error: 'PUT origin: { url: "https://<host>/<org>/<world>", token }' }, { status: 400 });
+        if (!at || !body.token) return Response.json({ error: 'PUT origin: { url: "https://<host>/<org>/<world>", token, views? }' }, { status: 400 });
         store.write(tokenPath, `${body.token}\n`, { secret: true });
-        const fetched = await this.serialized('push', () => fetchFromOrigin(this.name, { root: this.worldRoot, url: at[1]!, namespace: at[2]!, key: body.token!, full: true }));
+        // `views` (the origin's history door answers them) clones each twin's history as of a cut
+        const fetched = await this.serialized('push', () => fetchFromOrigin(this.name, { root: this.worldRoot, url: at[1]!, namespace: at[2]!, key: body.token!, full: true, ...(body.views ? { views: body.views } : {}) }));
         return Response.json({ origin: fetched.origin, appended: fetched.appended });
       }
       if (name === 'pull' && request.method === 'POST') {
@@ -584,6 +1041,13 @@ export class WorldDoors {
     }
     if (kind === 'push' && request.method === 'POST') return await this.serialized('push', () => this.push(request));
     if (kind === 'deploy' && request.method === 'POST') {
+      // a deploy acts on the real vendors: a browser's session deploys only what the request itself names, so no link,
+      // page or request built from a path (a console route, a crafted URL) deploys by being opened. A caller presenting
+      // the token is the operator's own tool, as before.
+      if (via === 'session') {
+        const asked = (await request.json().catch(() => null)) as { confirm?: unknown } | null;
+        if (asked?.confirm !== (name ?? this.served)) return Response.json({ error: `a browser deploys only what it names: POST { "confirm": "${name ?? this.served}" }` }, { status: 400 });
+      }
       const outcomes = await this.serialized('push', () => deployWorld(this.name, { root: this.worldRoot, instance: this.up(), ...(name ? { changeset: name } : {}) }));
       return Response.json({ deployed: outcomes.map((o) => ({ twin: o.service, pushed: o.report.pushed, ...(o.report.refused ? { refused: o.report.refused } : {}), ...(o.report.failed ? { failed: o.report.failed } : {}) })) });
     }
@@ -655,7 +1119,7 @@ export class WorldDoors {
         const marker = getActiveWorldStore().read(join(this.controlRoot(name), stateDirName(), 'world', name, 'refresh.json'));
         let refresh: unknown = null; try { if (marker !== null) refresh = JSON.parse(marker); } catch { refresh = null; }
         const last = [...parentEntries(state, this.controlRoot(name))].reverse().find((e) => e.landsId && e.receipt);
-        return Response.json({ twin: name, state, protocol: this.up().services[name]?.protocol ?? null, root: root ?? null, credential: sealedCredentialInfo(this.worldRoot, name), refresh, position: wholeLog(state, this.controlRoot(name)).length, lastReceipt: last?.receipt ?? null, mirror: await this.hasMirror(name) });
+        return Response.json({ twin: name, state, protocol: this.up().services[name]?.protocol ?? null, mirror: Boolean(await this.host.hasMirror?.(name)), root: root ?? null, credential: sealedCredentialInfo(this.worldRoot, name), refresh, position: wholeLog(state, this.controlRoot(name)).length, lastReceipt: last?.receipt ?? null });
       }
       if (verb === 'refresh' && request.method === 'POST') {
         const root = rootForControlRoot(this.controlRoot(name), name);
@@ -666,6 +1130,219 @@ export class WorldDoors {
     return Response.json({ error: `no such door: ${request.method} /-/${this.served}/${path}` }, { status: 404 });
   }
 
+  /** A browser session for this World: the presented token as an HttpOnly cookie scoped to the World's
+   *  paths, so a page served under it (a twin's mirror) reads the wire as the token's holder, in the
+   *  token's scope. */
+  /** THE LOCAL SESSION: a World served on this machine's loopback never asks the person at it for a token. Any
+   *  website can send requests to 127.0.0.1, so what stands in for the token is proof the request is this World's own
+   *  page, as Vite and Jupyter check their dev servers: the Host is a loopback name (a rebound DNS name is not, so DNS
+   *  rebinding fails), the browser's Origin is exactly this origin (another site's page cannot claim it, so CSRF
+   *  fails), and the fetch says it is same-origin. A process on this machine can claim all three: a local World
+   *  trusts this machine's user, as a local dev server does. The session is the write token's. A World with no origin
+   *  of its own (a shared origin, where every World's pages are one origin) is not trusted so: its page asks for a
+   *  token. */
+  private localPage(request: Request, url: URL): boolean {
+    // only where the World has an origin of its own: on a shared origin every World's pages (and each twin's own
+    // HTML) are the same origin, and none may be handed another's session
+    if (!this.host.localTrust?.() || !this.host.browserOrigin?.()) return false;
+    const name = url.hostname.replace(/^\[|\]$/g, '').toLowerCase();
+    const loopback = name === 'localhost' || name.endsWith('.localhost') || name === '127.0.0.1' || name === '::1';
+    const site = request.headers.get('sec-fetch-site');
+    // a request that does not say it is same-origin fails closed (every browser this serves says it)
+    return loopback && request.headers.get('origin') === url.origin && site === 'same-origin';
+  }
+  private localSession(url: URL): Response {
+    const own = this.host.browserOrigin?.() ?? null;
+    if (this.sessionCookieName(url) === null) return Response.json({ error: `${this.served}'s browser session lives at its own origin`, origin: own }, { status: 409 });
+    return Response.json({ world: this.served, scope: 'write', local: true, ...(own ? { origin: own } : {}) }, { headers: { 'set-cookie': this.sessionCookie(url, this.openSession('write'))! } });
+  }
+
+  private session(request: Request, url: URL, scope: 'read' | 'write', key?: { id: string; until: number }): Response {
+    const own = this.host.browserOrigin?.() ?? null;
+    // a World with an origin of its own keeps its session there: asked elsewhere, it says where
+    if (this.sessionCookieName(url) === null) return Response.json({ error: `${this.served}'s browser session lives at its own origin`, origin: own }, { status: 409 });
+    const held = this.credential(request).session ?? null;
+    if (request.method === 'DELETE') { this.endSession(held); return Response.json({ world: this.served, ended: true }, { headers: { 'set-cookie': this.sessionCookie(url, '', '; Max-Age=0')! } }); }
+    const cookie = this.sessionCookie(url, held ?? this.openSession(scope, undefined, key))!;
+    const who = held ? this.sessions()[held]?.who : undefined; const issuer = held ? this.sessions()[held]?.issuer : undefined;
+    // `local`: this page is the local World's own (localPage), so the console offers no sign-in or sign-out
+    return Response.json({ world: this.served, scope, ...(who ? { who } : {}), ...(issuer ? { issuer } : {}), ...(own ? { origin: own } : {}), ...(this.localPage(request, url) ? { local: true } : {}) }, { headers: { 'set-cookie': cookie } });
+  }
+
+  /** THE CLOCK: the frozen instant every twin stamps from, kept in the World's store. It moves only
+   *  forward once the World has entries (a twin's catch-up stamps each move at its due time, so a
+   *  clock set back would put new entries before old ones); the past is reached by branching. */
+  private async clockDoor(request: Request, verb: string | undefined): Promise<Response> {
+    const path = this.host.clockPath?.();
+    if (!path) return Response.json({ error: 'this host keeps no World clock' }, { status: 404 });
+    const store = getActiveWorldStore();
+    const held = store.exists(path) ? (store.read(path) ?? '').trim() : '';
+    const current = held && !Number.isNaN(Date.parse(held)) ? { at: new Date(Date.parse(held)).toISOString(), frozen: true } : { at: new Date().toISOString(), frozen: false };
+    if (!verb && request.method === 'GET') return Response.json(current);
+    const set = (at: number): Response => {
+      // the floor: the later of the frozen instant and the newest entry any twin holds (a push may
+      // land entries past the clock)
+      const newest = this.newestEntry(); const frozenAt = current.frozen ? Date.parse(current.at) : null;
+      const floor = frozenAt === null ? newest : newest === null ? frozenAt : Math.max(frozenAt, newest);
+      if (floor !== null && at < floor) return Response.json({ error: `the clock moves only forward: ${new Date(at).toISOString()} is before ${new Date(floor).toISOString()} (branch to go back)` }, { status: 409 });
+      store.writeAtomic(path, `${new Date(at).toISOString()}\n`);
+      return Response.json({ at: new Date(at).toISOString(), frozen: true });
+    };
+    if (!verb && request.method === 'PUT') {
+      const body = (await request.json().catch(() => null)) as { at?: unknown } | null;
+      const at = typeof body?.at === 'string' ? Date.parse(body.at) : Number.NaN;
+      if (Number.isNaN(at)) return Response.json({ error: 'clock: { at: <ISO-8601 instant> }' }, { status: 400 });
+      return set(at);
+    }
+    if (verb === 'advance' && request.method === 'POST') {
+      const body = (await request.json().catch(() => null)) as { by?: unknown } | null;
+      const m = typeof body?.by === 'string' ? SPAN.exec(body.by.trim()) : null;
+      if (!m) return Response.json({ error: 'advance: { by: "<N>(s|m|h|d)" }' }, { status: 400 });
+      if (!current.frozen) return Response.json({ error: 'the clock is not set: set it first (advancing the wall clock would freeze time as a side effect)' }, { status: 409 });
+      const target = Date.parse(current.at) + Number(m[1]) * SPAN_MS[m[2] as keyof typeof SPAN_MS];
+      if (!Number.isFinite(target) || target > Date.parse('9999-12-31T23:59:59Z')) return Response.json({ error: 'advance: past the last instant a clock can hold' }, { status: 400 });
+      return set(target);
+    }
+    return Response.json({ error: `no such door: ${request.method} clock${verb ? `/${verb}` : ''}` }, { status: 404 });
+  }
+
+  /** THE BRANCHES DOORS: list (read), make one as of an instant, remove one (write). The host makes
+   *  and removes them; a host that makes none answers 404, and a view offers no "as of". */
+  private async branchesDoor(request: Request, url: URL, rest: string[], via: 'token' | 'key' | 'session' | null): Promise<Response> {
+    const branches = this.host.branches;
+    if (!branches) return Response.json({ error: `this host makes no branches of ${this.served}` }, { status: 404 });
+    if (rest.length === 0 && request.method === 'GET') return Response.json({ world: this.served, branches: await branches.list() });
+    if (rest.length === 0 && request.method === 'POST') {
+      const body = (await request.json().catch(() => null)) as { at?: { instant?: unknown }; ttl?: unknown; live?: unknown; label?: unknown } | null;
+      const instant = body?.at?.instant;
+      if (instant !== undefined && (typeof instant !== 'string' || Number.isNaN(Date.parse(instant)))) return Response.json({ error: 'branches: { at?: { instant: <ISO-8601> }, ttl?: <seconds>, live?: true, label?: <name> }' }, { status: 400 });
+      if (body?.label !== undefined && (typeof body.label !== 'string' || !/^[a-z0-9][a-z0-9-]{0,23}$/.test(body.label))) return Response.json({ error: 'label: lowercase letters, digits and dashes, at most 24 (it names the branch)' }, { status: 400 });
+      if (body?.live !== undefined && (body.live !== true || instant !== undefined)) return Response.json({ error: 'live: true, and only for a branch as of now (a branch at an instant keeps that instant)' }, { status: 400 });
+      let ttl = body?.ttl === undefined || body.ttl === null ? null : Number(body.ttl);
+      if (ttl !== null && (!Number.isInteger(ttl) || ttl < 60 || ttl > 30 * 86_400)) return Response.json({ error: 'ttl: whole seconds, 60 to 2592000' }, { status: 400 });
+      // WHO MAKES IT, and for how long: the World's token as it asks; a key or a person's session only for a while, and
+      // never past its own end (a branch outlives neither the key nor the session that made it)
+      const now = Date.now();
+      const cred = this.credential(request);
+      const maker = via === 'key' && cred.token ? this.keys().find((k) => sameSecret(keyHash(cred.token!), k.hash)) : undefined;
+      const opened = via === 'session' && cred.session ? this.sessions()[cred.session] : undefined;
+      if (via !== 'token') {
+        const until = maker ? (maker.expiresAt ? Date.parse(maker.expiresAt) : Infinity) : opened ? opened.until : now;
+        const most = Math.floor(Math.min(7 * 86_400_000, until - now) / 1000);
+        if (ttl === null) return Response.json({ error: 'ttl: a branch made with a key or a browser session says how long it lives (seconds, at most 7 days and the key\'s or session\'s own end)' }, { status: 400 });
+        if (most < 60) return Response.json({ error: 'this key or session ends too soon to make a branch' }, { status: 403 });
+        ttl = Math.min(ttl, most);
+      }
+      const person = maker ? this.keyPerson(maker) : opened?.sub;
+      const createdBy: HeldKey['createdBy'] = maker ? { via: 'key', keyId: maker.id } : opened ? { via: 'session', ...(opened.sub ? { sub: opened.sub } : {}), ...(opened.who ? { who: opened.who } : {}), ...(opened.issuer ? { issuer: opened.issuer } : {}) } : { via: 'token' };
+      // the branch reaches this World with a key of its own, never this World's token: made for the same person, ending
+      // with the branch, so whatever ends the person's keys here (their leaving, a revoke, new tokens) ends its reach
+      const parentKey = mintToken('tok_k_');
+      const keyId = mintToken('key_').slice(0, 20);
+      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);
+        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)
+        // `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 });
+      } 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 });
+      }
+    }
+    if (rest.length === 2 && request.method === 'DELETE') {
+      const name = rest.join('/');
+      if (!(await branches.remove(name))) return Response.json({ error: `${name} is not a branch of ${this.served}` }, { status: 404 });
+      this.keepKeys(this.keys().filter((k) => k.branch !== name)); // its key here goes with it
+      return Response.json({ removed: name });
+    }
+    return Response.json({ error: `no such door: ${request.method} branches${rest.length ? `/${rest.join('/')}` : ''}` }, { status: 404 });
+  }
+
+  /** The newest entry's instant across the World's twins (ms), or null when it has none. */
+  private newestEntry(): number | null {
+    let newest: number | null = null;
+    for (const vendor of Object.keys(this.up().services)) {
+      for (const e of wholeLog(this.stateOf(vendor), this.controlRoot(vendor))) {
+        const t = Date.parse(e.occurredAt);
+        if (!Number.isNaN(t) && (newest === null || t > newest)) newest = t;
+      }
+    }
+    return newest;
+  }
+
+  /** THE MAP: every twin and what it holds, by resource type, and whether it has a mirror. */
+  private async map(): Promise<unknown> {
+    const twins: unknown[] = [];
+    for (const vendor of Object.keys(this.up().services)) {
+      const state = this.stateOf(vendor); const controlRoot = this.controlRoot(vendor);
+      const counts = new Map<string, number>();
+      for (const r of readTree(state, controlRoot)) if (r.deleted !== true) counts.set(r.type, (counts.get(r.type) ?? 0) + 1);
+      twins.push({
+        twin: vendor, position: wholeLog(state, controlRoot).length,
+        mirror: Boolean(await this.host.hasMirror?.(vendor)),
+        root: rootForControlRoot(controlRoot, vendor) ?? null,
+        resources: [...counts].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).map(([type, count]) => ({ type, count })),
+      });
+    }
+    return { world: this.served, twins };
+  }
+
+  /** THE TIMELINE: the entries of every twin's log merged, newest first, by each entry's instant, then
+   *  twin, then position. The World keeps no order across twins finer than its clock, and this claims
+   *  none. `before` is the cursor the previous page answered; `twin` and `trace` narrow it. */
+  private timeline(url: URL): Response {
+    const limit = Math.min(Number(url.searchParams.get('limit') ?? '100'), 500);
+    if (!Number.isInteger(limit) || limit < 1) return Response.json({ error: 'limit: 1-500' }, { status: 400 });
+    const onlyTwin = url.searchParams.get('twin'); const onlyTrace = url.searchParams.get('trace');
+    let before: { at: string; twin: string; position: number } | null = null;
+    const cursor = url.searchParams.get('before');
+    if (cursor) {
+      try {
+        const [at, twin, position] = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8')) as [string, string, number];
+        if (typeof at !== 'string' || typeof twin !== 'string' || !Number.isInteger(position)) throw new Error('shape');
+        before = { at, twin, position };
+      } catch { return Response.json({ error: 'before: not a cursor this door answered' }, { status: 400 }); }
+    }
+    const rows = this.timelineRows().filter((r) => (!onlyTwin || r.twin === onlyTwin) && (!onlyTrace || traceIdOf(r.entry.traceparent) === onlyTrace));
+    const key = (r: TimelineRow) => ({ at: r.entry.occurredAt, twin: r.twin, position: r.position });
+    const page = rows.filter((r) => before === null || newerFirst(before, key(r)) < 0).slice(0, limit + 1);
+    const more = page.length > limit; const shown = page.slice(0, limit);
+    const last = shown[shown.length - 1];
+    const next = more && last ? Buffer.from(JSON.stringify([last.entry.occurredAt, last.twin, last.position])).toString('base64url') : null;
+    return Response.json({ world: this.served, entries: shown, next });
+  }
+
+  /** Each twin's timeline rows, kept until its logs change: a poll of an unchanged World reads no log
+   *  (a twin is read again only when the size or time of its parent log, branch log or branch record
+   *  moved), and the merged order is sorted again only when a twin was. */
+  private readonly timelineByTwin = new Map<string, { fingerprint: string; rows: TimelineRow[] }>();
+  private timelineMerged: { fingerprint: string; rows: TimelineRow[] } | null = null;
+  private timelineRows(): TimelineRow[] {
+    const store = getActiveWorldStore();
+    const prints: string[] = [];
+    for (const vendor of Object.keys(this.up().services)) {
+      const state = this.stateOf(vendor); const controlRoot = this.controlRoot(vendor);
+      const fingerprint = [parentLogPath(state, controlRoot), branchLogPath(state, controlRoot), branchMetaPath(state, controlRoot)]
+        .map((p) => { const s = store.stat(p); return s ? `${s.size}:${s.mtimeMs}` : '-'; }).join('|');
+      prints.push(`${vendor}=${fingerprint}`);
+      if (this.timelineByTwin.get(vendor)?.fingerprint === fingerprint) continue;
+      this.timelineByTwin.set(vendor, { fingerprint, rows: wholeLog(state, controlRoot).map((entry, i) => ({ twin: vendor, position: i + 1, entry })) });
+    }
+    const all = prints.join(',');
+    if (this.timelineMerged?.fingerprint !== all) {
+      const key = (r: TimelineRow) => ({ at: r.entry.occurredAt, twin: r.twin, position: r.position });
+      const rows = Object.keys(this.up().services).flatMap((v) => this.timelineByTwin.get(v)?.rows ?? []);
+      this.timelineMerged = { fingerprint: all, rows: rows.sort((a, b) => newerFirst(key(a), key(b))) };
+    }
+    return this.timelineMerged.rows;
+  }
+
   /** PUSH: see `landChangeset` — the door hands the body to it. */
   private async push(request: Request): Promise<Response> {
     const body = (await request.json()) as Changeset | { changeset: Changeset; expect?: Record<string, HistoryReference> };