@volter/world-core 3.0.30 → 3.0.32

package/src/browser.ts

@@ -0,0 +1,164 @@
+import { BrowserCookieJar } from './browser-cookie-jar.ts';
+import { assertBrowserName, browserOrigin, validateBrowserState, type BrowserState } from './browser-state.ts';
+import { nodeBuiltin } from './serve-http.ts';
+import { worldNow } from './world-clock.ts';
+
+export { cookieMatchesHost } from './browser-state.ts';
+
+export type SeedBrowser = {
+  fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
+  storage(origin: string): { set(key: string, value: string): Promise<void>; remove(key: string): Promise<void> };
+  state(): Promise<BrowserState>;
+};
+
+/** Undo the request's path mount before its answer reaches a vendor-addressed client. */
+function vendorResponse(response: Response, vendor: URL, twin: URL, mount: string): Response {
+  if (!mount) return response;
+  const pathAtVendor = (path: string): string => path === mount ? '/' : path.startsWith(`${mount}/`) ? path.slice(mount.length) : path;
+  const urlAtVendor = (value: string): string => {
+    if (!value.trim()) return value;
+    let at: URL;
+    try { at = new URL(value, twin); } catch { return value; }
+    if (at.origin !== twin.origin && at.origin !== vendor.origin) return value;
+    const path = pathAtVendor(at.pathname);
+    if (path === at.pathname) return value;
+    const tail = `${path}${at.search}${at.hash}`;
+    return /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(value.trim()) ? `${vendor.origin}${tail}` : tail;
+  };
+  const headers = new Headers(response.headers);
+  let changed = false;
+  const cookies = response.headers.getSetCookie();
+  const mapped = cookies.map(cookie => cookie.replace(/(;\s*path\s*=)([^;]*)/gi, (attribute, lead: string, path: string) => {
+    const at = pathAtVendor(path.trim());
+    return at === path.trim() ? attribute : `${lead}${at}`;
+  }));
+  if (mapped.some((cookie, i) => cookie !== cookies[i])) {
+    headers.delete('set-cookie');
+    for (const cookie of mapped) headers.append('set-cookie', cookie);
+    changed = true;
+  }
+  for (const name of ['location', 'content-location']) {
+    const value = headers.get(name);
+    if (value === null) continue;
+    const at = urlAtVendor(value);
+    if (at !== value) { headers.set(name, at); changed = true; }
+  }
+  const refresh = headers.get('refresh');
+  if (refresh !== null) {
+    const parts = /^(\s*\d+(?:\.\d+)?\s*[;,]\s*(?:url\s*=\s*)?)(?:"([^"]*)"|'([^']*)'|([^"']*?))(\s*)$/i.exec(refresh);
+    if (parts) {
+      const value = parts[2] ?? parts[3] ?? parts[4]!;
+      const at = urlAtVendor(value);
+      if (at !== value) {
+        const quote = parts[2] !== undefined ? '"' : parts[3] !== undefined ? "'" : '';
+        headers.set('refresh', `${parts[1]}${quote}${at}${quote}${parts[5]}`);
+        changed = true;
+      }
+    }
+  }
+  return changed ? new Response(response.body, { status: response.status, statusText: response.statusText, headers }) : response;
+}
+
+/** A seed's named browser. Every state write goes through the World's single HTTP loader. */
+export async function browser(name: string): Promise<SeedBrowser> {
+  assertBrowserName(name);
+  const door = process.env.VOLTER_WORLD_BROWSER_DOOR;
+  const token = process.env.VOLTER_WORLD_BROWSER_TOKEN;
+  if (!process.env.VOLTER_WORLD || !door || !token) throw new Error('browser(name) runs in a World seed, with its browsers door and credential');
+  const require = nodeBuiltin<typeof import('node:module')>('module').createRequire(import.meta.url);
+  const routing = require('../vendor-hosts.cjs') as typeof import('../vendor-hosts.cjs');
+  const { packs } = require('../pack-facts.cjs').packFacts() as { packs: Record<string, { hostsClaimed?: { door: string } }> };
+  const resolve = async (url: URL): Promise<{ vendor: string; origin: string } | null> => {
+    const map = routing.twinOrigins(process.env);
+    const declared = routing.resolveTwinHost(url.hostname, map, url.pathname);
+    if (declared) return declared;
+    const claimed: Record<string, Set<string>> = {};
+    for (const [vendor, facts] of Object.entries(packs)) {
+      const origin = map[vendor] ?? process.env[`${routing.twinEnvStem(vendor)}_TWIN_URL`];
+      if (!origin || !facts.hostsClaimed) continue;
+      map[vendor] = origin;
+      const headers = new Headers({ 'x-volter-read-only': '1' });
+      if (process.env.VOLTER_TWINS_KEY) headers.set('x-twins-key', process.env.VOLTER_TWINS_KEY);
+      const listed = await fetch(`${origin}${facts.hostsClaimed.door}`, { headers })
+        .then(r => r.ok ? r.json() as Promise<{ hosts?: unknown }> : null).catch(() => null);
+      claimed[vendor] = new Set(Array.isArray(listed?.hosts) ? listed.hosts.map(h => String(h).toLowerCase()) : []);
+    }
+    return routing.resolveTwinHost(url.hostname, map, url.pathname, claimed);
+  };
+  const initial = await fetch(`${door}/${name}`, { headers: { 'x-volter-token': token } });
+  if (!initial.ok && initial.status !== 404) throw new Error(`browser ${name}: ${initial.status} ${await initial.text()}`);
+  const stored = initial.ok ? validateBrowserState(await initial.json()) : { cookies: [], origins: [] };
+  const jar = new BrowserCookieJar(stored.cookies);
+  const origins = structuredClone(stored.origins);
+  let queue: Promise<unknown> = Promise.resolve();
+  const serial = <T>(fn: () => Promise<T>): Promise<T> => { const next = queue.then(fn); queue = next.then(() => undefined, () => undefined); return next; };
+  const snapshot = (): BrowserState => {
+    const now = new Date(worldNow()).getTime();
+    const cookies = jar.snapshot(now);
+    return validateBrowserState({ cookies, origins: structuredClone(origins) });
+  };
+  const save = async (): Promise<void> => {
+    const response = await fetch(`${door}/${name}`, { method: 'PUT', headers: { 'content-type': 'application/json', 'x-volter-token': token }, body: JSON.stringify(snapshot()) });
+    if (!response.ok) throw new Error(`browser ${name}: ${response.status} ${await response.text()}`);
+  };
+  if (initial.status === 404) await save();
+  return {
+    state: () => serial(async () => snapshot()),
+    storage(origin) {
+      browserOrigin(origin);
+      const change = (key: string, value?: string): Promise<void> => serial(async () => {
+        if (typeof key !== 'string' || (value !== undefined && typeof value !== 'string')) throw new Error('browser storage: string keys and values');
+        const before = JSON.stringify(origins);
+        let entry = origins.find(o => o.origin === origin);
+        if (!entry && value !== undefined) { entry = { origin, localStorage: [] }; origins.push(entry); }
+        if (entry) {
+          entry.localStorage = entry.localStorage.filter(v => v.name !== key);
+          if (value !== undefined) entry.localStorage.push({ name: key, value });
+        }
+        if (JSON.stringify(origins) !== before) await save();
+      });
+      return { set: (key, value) => change(key, value), remove: key => change(key) };
+    },
+    fetch: (input, init) => serial(async () => {
+      const request = new Request(input, init);
+      let url = new URL(request.url);
+      let method = request.method;
+      let body: ArrayBuffer | undefined = request.body ? await request.arrayBuffer() : undefined;
+      const headers = new Headers(request.headers);
+      if (headers.has('cookie')) throw new Error('browser.fetch carries its own cookie jar');
+      for (let redirects = 0; ; redirects++) {
+        if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password) throw new Error('browser.fetch takes an http or https vendor URL');
+        const target = await resolve(url);
+        if (!target || target.vendor === 'app') throw new Error(`browser ${name}: no twin in this World serves ${url.hostname}${url.pathname}`);
+        const at = new URL(target.origin);
+        const mount = at.pathname.replace(/\/+$/, '');
+        at.pathname = `${mount}${url.pathname}`;
+        at.search = url.search;
+        const sent = new Headers(headers);
+        const cookies = jar.header(url, new Date(worldNow()).getTime());
+        if (cookies) sent.set('cookie', cookies);
+        sent.set('host', mount ? at.host : url.host);
+        sent.set('x-volter-twin-original-host', url.host);
+        sent.set('x-forwarded-host', url.host);
+        sent.set('x-forwarded-proto', url.protocol.slice(0, -1));
+        if (process.env.VOLTER_TWINS_KEY) sent.set('x-twins-key', process.env.VOLTER_TWINS_KEY);
+        const before = JSON.stringify(snapshot());
+        const response = vendorResponse(await fetch(at, { method, headers: sent, body, redirect: 'manual', signal: request.signal }), url, at, mount);
+        for (const cookie of response.headers.getSetCookie()) jar.set(cookie, url, new Date(worldNow()).getTime());
+        if (JSON.stringify(snapshot()) !== before) await save();
+        const location = response.headers.get('location');
+        if (!location || ![301, 302, 303, 307, 308].includes(response.status) || request.redirect === 'manual') return response;
+        if (request.redirect === 'error') throw new Error('browser.fetch refused a redirect');
+        if (redirects >= 20) throw new Error('browser.fetch exceeded the fetch redirect limit');
+        await response.body?.cancel();
+        const next = new URL(location, url);
+        if (next.origin !== url.origin) { headers.delete('authorization'); headers.delete('proxy-authorization'); }
+        if ((response.status === 303 && method !== 'HEAD') || ([301, 302].includes(response.status) && method === 'POST')) {
+          method = 'GET'; body = undefined;
+          for (const key of ['content-type', 'content-length', 'content-encoding', 'content-language', 'content-location']) headers.delete(key);
+        }
+        url = next;
+      }
+    }),
+  };
+}

package/src/derived-core.ts

@@ -214,7 +214,7 @@ 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; browserSession?: DerivedManifest['browserSession'];
+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'] };
 
@@ -395,8 +395,6 @@ export type DerivedManifest = {
   resources: Record<string, ResourceDecl>;
   /** Read-only cross-pack credential subjects of the same vendor (architecture A3); no root is exposed to handlers. */
   ownerReads?: ReadonlyArray<{ owner: string; resource: string }>;
-  /** The browser session of a World's person, issued with world-ui's kit. Declaring it lets the World offer View as. */
-  browserSession?: { cookie: string; scope?: string };
   /** the vendor's screens this pack serves or owes (demand decides which exist) */
   screens?: ScreenDecl[];
   /** The discovery door's facts (`GET /twin`): what the twin is of, what it stores, and how it is authenticated. */
@@ -774,8 +772,9 @@ function view(m: DerivedManifest, resource: string, r: TwinResource): Record<str
  *  a caller that pins an instant passes its own). */
 /** One call of a protocol-3 pack's default data (`src/semantics/seed.ts` exports `seed: SeedCall[]`): a request to the
  *  vendor's own operation (or the pack's door), made in order against the twin by the runner `volter-world init` writes
- *  beside the copied data. */
-export type SeedCall = { method: string; path: string; body?: unknown; headers?: Record<string, string> };
+ *  beside the copied data. An ordinary path is relative to the twin base. A call naming a browser uses the
+ *  vendor's absolute URL and is exported separately as `browserSeed`, after the ordinary `seed` calls. */
+export type SeedCall = { browser?: string; method: string; path: string; body?: unknown; headers?: Record<string, string> };
 
 /** Where a call is answered: the World's root, its clock, and the managed Postgres the runtime binds to the pack
  *  (`database`, the descriptor's `managedDatabase`), which a handler reaches as `ctx.engine` — READ ONLY in every

package/src/derived.ts

@@ -208,7 +208,7 @@ export type DerivedFetch = ((request: Request) => Promise<Response>) & {
 };
 
 /** A workspace screen a pack draws, as `GET /twin` lists it: its id and path (Viewing a World). */
-export type Workspace = { id: string; path: string };
+export type Workspace = { id: string; path: string; host?: string };
 
 /** A page of the World's board (architecture, "The board"): a page there is to see at the vendor, a record's own (an
  *  account's profile, each of its posts, a site and each page it serves), as the vendor's pack lists them from its state

package/src/index.ts

@@ -91,3 +91,5 @@ export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioErr
 export type { PackScenarioAdapter, ScenarioDecision, ScenarioDocument, ScenarioExtractorSpec, ScenarioFault, ScenarioFaultResult, ScenarioFeatures, ScenarioHandler, ScenarioMatcher, ScenarioMissRecord, ScenarioStatus } from './scenario.ts';
 
 export { browserSessionToken, startBrowserSession, endBrowserSession } from './browser-session.ts';
+
+export { assertBrowserName, browserOrigin, validateBrowserState, cookieMatchesHost, type BrowserCookie, type BrowserState, type BrowserIndexedDB } from './browser-state.ts';

package/src/pack-fetch.ts

@@ -5,8 +5,6 @@
 // `screens/<id>.tsx`), and the API (the derived dispatch over the generated surface, the handlers and the core). Every
 // 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 { startBrowserSession, endBrowserSession } from './browser-session.ts';
-import { BROWSER_SESSION_PATH, takeBrowserSessionPermit } from './browser-session-permit.ts';
 import { ORIGINAL_PATH_HEADER } from './sigv4.ts';
 import { placedCookies, TWIN_PREFIX_HEADER } from './twin-fetch.ts';
 import { PREFIX_PARAMS_HEADER } from './derived.ts';
@@ -22,7 +20,7 @@ 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';
+import { hostRules } from '../host-routing.cjs';
 
 /** A descriptor's host rules, as data. */
 type PackDescriptorHosts = ReadonlyArray<HostRule> | undefined;
@@ -79,11 +77,9 @@ export type PackScenario<Req = any> = { adapter: PackScenarioAdapter<Req>; opera
 /** 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; drawsScreens?: boolean; draws?: (url: string) => boolean;
+    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>;
-    /** A vendor's browser session applies to its lanes without a lane importing its parent's manifest. */
-    sessionDeclaration?: (session: NonNullable<DerivedManifest['browserSession']>) => void;
   };
   manifest: { doors?: ReadonlyArray<{ method: string; path: string }> };
 };
@@ -177,7 +173,6 @@ async function encoded(m: DerivedManifest, request: Request, res: Response): Pro
 /** A pack's HTTP surface, as the kernel serves it from the pack's parts. */
 export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}): DerivedFetch {
   const m = parts.manifest;
-  let browserSession = m.browserSession;
   const scope: CoreScope = {
     ...(options.root !== undefined ? { root: options.root } : {}),
     ...(options.clock ? { clock: options.clock } : {}),
@@ -275,7 +270,7 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
   });
   // the workspaces a person can be shown (Viewing a World): each built workspace screen's id and path, the pack's own
   // and its lanes'
-  const workspaces = (): Workspace[] => [...(m.screens ?? []).filter((s) => s.kind === 'workspace' && s.status === 'done' && parts.screens?.[s.id]).map((s) => ({ id: s.id, path: s.path })), ...lanesWorkspaces(parts.lanes ?? {})];
+  const workspaces = (): Workspace[] => [...(m.screens ?? []).filter((s) => s.kind === 'workspace' && s.status === 'done' && parts.screens?.[s.id]).map((s) => ({ id: s.id, path: s.path, host: s.host })), ...lanesWorkspaces(parts.lanes ?? {})];
   /** Whether a built screen a person views (a workspace or a flow, never content an API client reads) draws a url: its host
    *  one the screen names, its path the screen's or under it (a root screen draws its root alone). */
   // by what the pack declares built (a screen drawn by another's handler, as X's profile is by its web pages, is built)
@@ -283,7 +278,6 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
     const hosts = [s.host, ...(s.hosts ?? [])].map(hostMatcher);
     return { root: s.path.replace(/\/+$/, '') === '', host: (h: string) => hosts.some((match) => match(h)), path: pathMatcher(s.path, true) };
   });
-  const drawsScreens = viewed.length > 0 || Object.values(parts.lanes ?? {}).some((l) => l.fetch.drawsScreens);
   const drawsUrl = (at: string): boolean => {
     try {
       const u = new URL(at); const path = u.pathname.replace(/\/+$/, '') || '/';
@@ -412,7 +406,7 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
     if (request.method === 'GET' && path === '/twin' && m.discovery) {
       const d = m.discovery;
       // the workspaces a person can be shown (Viewing a World): each built workspace screen's id and path
-      const shown = { drawsScreens, ...(workspaces().length ? { screens: workspaces() } : {}), ...(browserSession ? { browserSession } : {}) };
+      const shown = workspaces().length ? { screens: workspaces() } : {};
       // a model vendor's: its state, and what its scenario scripts, with the scenario's live counts
       if (parts.scenario && d.behavior) {
         return Response.json({ ...shown, ...twinManifest({
@@ -428,17 +422,6 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
     // the vendor's own moves, not the caller's: its context carries none of the request's headers (a Stripe-Account
     // header would make a payout time makes the caller's), but a tenant's, when the vendor keeps tenants apart
     if (parts.clock) await runAsVendorMove(async () => parts.clock!(await open(new Request(request.url, m.tenant ? { headers: request.headers } : {}), 'clock', 'POST', '/_twin/clock', {})));
-    if (path === BROWSER_SESSION_PATH && browserSession) {
-      if (request.method !== 'POST' || readOnly) return Response.json({ error: 'a browser session needs a permitted write' }, { status: 403 });
-      const choice = takeBrowserSessionPermit(request, m.service, options.root);
-      if (!choice) return Response.json({ error: 'only the World can change this browser session' }, { status: 403 });
-      const ctx = await open(request, 'browser-session', 'POST', BROWSER_SESSION_PATH, {});
-      const person = choice.person === null ? null : ctx.rowsRaw('_person').find((p) => p.id === choice.person && typeof p.email === 'string');
-      if (person === undefined) return Response.json({ error: 'that person is no longer in the World' }, { status: 404 });
-      const cleared = await endBrowserSession(ctx, browserSession.cookie);
-      const cookie = person ? await startBrowserSession(ctx, String(person.email), browserSession.cookie, browserSession.scope) : cleared;
-      return new Response(null, { status: 303, headers: { location: choice.land, 'set-cookie': cookie } });
-    }
     if (path.startsWith('/_twin/')) {
       // the World's machine pool, enrolled by the kernel for a vendor that runs images (machines.ts)
       if (m.machines && path === '/_twin/machine-pool' && request.method === 'POST') {
@@ -536,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, { sessionDeclaration: (session: NonNullable<DerivedManifest['browserSession']>) => { browserSession ??= session; }, owners, serves, workspaces, boards: Boolean(parts.board), drawsScreens, draws: drawsUrl, contentHosts, ...(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
@@ -600,7 +583,6 @@ const lanesWorkspaces = (lanes: Record<string, LanePart>): Workspace[] =>
   Object.values(lanes).flatMap((l) => (l.fetch as { workspaces?: () => Workspace[] }).workspaces?.() ?? []);
 
 export function createVendorFetch(manifest: VendorManifest, lanes: Record<string, LanePart>): ((request: Request) => Promise<Response>) & { owners: () => Record<string, DerivedOwner>; workspaces: () => Workspace[] } {
-  if (manifest.browserSession) for (const part of Object.values(lanes)) part.fetch.sessionDeclaration?.(manifest.browserSession);
   const lane = laneRouter(manifest.vendor, manifest.lanes, lanes);
   return Object.assign(async (request: Request): Promise<Response> => {
     const path = new URL(request.url).pathname.replace(/\/+$/, '') || '/';
@@ -620,7 +602,7 @@ export function createVendorFetch(manifest: VendorManifest, lanes: Record<string
     if (request.method === 'GET' && path === '/twin' && manifest.discovery) {
       // the vendor's screens are its lanes' (a dashboard drawn by one lane is the vendor's)
       const screens = lanesWorkspaces(lanes);
-      return Response.json({ ...statefulTwinManifest({ vendor: manifest.vendor, ...manifest.discovery }), drawsScreens: Object.values(lanes).some((l) => l.fetch.drawsScreens), ...(manifest.browserSession ? { browserSession: manifest.browserSession } : {}), ...(screens.length ? { screens } : {}) });
+      return Response.json({ ...statefulTwinManifest({ vendor: manifest.vendor, ...manifest.discovery }), ...(screens.length ? { screens } : {}) });
     }
     const to = lane(request);
     return to ? to(request) : Response.json({ error: `${manifest.vendor}: no lane serves ${request.method} ${path}` }, { status: 404 });