@volter/world-core 3.0.29 → 3.0.31

package/src/browser-state.ts

@@ -0,0 +1,89 @@
+/** The frontend state of a scenario, in Playwright's storageState form. */
+export type BrowserCookie = { name: string; value: string; domain: string; path: string; expires: number; httpOnly: boolean; secure: boolean; sameSite: 'Strict' | 'Lax' | 'None'; partitionKey?: string; _crHasCrossSiteAncestor?: boolean };
+export type BrowserIndexedDB = { name: string; version: number; stores: {
+  name: string; autoIncrement: boolean; keyPath?: string; keyPathArray?: string[];
+  records: { key?: unknown; keyEncoded?: unknown; value?: unknown; valueEncoded?: unknown }[];
+  indexes: { name: string; keyPath?: string; keyPathArray?: string[]; multiEntry: boolean; unique: boolean }[];
+}[] };
+export type BrowserState = { cookies: BrowserCookie[]; origins: { origin: string; localStorage: { name: string; value: string }[]; indexedDB?: BrowserIndexedDB[] }[] };
+
+export function assertBrowserName(name: string): void {
+  if (!/^[a-z0-9](?:[a-z0-9]|-(?!-)){0,23}$/.test(name) || name.endsWith('-')) throw new Error('browser name: 1–24 lowercase letters, digits or single hyphens, starting and ending with a letter or digit');
+}
+
+function object(value: unknown, keys: string[]): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).some(k => !keys.includes(k))) throw new Error(`browser state: an object with only ${keys.join(', ')}`);
+  return value as Record<string, unknown>;
+}
+const host = (value: string): boolean => value !== 'localhost' && !value.endsWith('.localhost') && !/^\d+(?:\.\d+){3}$/.test(value) && /^(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z][a-z0-9-]*$/.test(value) && value.length <= 253 && value.split('.').every(l => l.length <= 63);
+
+export function browserOrigin(value: string): string {
+  let url: URL;
+  try { url = new URL(value); } catch { throw new Error('browser origin: an absolute http or https vendor origin'); }
+  if (!['http:', 'https:'].includes(url.protocol) || url.origin !== value || !host(url.hostname)) throw new Error('browser origin: a canonical http or https vendor origin, never a local twin URL');
+  return value;
+}
+
+/** Refuse unknown keys at every level; the accepted object is never reshaped. */
+export function validateBrowserState(value: unknown): BrowserState {
+  const state = object(value, ['cookies', 'origins']);
+  if (!Array.isArray(state.cookies) || !Array.isArray(state.origins)) throw new Error('browser state: cookies and origins are arrays');
+  const cookies = new Set<string>();
+  for (const raw of state.cookies) {
+    const c = object(raw, ['name', 'value', 'domain', 'path', 'expires', 'httpOnly', 'secure', 'sameSite', 'partitionKey', '_crHasCrossSiteAncestor']);
+    if (typeof c.name !== 'string' || !/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(c.name) || typeof c.value !== 'string' || /[\x00-\x1f\x7f;]/.test(c.value)) throw new Error('browser cookie: a cookie name and wire-safe string value');
+    if (/[^\u0000-\u00ff]/.test(c.value)) throw new Error('browser cookie: value characters must be U+00FF or below for Set-Cookie');
+    if (typeof c.domain !== 'string' || !host(c.domain.replace(/^\./, ''))) throw new Error('browser cookie: a real vendor domain, optionally prefixed by a dot');
+    if (typeof c.path !== 'string' || !c.path.startsWith('/') || /[\x00-\x20\x7f;\u0100-\uffff]/.test(c.path)) throw new Error('browser cookie: an absolute wire-safe cookie path');
+    if (typeof c.expires !== 'number' || !Number.isFinite(c.expires) || (c.expires < 0 && c.expires !== -1)) throw new Error('browser cookie: expires is Unix seconds, or -1 for a session');
+    if (typeof c.httpOnly !== 'boolean' || typeof c.secure !== 'boolean' || (typeof c.sameSite !== 'string' || !['Strict', 'Lax', 'None'].includes(c.sameSite))) throw new Error('browser cookie: httpOnly and secure are booleans; sameSite is Strict, Lax or None');
+    if (c.partitionKey !== undefined && (typeof c.partitionKey !== 'string' || !c.partitionKey || /[\x00-\x20\x7f]/.test(c.partitionKey))) throw new Error('browser cookie: partitionKey is a nonempty string');
+    if (c._crHasCrossSiteAncestor !== undefined && typeof c._crHasCrossSiteAncestor !== 'boolean') throw new Error('browser cookie: _crHasCrossSiteAncestor is a boolean');
+    const key = JSON.stringify([c.name, c.domain, c.path, c.partitionKey]);
+    if (cookies.has(key)) throw new Error('browser state: duplicate cookie');
+    cookies.add(key);
+  }
+  const origins = new Set<string>();
+  for (const raw of state.origins) {
+    const o = object(raw, ['origin', 'localStorage', 'indexedDB']);
+    if (typeof o.origin !== 'string') throw new Error('browser state: origin is a string');
+    browserOrigin(o.origin);
+    if (origins.has(o.origin)) throw new Error('browser state: duplicate origin');
+    origins.add(o.origin);
+    if (!Array.isArray(o.localStorage)) throw new Error('browser state: localStorage is an array');
+    if (o.indexedDB !== undefined) {
+      if (!Array.isArray(o.indexedDB)) throw new Error('browser storage: indexedDB is an array');
+      const keyPath = (item: Record<string, unknown>): void => {
+        if (item.keyPath !== undefined && typeof item.keyPath !== 'string') throw new Error('browser IndexedDB: keyPath is a string');
+        if (item.keyPathArray !== undefined && (!Array.isArray(item.keyPathArray) || item.keyPathArray.some(k => typeof k !== 'string'))) throw new Error('browser IndexedDB: keyPathArray contains strings');
+      };
+      for (const rawDB of o.indexedDB) {
+        const db = object(rawDB, ['name', 'version', 'stores']);
+        if (typeof db.name !== 'string' || typeof db.version !== 'number' || !Number.isSafeInteger(db.version) || db.version < 1 || !Array.isArray(db.stores)) throw new Error('browser IndexedDB: a name, positive integer version and stores array');
+        for (const rawStore of db.stores) {
+          const store = object(rawStore, ['name', 'autoIncrement', 'keyPath', 'keyPathArray', 'records', 'indexes']);
+          if (typeof store.name !== 'string' || typeof store.autoIncrement !== 'boolean' || !Array.isArray(store.records) || !Array.isArray(store.indexes)) throw new Error('browser IndexedDB: a store name, autoIncrement boolean, records and indexes arrays');
+          keyPath(store);
+          for (const record of store.records) object(record, ['key', 'keyEncoded', 'value', 'valueEncoded']);
+          for (const rawIndex of store.indexes) {
+            const index = object(rawIndex, ['name', 'keyPath', 'keyPathArray', 'multiEntry', 'unique']);
+            if (typeof index.name !== 'string' || typeof index.multiEntry !== 'boolean' || typeof index.unique !== 'boolean') throw new Error('browser IndexedDB: an index name, multiEntry and unique booleans');
+            keyPath(index);
+          }
+        }
+      }
+    }
+    const names = new Set<string>();
+    for (const rawEntry of o.localStorage) {
+      const entry = object(rawEntry, ['name', 'value']);
+      if (typeof entry.name !== 'string' || typeof entry.value !== 'string' || names.has(entry.name)) throw new Error('browser storage: unique string names and string values');
+      names.add(entry.name);
+    }
+  }
+  return value as BrowserState;
+}
+
+export function cookieMatchesHost(cookie: BrowserCookie, hostname: string): boolean {
+  const domain = cookie.domain.replace(/^\./, '');
+  return hostname === domain || (cookie.domain.startsWith('.') && hostname.endsWith(`.${domain}`));
+}

package/src/browser.ts

@@ -0,0 +1,115 @@
+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>;
+};
+
+/** 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);
+        at.pathname = `${at.pathname.replace(/\/$/, '')}${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', new URL(target.origin).pathname.replace(/\/$/, '') ? 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 = await fetch(at, { method, headers: sent, body, redirect: 'manual', signal: request.signal });
+        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

@@ -772,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
@@ -1702,7 +1703,6 @@ export async function contextFor(m: DerivedManifest, call: DerivedCall, scope: C
     body,
     text,
     root,
-    occurredAt: at,
     publicBase: twinPublicBase(call.request),
     scenario: scenarioDecisionOf(call.request),
     deliver: (url, init) => deliverToApplication(url, init),
@@ -1737,7 +1737,30 @@ export async function contextFor(m: DerivedManifest, call: DerivedCall, scope: C
       }
       return id;
     },
+    occurredAt: at,
     secret: async (label) => hmac(await worldSeed(m.service, root, at), label, 'base64url'),
+    record: async (type, fields, id) => {
+      if (!type.startsWith('_')) throw new Error(`semantics: ${type} is not a bookkeeping type (bookkeeping types start with _)`);
+      if (id !== undefined) {
+        await applyTwinWrite(m.service, { operation: `${type.slice(1)}.record`, subjectType: type, subjectId: id, fields, occurredAt: at, actor: { kind: 'system' } }, root);
+        return id;
+      }
+      const { value } = await applyTwinWriteAtomic(m.service, (resources) => {
+        // Allocate and append under the same state lock: concurrent sign-ins must never share an issue id.
+        const subject = (() => {
+          const prefix = `${type.slice(1)}_`;
+          let max = 0;
+          for (const r of resources) {
+            if (r.type !== type) continue;
+            const n = r.id.startsWith(prefix) ? Number(r.id.slice(prefix.length)) : NaN;
+            if (Number.isInteger(n) && n > max) max = n;
+          }
+          return `${prefix}${max + 1}`;
+        })();
+        return { kind: 'write', value: subject, write: { operation: `${type.slice(1)}.record`, subjectType: type, subjectId: subject, fields, occurredAt: at, actor: { kind: 'system' } } };
+      }, root, () => resourcesOfType(m.service, type, root));
+      return value;
+    },
     get machines() {
       const enrolled = resourcesOfType(m.service, MACHINE_POOL, root).find((r) => r.id === 'pool') as unknown as { kind?: MachinePool['kind'] } | undefined;
       return poolFor(m.service, root, enrolled?.kind ?? 'none');
@@ -1767,19 +1790,6 @@ export async function contextFor(m: DerivedManifest, call: DerivedCall, scope: C
     rowsRaw: (resource, opts) => stored(m, resource, root, opts) as Array<Record<string, unknown>>,
     tree: () => twinResources(m.service, root) as Array<Record<string, unknown>>,
     history: (resource, id) => subjectHistory(m.service, { type: storedType(m, resource), id }, root).map((e) => ({ ...(e.operation ? { operation: e.operation } : {}), ...(e.fields ? { fields: e.fields as Record<string, unknown> } : {}), ...(e.occurredAt ? { occurredAt: e.occurredAt } : {}) })),
-    record: async (type, fields, id) => {
-      if (!type.startsWith('_')) throw new Error(`semantics: ${type} is not a bookkeeping type (bookkeeping types start with _)`);
-      // an id the caller does not give is the next past every one of this type the tree holds (as `{n}` ids are minted),
-      // never a count of the rows, which a removed row would make repeat
-      const subject = id ?? (() => {
-        const prefix = `${type.slice(1)}_`;
-        let max = 0;
-        for (const r of resourcesOfType(m.service, type, root)) { const n = r.id.startsWith(prefix) ? Number(r.id.slice(prefix.length)) : NaN; if (Number.isInteger(n) && n > max) max = n; }
-        return `${prefix}${max + 1}`;
-      })();
-      await applyTwinWrite(m.service, { operation: `${type.slice(1)}.record`, subjectType: type, subjectId: subject, fields, occurredAt: at, actor: { kind: 'system' } }, root);
-      return subject;
-    },
     raw: (body, init = {}) => new Response(body, { status: init.status ?? 200, headers: init.headers ?? {} }),
     atomically: async (decide) => {
       const { value } = await applyTwinWriteAtomic(

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

@@ -89,3 +89,7 @@ export * as git from './git/index.ts';
 // ── the scenario grammar (architecture, "Behaviour") ───────────────────────────────────────────
 export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioError } from './scenario.ts';
 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

@@ -20,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;
@@ -270,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)