@volter/world-core 3.0.18 → 3.0.20

package/src/derived-core.ts

@@ -16,7 +16,7 @@ import { worldNow } from './world-clock.ts';
 import { worldEnvValue } from './world-env.ts';
 import { openSessions, socketWrite, type SocketDecl, type SocketSession } from './sockets.ts';
 import { MACHINE_POOL, poolFor, type MachinePool } from './machines.ts';
-import { askApplication, deliverEvents, deliverToApplication, type ApplicationAnswer, type DeliveryAnswer, type EventRender, type EventScheme, type EventsDecl, type EventValues } from './events.ts';
+import { askApplication, deliverEvents, deliverToApplication, type ApplicationAnswer, type ApplicationStandIn, type DeliveryAnswer, type EventRender, type EventScheme, type EventsDecl, type EventValues } from './events.ts';
 import type { RateBudgetDeclaration } from './rateBudget.ts';
 import { handlerCrypto, hmac, lettersFrom, sha256, uuidFrom, type HandlerCrypto } from './signing.ts';
 import { hashFieldValue } from './hash.ts';
@@ -214,7 +214,9 @@ export type LaneRoute = {
 export type LanesDecl = { cors?: CorsDecl; routes: ReadonlyArray<LaneRoute>; default?: string };
 /** The manifest of a vendor whose every API is a lane (Cloudflare's API v4 and R2, AWS's services): no API of its own,
  *  only what the vendor's front says — its discovery facts, its lanes and its descriptor. */
-export type VendorManifest = { vendor: string; discovery?: DerivedManifest['discovery']; lanes: LanesDecl; descriptor: Omit<PackDescriptor, 'vendor'>; ingest?: IngestDecl; rateBudget?: RateBudgetDeclaration };
+export type VendorManifest = { vendor: string; discovery?: DerivedManifest['discovery']; lanes: LanesDecl; descriptor: Omit<PackDescriptor, 'vendor'>; ingest?: IngestDecl; rateBudget?: RateBudgetDeclaration;
+  /** the vendor has no vendor-backed half (architecture, "The descriptor"): packOf copies it, and derives no state system */
+  vendorBacked?: DerivedManifest['vendorBacked'] };
 
 /** `code` as the vendor writes it: a string, or a number (Discord's JSON error codes are integers) */
 export type ErrorSpec = { status: number; message: string; code?: string | number; param?: string; kind?: string };
@@ -235,6 +237,15 @@ export type ScreenDecl = {
   demand: string;
   status: 'done' | 'todo';
   controls?: string[];
+  /** wherever this screen would answer (its host, a World's place, its path alone), a request the pack's API names for
+   *  its method is the operation's, not this screen's: a site whose pages draw while its forms and links act on
+   *  operations the spec writes at the same paths (Hacker News's /login page posts to POST /login; its front page at `/`
+   *  would otherwise take GET /vote) (architecture, "Screens") */
+  yieldsToApi?: true;
+  /** a content screen that takes a form at a World's place (`<base>/@<host>/…`), beside GET and HEAD: the methods it
+   *  takes, with its demand (an upload bucket a page posts a lease's form to: Reddit's S3 hosts) (architecture, "A page
+   *  at a World's place") */
+  takes?: ReadonlyArray<'POST'>;
   /** the vendor's documentation of the round trip or the screen */
   source: string;
 };
@@ -524,6 +535,14 @@ export function flagOf(m: Pick<DerivedManifest, 'booleans'>, value: unknown): bo
  *  text: a field the operation's spec types as a number or a boolean (`scalars`, by bracket path, written by
  *  world-tooling's formScalarsOf) is read as one when its text is that literal; every other field stays the text sent
  *  (`metadata[order]=007`, `name=2024`). */
+/** A field set as the object's own, whatever its name (`__proto__`, `constructor` and `prototype` are data a caller
+ *  may name: Stripe's metadata keys are the caller's), never through what the object inherits. */
+export function ownField(node: Record<string, unknown> | unknown[], key: string, value: unknown): void {
+  Object.defineProperty(node, key, { value, writable: true, enumerable: true, configurable: true });
+}
+/** A field the object holds as its own, never one it inherits (`constructor` is every object's). */
+const ownValue = (node: Record<string, unknown> | unknown[], key: string): unknown => (Object.hasOwn(node, key) ? (node as Record<string, unknown>)[key] : undefined);
+
 export function parseBracketForm(text: string, scalars?: Readonly<Record<string, string | undefined>>): Record<string, unknown> {
   const out: Record<string, unknown> = {};
   for (const [rawKey, raw] of new URLSearchParams(text)) {
@@ -533,18 +552,26 @@ export function parseBracketForm(text: string, scalars?: Readonly<Record<string,
       : kind === 'integer' ? (/^-?\d+$/.test(raw) ? Number(raw) : raw)
       : kind === 'number' ? (/^-?\d+(\.\d+)?$/.test(raw) ? Number(raw) : raw)
       : raw;
-    let node: any = out;
-    parts.forEach((key, i) => {
+    // every field is the node's own, read and written as such: a key naming an object's machinery (`__proto__[x]`,
+    // `constructor[prototype][x]`) is a field of that name, never a walk into what every object inherits
+    let node: Record<string, unknown> | unknown[] = out;
+    for (const [i, key] of parts.entries()) {
+      // an array holds its items by index (`a[]`, `a[0]`): a named key under one (`a[]=1&a[length]=-1`) has nowhere to
+      // go, as a key under text has none (`a=1&a[b]=2`): the first shape stands
+      if (Array.isArray(node) && key !== '' && !/^\d+$/.test(key)) break;
       if (i === parts.length - 1) {
         if (key === '') {
           if (Array.isArray(node)) node.push(value);
-        } else node[key] = value;
-        return;
+        } else ownField(node, key, value);
+        break;
       }
       const next = parts[i + 1]!;
-      if (node[key] === undefined) node[key] = next === '' || /^\d+$/.test(next) ? [] : {};
-      node = node[key];
-    });
+      if (key === '') break;
+      let child = ownValue(node, key);
+      if (child === undefined) { child = next === '' || /^\d+$/.test(next) ? [] : {}; ownField(node, key, child); }
+      if (child === null || typeof child !== 'object') break;
+      node = child as Record<string, unknown> | unknown[];
+    }
   }
   return out;
 }
@@ -580,26 +607,38 @@ export async function readParams(manifest: DerivedManifest, request: Request, op
     const parts = boundary === null ? [] : multipartParts(new Uint8Array(await request.arrayBuffer()), boundary);
     const out: Record<string, unknown> = { ...query };
     for (const part of parts) {
+      // each part a field of its own name, whatever the name (`__proto__` included: ownField)
       if (part.filename === null) {
-        out[part.name] = new TextDecoder().decode(part.body);
+        ownField(out, part.name, new TextDecoder().decode(part.body));
         continue;
       }
       const bytes = part.body;
       const parsed = { name: part.filename, type: part.type ?? '', size: bytes.byteLength, content: new TextDecoder().decode(bytes) };
-      out[part.name] = Object.defineProperty(parsed, 'bytes', { value: bytes, enumerable: false });
+      ownField(out, part.name, Object.defineProperty(parsed, 'bytes', { value: bytes, enumerable: false }));
     }
     return out;
   }
-  const text = await bodyTextOf(request);
-  if (!text) return query;
   // NDJSON (`application/x-ndjson`) is lines of JSON, not a JSON document: the handler reads its text
-  const isJson = type.includes('json') && !type.includes('ndjson');
+  const media = (type.split(';')[0] ?? '').trim().toLowerCase();
+  const isJson = media.includes('json') && !media.includes('ndjson');
+  // a form is a body labelled one (application/x-www-form-urlencoded); a body of any other type (an image, a video, an
+  // octet-stream PUT to an upload URL, a text/plain SQL statement, an NDJSON batch) is no form: its parameters are the
+  // query's, and the handler reads its text or bytes itself
+  const isForm = media === 'application/x-www-form-urlencoded';
   const asJson = isJson || manifest.body.json === 'always';
+  if (!isForm && !asJson) return query;
+  const text = await bodyTextOf(request);
+  if (!text) return query;
   // `json: 'always'` reads a body labelled otherwise as JSON (GitHub reads curl -d's); a body that is not JSON is read
-  // as the form it is labelled, never a crash (a sign-in page's own form, posted to the vendor's page)
+  // as a form only when it is labelled one (a sign-in page's own form, posted to the vendor's page), never a crash
   let body: unknown;
-  if (asJson) { try { body = JSON.parse(text); } catch { if (isJson) throw new SyntaxError('malformed JSON body'); body = parseBracketForm(text, scalars); } }
-  else body = parseBracketForm(text, scalars);
+  if (asJson) {
+    try { body = JSON.parse(text); } catch {
+      if (isJson) throw new SyntaxError('malformed JSON body');
+      if (!isForm) return query;
+      body = parseBracketForm(text, scalars);
+    }
+  } else body = parseBracketForm(text, scalars);
   // a body that is not an object (GitHub's set-labels takes a bare array) is the body, not fields
   return body && typeof body === 'object' && !Array.isArray(body) ? { ...query, ...(body as Record<string, unknown>) } : { ...query };
 }
@@ -743,6 +782,8 @@ export type CoreScope = {
   root?: string; clock?: () => string; database?: string; readOnly?: boolean;
   /** `semantics/tenant.ts`: the tenant the caller acts in (the manifest's `tenant`), or undefined for none */
   tenant?: (ctx: HandlerContext) => string | undefined | Promise<string | undefined>;
+  /** the application a walk stands in for: what the vendor asks it (`ctx.ask`) is answered by it (events.ts) */
+  application?: ApplicationStandIn;
 };
 
 function now(m: DerivedManifest, at: string): unknown {
@@ -979,6 +1020,9 @@ function recordedInput(m: DerivedManifest, call: DerivedCall, merged: Record<str
   return { operationId: id, ...asSent };
 }
 
+/** The scope each call is served in (serveCore, contextFor), for the contexts a write opens for its hooks. */
+const scopeOfCall = new WeakMap<DerivedCall, CoreScope>();
+
 async function writeDetailed(m: DerivedManifest, call: DerivedCall, resource: string, id: string, fields: Record<string, unknown>, operation: string, params: Record<string, unknown>, root: string | undefined, occurredAt: string): Promise<{ body: Record<string, unknown>; id: string; vendorData?: unknown }> {
   const withFiles = async (input: Record<string, unknown>): Promise<Record<string, unknown>> => { const files = input.operationId ? await keptFiles(m, call, root) : undefined; return files ? { ...input, files } : input; };
   const { resource: row, result } = await applyTwinWrite(
@@ -993,7 +1037,9 @@ async function writeDetailed(m: DerivedManifest, call: DerivedCall, resource: st
   );
   await keepCounts(m, call, resource, row as unknown as Record<string, unknown>, params, root, occurredAt);
   const body = view(m, resource, row);
-  const context = (): Promise<SemanticsContext> => contextFor(m, { ...call, request: call.request.clone() }, { ...(root !== undefined ? { root } : {}), clock: () => occurredAt });
+  // the write's own context for its hooks, in the scope the call was served in (a walk's application answers, a tenant,
+  // the managed database), at the write's moment
+  const context = (): Promise<SemanticsContext> => contextFor(m, { ...call, request: call.request.clone() }, { ...(scopeOfCall.get(call) ?? {}), ...(root !== undefined ? { root } : {}), clock: () => occurredAt });
   if (m.onWrite) await m.onWrite({ operation, storedType: storedType(m, resource), body, ...(root !== undefined ? { root } : {}), occurredAt, request: call.request, context });
   if (m.events) {
     const events = m.events;
@@ -1314,6 +1360,7 @@ export async function serveCore(m: DerivedManifest, call: DerivedCall, scope: Co
   const decl = resource ? m.resources[resource] : undefined;
   if (!resource || !decl) return { unmodeled: `no manifest entry for resource ${resource ?? '(none)'}` };
   call = adoptedPath(m, call, root);
+  scopeOfCall.set(call, scope);
   // the body is read from a copy, so the call's own request is still unread for the write hook's context
   const params = await boundaryParams(m, { ...call, request: call.request.clone() }, root);
   const idParam = subjectOf(m, resource, call);
@@ -1626,6 +1673,7 @@ export async function contextFor(m: DerivedManifest, call: DerivedCall, scope: C
   const root = scope.root;
   const asAsked = call;
   call = adoptedPath(m, call, root);
+  scopeOfCall.set(call, scope);
   const at = (scope.clock ?? worldNow)();
   // the guard's parse when it made one (taken once), else this context's own
   const parsed = takeParsedBody(call.request);
@@ -1658,7 +1706,7 @@ export async function contextFor(m: DerivedManifest, call: DerivedCall, scope: C
     publicBase: twinPublicBase(call.request),
     scenario: scenarioDecisionOf(call.request),
     deliver: (url, init) => deliverToApplication(url, init),
-    ask: (url, init, within) => askApplication(url, init, within),
+    ask: (url, init, within) => askApplication(url, init, within, scope.application),
     worldEnv: (name) => worldEnvValue(name),
     asVendor: (fn) => runAsVendorMove(fn),
     git: (name) => {

package/src/derived.ts

@@ -202,6 +202,9 @@ export type DerivedFetch = ((request: Request) => Promise<Response>) & {
   boards?: boolean;
   /** Whether a built screen of it takes a URL: a board frame it draws. */
   draws?(url: string): boolean;
+  /** The hosts its built content screens name: a vendor's lane router sends `<base>/@<host>/<path>` for one of them to
+   *  this fetch (pack-fetch.ts). */
+  contentHosts?: ReadonlyArray<string>;
 };
 
 /** A workspace screen a pack draws, as `GET /twin` lists it: its id and path (Viewing a World). */

package/src/events.ts

@@ -323,9 +323,26 @@ export async function deliverToApplication(url: string, init: RequestInit): Prom
  *  World let no request out to it or it could not be reached (`unreachable`), or it did not answer in time (`timeout`). */
 export type ApplicationAnswer = { status: number; body: string; missed?: 'timeout' | 'unreachable' };
 
+/** Who answers what the vendor asks the application (`ctx.ask`) before the World's application route does, given to a
+ *  pack's fetch (`PackFetchOptions.application`) and belonging to that fetch alone: an answer it gives is the
+ *  application's; `'unreachable'` is a question nobody answers (a walk's life, a sealed World, takes no other); undefined
+ *  is a question it does not take, which goes on as any other does: the application route, the World's egress rule, the
+ *  network. A walk's stand-in answers every question (its life's answers, else unreachable); a hosted World's router
+ *  answers only what it can answer truthfully (WorldDoors.askInWorld) and leaves the rest. */
+export type ApplicationStandIn = (url: string, init: RequestInit) => Promise<{ status: number; body: string } | 'unreachable' | undefined>;
+
 /** A message the vendor sends the application's server and decides by its answer (Stripe's real-time authorization
- *  request, answered within its window): over the same transport, waited on for at most `within` milliseconds. */
-export async function askApplication(url: string, init: RequestInit, within: number): Promise<ApplicationAnswer> {
+ *  request, answered within its window): over the same transport, waited on for at most `within` milliseconds, the
+ *  fetch's stand-in first when it was given one (its window the same). */
+export async function askApplication(url: string, init: RequestInit, within: number, standIn?: ApplicationStandIn): Promise<ApplicationAnswer> {
+  if (standIn) {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const late = new Promise<'late'>((done) => { timer = setTimeout(() => done('late'), within); });
+    const stood = await Promise.race([standIn(url, init), late]).finally(() => clearTimeout(timer));
+    if (stood === 'late') return { status: 0, body: '', missed: 'timeout' };
+    if (stood === 'unreachable') return { status: 0, body: '', missed: 'unreachable' };
+    if (stood !== undefined) return stood;
+  }
   const [{ appDestination, appFetch }, { worldEgressRefusal }] = await Promise.all([
     import('../app-route.cjs') as Promise<{ appDestination: (value: string) => unknown; appFetch: (url: string, init: RequestInit) => Promise<{ status: number; text(): Promise<string> }> }>,
     import('../network-policy.cjs') as Promise<{ worldEgressRefusal: (value: string) => unknown }>,

package/src/file-response.ts

@@ -22,9 +22,10 @@ export function fileResponse(path: string, init?: ResponseInit): Response {
 }
 
 /**
- * Stored bytes as a response, honouring a single `Range: bytes=` as RFC 9110 §14 has it: a range that does not parse, a
- * first-byte-pos past its last-byte-pos (`bytes=5-2`) included, is ignored and the whole body is a 200; a well-formed
- * range that starts past the end is a 416. `nosniff` stops a browser second-guessing the content type the vendor gave.
+ * Stored bytes as a response, honouring a single `Range: bytes=` as RFC 9110 §14 has it: every satisfiable range is a
+ * 206 with its Content-Range, `bytes=0-` (the whole body) included; a range that does not parse, a first-byte-pos past
+ * its last-byte-pos (`bytes=5-2`) included, is ignored and the whole body is a 200; a well-formed range that starts past
+ * the end (any range of an empty body) is a 416. `nosniff` stops a browser second-guessing the content type the vendor gave.
  */
 export function bytesResponse(request: Request, bytes: Uint8Array, contentType: string, cacheControl = 'public, max-age=604800, immutable'): Response {
   const total = bytes.length;
@@ -40,7 +41,9 @@ export function bytesResponse(request: Request, bytes: Uint8Array, contentType:
     }
     if (start >= total || (range[1] === '' && Number(range[2]) === 0)) return new Response(null, { status: 416, headers: { ...base, 'content-range': `bytes */${total}` } });
   }
-  const partial = start !== 0 || end !== total - 1;
+  // every satisfiable range is answered as one, the whole body's `bytes=0-` included: a media player (Safari's) reads a
+  // 206 with its Content-Range as the server taking ranges, and a 200 as one it cannot seek in
+  const partial = valid;
   const body = bytes.slice(start, end + 1);
   return new Response(request.method === 'HEAD' ? null : new Blob([body]), {
     status: partial ? 206 : 200,

package/src/pack-fetch.ts

@@ -6,7 +6,7 @@
 // one of them is answered over the contract's context, which the kernel opens: a pack opens none, reads the tree and
 // writes it only through one.
 import { ORIGINAL_PATH_HEADER } from './sigv4.ts';
-import { TWIN_PREFIX_HEADER } from './twin-fetch.ts';
+import { placedCookies, TWIN_PREFIX_HEADER } from './twin-fetch.ts';
 import { PREFIX_PARAMS_HEADER } from './derived.ts';
 import { withHeaders } from './with-headers.ts';
 import { authRefusal, bindSemantics, contextFor, LANE_HEADER, SCENARIO_DECISION_HEADER, coreFor, crossCutting, derivedRequestScopes, vendorError, type CoreScope, type DerivedManifest, type ErrorSpec, type Handler, type HandlerContext, type LanesDecl, type VendorManifest } from './derived-core.ts';
@@ -17,6 +17,13 @@ import { getActiveWorldStore } from './world-store.ts';
 import { runWithCorrelationId } from './actions.ts';
 import { deferPerform, performRequestGroup, RefusedWriteError, VendorWriteError } from './head.ts';
 import { withCors } from './cors.ts';
+import type { ApplicationStandIn } from './events.ts';
+import { contentAddressOf } from './content-route.ts';
+import { getPack, type HostRule } from './packRegistry.ts';
+import { hostRules } from '../vendor-hosts.cjs';
+
+/** A descriptor's host rules, as data. */
+type PackDescriptorHosts = ReadonlyArray<HostRule> | undefined;
 import { socketUpgrade, type SocketEngine } from './sockets.ts';
 import { MACHINE_POOL, POOL_KINDS } from './machines.ts';
 import { applyTwinWrite } from './serve.ts';
@@ -68,12 +75,23 @@ export type PackParts = {
 export type PackScenario<Req = any> = { adapter: PackScenarioAdapter<Req>; operations: ReadonlyArray<string>; request: (ctx: HandlerContext) => Req | undefined };
 
 /** A lane as its vendor's fetch is given it: its own pack fetch, and its manifest (the doors it declares). */
-export type LanePart = { fetch: ((request: Request) => Promise<Response>) & { serves?: (method: string, path: string) => boolean; boards?: boolean; draws?: (url: string) => boolean }; manifest: { doors?: ReadonlyArray<{ method: string; path: string }> } };
+export type LanePart = {
+  fetch: ((request: Request) => Promise<Response>) & {
+    serves?: (method: string, path: string) => boolean; boards?: boolean; draws?: (url: string) => boolean;
+    /** the hosts the lane's built content screens name: its vendor's router sends `<base>/@<host>/` there */
+    contentHosts?: ReadonlyArray<string>;
+  };
+  manifest: { doors?: ReadonlyArray<{ method: string; path: string }> };
+};
 
 /** Where a pack serves: its World's root, whether it was started read-only, the World instant when a caller pins it, the
  *  World's managed Postgres the runtime binds a pack declaring `managedDatabase` to (a handler's `ctx.engine`), and the
  *  World's scenario file for a model vendor's turns (`scenarioPath`, the runtime's `--scenario`). */
-export type PackFetchOptions = { root?: string; readOnly?: boolean; clock?: () => string; database?: string; scenarioPath?: string };
+export type PackFetchOptions = {
+  root?: string; readOnly?: boolean; clock?: () => string; database?: string; scenarioPath?: string;
+  /** the application a walk stands in for (a life's `application` answers): this fetch's `ctx.ask` is answered by it */
+  application?: ApplicationStandIn;
+};
 
 type Match = { params: Record<string, string> };
 /** A declared path (`/{account}/r2/api-tokens`, `/<room>`, a door's `/_twin/users/{email}`) as a matcher of a request's
@@ -160,6 +178,7 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
     ...(options.clock ? { clock: options.clock } : {}),
     ...(options.database !== undefined ? { database: options.database, readOnly: options.readOnly ?? false } : {}),
     ...(parts.tenant ? { tenant: parts.tenant } : {}),
+    ...(options.application ? { application: options.application } : {}),
   };
   // a command table's surface (Redis's, a vendor that carries Redis over HTTP) names no HTTP operation: its wire is the
   // pack's front (its `around`), and the table is the denominator the grade counts
@@ -295,6 +314,68 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
   };
   const rootServes = (method: string, path: string): boolean => Boolean(matchOperation(routes, method, path));
   const lane = m.lanes ? laneRouter(m.vendor, m.lanes, parts.lanes ?? {}, rootServes) : undefined;
+  // at a World's place, a page's asset or upload on another of the pack's content hosts is `<base>/@<host>/<path>`
+  // (architecture, "A page at a World's place"): answered by the built content screen that names that host exactly,
+  // routed from it, and by nothing else; a request naming no such host is general routing's
+  const contentScreens = screens.filter((s) => s.decl.kind === 'content');
+  for (const s of contentScreens) if (s.decl.yieldsToApi) throw new Error(`${m.vendor}: the content screen ${s.decl.id} declares yieldsToApi; a content screen answers its host's requests alone (architecture, "Screens")`);
+  const contentHosts = [...new Set(contentScreens.flatMap((s) => [s.decl.host, ...(s.decl.hosts ?? [])]).filter((h) => !/[{<]/.test(h)).map((h) => h.toLowerCase()))];
+  const contentNotFound = (host: string, path: string): Response => {
+    const nf = m.notFound;
+    return vendorError(m, { status: nf.status, message: nf.message.replace(/\{object\}/g, host).replace(/\{id\}/g, path), ...(nf.code !== undefined ? { code: nf.code } : {}), ...(nf.kind !== undefined ? { kind: nf.kind } : {}) });
+  };
+  /** A request at a World's place for `/@<host>/<path>`, `<host>` one a built content screen of this unit names exactly:
+   *  that screen's answer, or the pack's not-found for what the host or the screen does not take. The path is held to
+   *  the descriptor's host rules (`rules`: this unit's, or its vendor's for a lane), read as the injector reads them.
+   *  Undefined for any other request. */
+  // the descriptor's host rules: this unit's, or, for a lane (which declares none), its vendor's as registered
+  const descriptorHosts = (): PackDescriptorHosts => m.descriptor?.hosts ?? getPack(m.vendor)?.hosts;
+  const atContentHost = async (request: Request, rules: PackDescriptorHosts = descriptorHosts()): Promise<Response | undefined> => {
+    if (!request.headers.has(TWIN_PREFIX_HEADER)) return undefined;
+    const url = new URL(request.url);
+    const address = contentAddressOf(url.pathname);
+    if (!address || !contentHosts.includes(address.host)) return undefined;
+    const { host, path: inner } = address;
+    if (address.refused) return contentNotFound(host, inner);
+    const declared = hostRules(rules);
+    if (declared.names(host) && !declared.takes(host, inner)) return contentNotFound(host, inner);
+    const onHost = contentScreens.filter((s) => [s.decl.host, ...(s.decl.hosts ?? [])].some((h) => h.toLowerCase() === host));
+    const method = request.method.toUpperCase();
+    const allowed = (s: (typeof screens)[number]): boolean => method === 'GET' || method === 'HEAD' || (method === 'POST' && (s.decl.takes ?? []).includes('POST'));
+    // the request as it reaches the content host, through the pack's own routing of a host (its path prefix and labels)
+    url.pathname = inner;
+    const headers = new Headers(request.headers);
+    headers.set('x-volter-twin-original-host', host);
+    const sent = method === 'POST' && request.body ? { body: request.body, duplex: 'half' } : {};
+    const there = routed(new Request(url, { method, headers, signal: request.signal, ...sent } as RequestInit));
+    const path = new URL(there.url).pathname.replace(/\/+$/, '') || '/';
+    const hit = onHost.map((s) => ({ s, hit: s.path(path) })).find((x) => x.hit && allowed(x.s));
+    if (!hit) return contentNotFound(host, inner);
+    const asked = options.readOnly && !isReadOnlyRequest(there) ? withHeaders(there, new Headers([...there.headers, [READ_ONLY_REQUEST_HEADER, '1']])) : there;
+    if (method === 'POST' && ((options.readOnly ?? false) || isReadOnlyRequest(asked))) return refusedReadOnly();
+    if (parts.clock) await runAsVendorMove(async () => parts.clock!(await open(new Request(asked.url, m.tenant ? { headers: asked.headers } : {}), 'clock', 'POST', '/_twin/clock', {})));
+    return hit.s.answer(await open(asked, hit.s.decl.id, method, hit.s.decl.path, { ...(hit.s.host(host)?.params ?? {}), ...hit.hit!.params }));
+  };
+  /** A request as the kernel reads it: the headers only the kernel names taken off, its body decoded (undefined when it
+   *  does not decode as its Content-Encoding says). */
+  const prepared = async (arrived: Request): Promise<Request | undefined> => {
+    if (arrived.headers.has(SCENARIO_DECISION_HEADER) || arrived.headers.has(PREFIX_PARAMS_HEADER)) {
+      const headers = new Headers(arrived.headers);
+      headers.delete(SCENARIO_DECISION_HEADER);
+      headers.delete(PREFIX_PARAMS_HEADER);
+      arrived = new Request(arrived, { headers });
+    }
+    return decoded(m, arrived);
+  };
+  const undecodable = (arrived: Request): Response => vendorError(m, m.encodings?.undecodable ?? { status: 400, message: `the body does not decode as its Content-Encoding (${arrived.headers.get('content-encoding')}) says` });
+  /** The content route at the request's arrival: the answer, or undefined when this unit's content screens name no such
+   *  host. */
+  const answerContent = async (arrived: Request): Promise<Response | undefined> => {
+    const address = arrived.headers.has(TWIN_PREFIX_HEADER) ? contentAddressOf(new URL(arrived.url).pathname) : undefined;
+    if (!address || !contentHosts.includes(address.host)) return undefined;
+    const readable = await prepared(arrived);
+    return readable ? atContentHost(readable) : undecodable(arrived);
+  };
   const fetch = async (arrived: Request): Promise<Response> => {
     // the discovery door is the pack's own, whichever lane would take its path
     const asked = new URL(arrived.url).pathname.replace(/\/+$/, '') || '/';
@@ -307,17 +388,15 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
       const frames = await parts.board(await open(request, 'board', 'GET', '/twin/board', {}));
       return Response.json({ frames: frames.map((f) => ({ ...f, drawn: drawsUrl(f.url) })) });
     }
+    // `<base>/@<host>/<path>` at a World's place, for a host a built content screen of this pack names, is that screen's
+    // alone (only the kernel names a scenario's decision or a path prefix's parameters: `prepared` takes them off); for
+    // one a lane's names, the lane router sends it to that lane's own fetch, wrapped as any request to it is
+    const own = await answerContent(arrived);
+    if (own) return own;
     const toLane = discovery ? undefined : lane?.(arrived);
     if (toLane) return toLane(arrived);
-    // only the kernel names a scenario's decision, or a path prefix's parameters
-    if (arrived.headers.has(SCENARIO_DECISION_HEADER) || arrived.headers.has(PREFIX_PARAMS_HEADER)) {
-      const headers = new Headers(arrived.headers);
-      headers.delete(SCENARIO_DECISION_HEADER);
-      headers.delete(PREFIX_PARAMS_HEADER);
-      arrived = new Request(arrived, { headers });
-    }
-    const readable = await decoded(m, arrived);
-    if (!readable) return vendorError(m, m.encodings?.undecodable ?? { status: 400, message: `the body does not decode as its Content-Encoding (${arrived.headers.get('content-encoding')}) says` });
+    const readable = await prepared(arrived);
+    if (!readable) return undecodable(arrived);
     const incoming = routed(readable);
     // a twin started read-only marks every request so, so every context it opens knows (isReadOnlyRequest)
     const request = options.readOnly && !isReadOnlyRequest(incoming) ? withHeaders(incoming, new Headers([...incoming.headers, [READ_ONLY_REQUEST_HEADER, '1']])) : incoming;
@@ -368,8 +447,10 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
     // whichever host the twin is reached (its links carry the twin's own base), never a root screen off its own host
     const host = hostOf(request);
     const exact = (s: (typeof screens)[number]): boolean => [s.decl.host, ...(s.decl.hosts ?? [])].some((h) => !/[{<]/.test(h) && h.toLowerCase() === host);
-    const hits = screens.map((s) => ({ s, hit: s.path(path), onHost: s.host(host) })).filter((x) => x.hit);
     const apiPath = Boolean(matchOperation(routes, request.method, url.pathname, url.searchParams, request.headers));
+    // a screen that yields to the API draws only what no operation names, wherever it would answer (architecture,
+    // "Screens": Hacker News's /login page, whose form posts to POST /login)
+    const hits = screens.map((s) => ({ s, hit: s.path(path), onHost: s.host(host) })).filter((x) => x.hit && !(apiPath && x.s.decl.yieldsToApi));
     // reached at a World's place for the twin (`x-forwarded-prefix`, served-world's wire), the host is the World's: a
     // workspace is shown there by its path alone, its root too (the console frames it so)
     const placed = request.headers.has(TWIN_PREFIX_HEADER);
@@ -424,7 +505,9 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
     headers.set('content-type', m.jsonContentType!);
     return new Response(res.body, { status: res.status, statusText: res.statusText, headers });
   };
-  const served = m.cors ? withCors(m.cors, labelled) : labelled;
+  const cors = m.cors ? withCors(m.cors, labelled) : labelled;
+  // at a World's place every cookie the twin sets is kept to the twin's base path (twin-fetch.ts, placedCookies)
+  const served = async (request: Request): Promise<Response> => placedCookies(request, await cors(request));
   // which paths this pack's API serves, for a vendor's lane router that asks (unlessOnlyRoot)
   const serves = (method: string, path: string): boolean => Boolean(matchOperation(routes, method, path));
   // the vendor's sockets: a request to a declared socket's path opens a session of its engine, over a context of the
@@ -436,7 +519,7 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
     async (asked) => engineOf()?.serve(asked)) : undefined;
   // what serves each operation: the pack's own, and each lane's
   const owners = (): Record<string, DerivedOwner> => ({ ...api.owners(), ...lanesOwners(parts.lanes ?? {}) });
-  return derivedRequestScopes(m, Object.assign(served, { owners, serves, workspaces, boards: Boolean(parts.board), draws: drawsUrl, ...(upgrade ? { upgrade } : {}) }));
+  return derivedRequestScopes(m, Object.assign(served, { owners, serves, workspaces, boards: Boolean(parts.board), draws: drawsUrl, contentHosts, ...(upgrade ? { upgrade } : {}) }));
 }
 
 /** The vendor's gateway over its lanes: the lane a request goes to (a door to the lane that declares it, then the first
@@ -473,6 +556,12 @@ function laneRouter(vendor: string, decl: LanesDecl, lanes: Record<string, LaneP
   });
   const fallback = decl.default !== undefined ? served(decl.default) : undefined;
   return (request) => {
+    // `<base>/@<host>/<path>` at a World's place, for a host a lane's built content screen names, goes to that lane, before
+    // any lane is picked by the request's host or path: its own fetch answers it by its content route, under the vendor's
+    // host rules (architecture, "A page at a World's place")
+    const address = request.headers.has(TWIN_PREFIX_HEADER) ? contentAddressOf(new URL(request.url).pathname) : undefined;
+    const content = address && Object.keys(lanes).find((l) => lanes[l]!.fetch.contentHosts?.includes(address.host));
+    if (content) return served(content);
     const path = new URL(request.url).pathname.replace(/\/{2,}/g, '/');
     if (path.startsWith('/_twin/')) {
       const door = doors.find((d) => d.method === request.method && d.matches(path));

package/src/twin-fetch.ts

@@ -230,3 +230,29 @@ async function readScoped(run: (asReadOnly?: boolean) => TwinFetchHandlerResult
   if (!out.refused) return out.value;
   return { status: 405, body: { error: 'read_only', message: out.refused.message } };
 }
+
+/** A twin's answer at a World's place with its cookies kept to the twin: every cookie it sets is scoped to the twin's
+ *  base path there (`Path=/` and no Path become `Path=<prefix>`, which RFC 6265's path-match gives the twin's root
+ *  `<prefix>` and every path under it and no sibling; a path under the vendor's root, `Path=/x`, becomes `<prefix>/x`),
+ *  so one twin's sign-in never reaches a sibling twin served from the same pages origin (architecture, "A page at a
+ *  World's place"). A `__Host-` cookie, which a browser takes only at `Path=/`, is left as set. An answer off a place, at
+ *  a prefix the World never sends (outside `/[A-Za-z0-9._~/-]*`, which twinPublicBase refuses too), or setting no cookie
+ *  is the answer as it is. */
+export function placedCookies(request: Request, response: Response): Response {
+  const prefix = request.headers.get(TWIN_PREFIX_HEADER)?.replace(/\/+$/, '');
+  if (!prefix || !/^\/[A-Za-z0-9._~\/-]*$/.test(prefix)) return response;
+  const cookies = response.headers.getSetCookie?.() ?? [];
+  if (!cookies.length || response.status < 200) return response;
+  const scoped = cookies.map((cookie) => {
+    if (/^\s*__Host-/i.test(cookie)) return cookie;
+    const path = /;\s*path=([^;]*)/i.exec(cookie)?.[1]?.trim();
+    // already scoped (a lane's answer its vendor passes on): as it is
+    if (path !== undefined && (path === prefix || path.startsWith(`${prefix}/`))) return cookie;
+    const at = !path || path === '/' ? prefix : `${prefix}${path.startsWith('/') ? path : `/${path}`}`.replace(/\/+$/, '');
+    return path === undefined ? `${cookie}; Path=${at}` : cookie.replace(/(;\s*)path=[^;]*/i, `$1Path=${at}`);
+  });
+  const headers = new Headers(response.headers);
+  headers.delete('set-cookie');
+  for (const cookie of scoped) headers.append('set-cookie', cookie);
+  return new Response(response.body, { status: response.status, statusText: response.statusText, headers });
+}

package/vendor-hosts.cjs

@@ -55,6 +55,39 @@ const COMPILED = new Map();
 /** The hand table's keys, before any pack's rules: a pack installed later replaces its hand entry in place (keeping its
  *  position, which decides who answers a shared host first), where the built-in facts may not declare one twice. */
 const HAND = new Set(Object.keys(VENDOR_HOSTS));
+/** One host rule as a predicate over (hostname, pathname?): its one selector (host | suffix | hostPattern) and its
+ *  pathPattern, a path left out matching any. */
+function compileHostRule(rule, where) {
+  const selectors = ['host', 'suffix', 'hostPattern'].filter((k) => rule[k] !== undefined).length;
+  if (selectors !== 1) throw new Error(`inject: ${where} rule ${JSON.stringify(rule)} — exactly one of host | suffix | hostPattern (pack-facts.json is hand-edited or stale)`);
+  const hostRe = rule.hostPattern === undefined ? null : new RegExp(rule.hostPattern);
+  const pathRe = rule.pathPattern === undefined ? null : new RegExp(rule.pathPattern);
+  return (h, p) =>
+    (rule.host !== undefined ? h === rule.host : rule.suffix !== undefined ? h.endsWith(rule.suffix) : hostRe.test(h))
+    && (pathRe === null || p === undefined || pathRe.test(p));
+}
+
+/** A pack's host rules (its descriptor's `hosts`) read as the injector reads them: `names(host)`, whether any include
+ *  rule's selector names the host, whatever the path; `takes(host, path)`, whether the request is the pack's (under
+ *  one of its keys, an include matches and no exclude does). The content route at a World's place holds a
+ *  `<base>/@<host>/<path>` to it (pack-fetch.ts). */
+function hostRules(rules) {
+  const byKey = new Map();
+  for (const rule of rules || []) {
+    const key = rule.key === undefined ? '' : rule.key;
+    if (!byKey.has(key)) byKey.set(key, []);
+    byKey.get(key).push(rule);
+  }
+  const keys = [...byKey.values()].map((keyRules) => ({
+    includes: keyRules.filter((r) => r.exclude !== true).map((r) => compileHostRule(r, 'a pack')),
+    excludes: keyRules.filter((r) => r.exclude === true).map((r) => compileHostRule(r, 'a pack')),
+  }));
+  return {
+    names: (h) => keys.some((k) => k.includes.some((m) => m(h))),
+    takes: (h, p) => keys.some((k) => k.includes.some((m) => m(h, p)) && !k.excludes.some((m) => m(h, p))),
+  };
+}
+
 function compilePackHosts(packs, overlay) {
   for (const vendor of Object.keys(packs)) {
     const rules = packs[vendor].hosts;
@@ -77,15 +110,7 @@ function compilePackHosts(packs, overlay) {
       if (VENDOR_HOSTS[key] && !(overlay && HAND.has(key))) {
         throw new Error(`inject: key "${key}" (pack ${vendor}) is declared twice — on this descriptor and in the hand VENDOR_HOSTS table or another pack's descriptor; a key has one home.`);
       }
-      const compile = (rule) => {
-        const selectors = ['host', 'suffix', 'hostPattern'].filter((k) => rule[k] !== undefined).length;
-        if (selectors !== 1) throw new Error(`inject: key "${key}" (pack ${vendor}) rule ${JSON.stringify(rule)} — exactly one of host | suffix | hostPattern (pack-facts.json is hand-edited or stale)`);
-        const hostRe = rule.hostPattern === undefined ? null : new RegExp(rule.hostPattern);
-        const pathRe = rule.pathPattern === undefined ? null : new RegExp(rule.pathPattern);
-        return (h, p) =>
-          (rule.host !== undefined ? h === rule.host : rule.suffix !== undefined ? h.endsWith(rule.suffix) : hostRe.test(h))
-          && (pathRe === null || p === undefined || pathRe.test(p));
-      };
+      const compile = (rule) => compileHostRule(rule, `key "${key}" (pack ${vendor})`);
       const includes = keyRules.filter((r) => r.exclude !== true).map(compile);
       const excludes = keyRules.filter((r) => r.exclude === true).map(compile);
       VENDOR_HOSTS[key] = (h, p) => includes.some((m) => m(h, p)) && !excludes.some((m) => m(h, p));
@@ -141,4 +166,4 @@ function twinOrigins(env) {
   return map;
 }
 
-module.exports = { VENDOR_HOSTS, addPackHosts, isVendorHost, vendorsOfHost, twinEnvStem, twinOrigins };
+module.exports = { VENDOR_HOSTS, hostRules, addPackHosts, isVendorHost, vendorsOfHost, twinEnvStem, twinOrigins };

package/vendor-hosts.d.cts

@@ -6,3 +6,6 @@ export function vendorsOfHost(hostname: string): string[];
 export function twinEnvStem(vendor: string): string;
 /** The vendors whose twin `env` points at, each with its origin. */
 export function twinOrigins(env: Readonly<Record<string, string | undefined>>): Record<string, string>;
+/** A pack's host rules (its descriptor's `hosts`, as data) read as the injector reads them: whether any include names a
+ *  host whatever the path, and whether a request to a host and path is the pack's. */
+export function hostRules(rules: ReadonlyArray<{ host?: string; suffix?: string; hostPattern?: string; pathPattern?: string; key?: string; exclude?: true }> | undefined): { names(hostname: string): boolean; takes(hostname: string, pathname: string): boolean };