@daugasauron/dolly 0.0.0-stage → 0.1.4-rc.1

package/host/http/policy.mjs

@@ -0,0 +1,293 @@
+import { DOLLY_ERRNO } from "./abi.mjs";
+
+export class HttpError extends Error {
+  constructor(errno, message) { super(message); this.errno = errno; }
+}
+
+const credentialHeaderNames = new Set([
+  "authorization",
+  "cookie",
+  "proxy-authorization",
+  "x-api-key",
+  "api-key",
+  "x-goog-api-key",
+]);
+
+// Fetch owns these transport headers. Forwarding native libcurl values is not
+// merely ineffective: engines disagree about whether to discard them or turn
+// the request into a CORS preflight. In particular Firefox preflights a
+// caller-supplied User-Agent, which makes otherwise CORS-enabled PyPI GETs
+// fail. Normalize that browser variance at Dolly's broker boundary.
+const browserOwnedTransportHeaderNames = new Set([
+  "accept-encoding",
+  "connection",
+  "content-length",
+  "host",
+  "transfer-encoding",
+  "user-agent",
+]);
+
+export function isDollyCredentialHeader(name) {
+  return credentialHeaderNames.has(String(name).toLowerCase());
+}
+
+export function stripDollyBrowserOwnedHeaders(headers) {
+  for (const name of browserOwnedTransportHeaderNames) headers.delete(name);
+  return headers;
+}
+
+const defaultLimits = Object.freeze({
+  maxRequests: 256,
+  maxRequestBytes: 8 * 1024 * 1024,
+  maxResponseBytes: Infinity,
+  timeoutMilliseconds: 600_000,
+});
+
+function positiveInteger(value, fallback, name) {
+  const result = value ?? fallback;
+  if (!Number.isSafeInteger(result) || result <= 0) {
+    throw new TypeError(`invalid Dolly HTTP policy ${name}`);
+  }
+  return result;
+}
+
+function normalizeRule(rule) {
+  if (rule === null || typeof rule !== "object") {
+    throw new TypeError("invalid Dolly HTTP policy rule");
+  }
+  const origin = new URL(rule.origin).origin;
+  if (origin !== rule.origin || !/^https?:$/.test(new URL(origin).protocol)) {
+    throw new TypeError("Dolly HTTP policy origins must be exact HTTP(S) origins");
+  }
+  if (rule.path !== undefined && rule.pathPrefix !== undefined) {
+    throw new TypeError("Dolly HTTP policy rules cannot combine path and pathPrefix");
+  }
+  const path = rule.path === undefined ? null : String(rule.path);
+  const pathPrefix = rule.pathPrefix ?? "/";
+  if (path !== null && !path.startsWith("/")) {
+    throw new TypeError("Dolly HTTP policy paths must start with /");
+  }
+  if (typeof pathPrefix !== "string" || !pathPrefix.startsWith("/")) {
+    throw new TypeError("Dolly HTTP policy path prefixes must start with /");
+  }
+  const methods = new Set((rule.methods ?? ["GET", "HEAD"]).map((method) => {
+    if (typeof method !== "string" || !/^[A-Z]+$/.test(method)) {
+      throw new TypeError("Dolly HTTP policy methods must be uppercase tokens");
+    }
+    return method;
+  }));
+  if (rule.credential !== undefined) {
+    throw new TypeError(
+      "Dolly HTTP credentials belong inside the sandbox; use credentialHeaders",
+    );
+  }
+  const credentialHeaders = new Set((rule.credentialHeaders ?? []).map((value) => {
+    const name = String(value).toLowerCase();
+    if (!credentialHeaderNames.has(name)) {
+      throw new TypeError(`invalid Dolly HTTP credential header: ${name}`);
+    }
+    return name;
+  }));
+  return Object.freeze({
+    origin,
+    path,
+    pathPrefix,
+    methods,
+    credentialHeaders,
+    maxRequestBytes: positiveInteger(
+      rule.maxRequestBytes,
+      defaultLimits.maxRequestBytes,
+      "maxRequestBytes",
+    ),
+    maxResponseBytes: rule.maxResponseBytes == null ? Infinity :
+      positiveInteger(rule.maxResponseBytes, undefined, "maxResponseBytes"),
+    timeoutMilliseconds: positiveInteger(
+      rule.timeoutMilliseconds,
+      defaultLimits.timeoutMilliseconds,
+      "timeoutMilliseconds",
+    ),
+  });
+}
+
+// Whole segments only: "/v1" admits "/v1" and "/v1/x", never "/v1-admin".
+// Encoded separators could re-segment the path on the server.
+function pathWithin(pathname, prefix) {
+  if (/%(?:2f|5c)/i.test(pathname)) return false;
+  return pathname === prefix || pathname.startsWith(prefix.endsWith("/") ? prefix : `${prefix}/`);
+}
+
+// Recipes name a published file by its site path, which the broker resolves
+// to the file's public URL; the embedding fetches the copy its own release
+// holds (applicationBase).
+function normalizeTrustedSource(source, applicationBase) {
+  if (source === null || typeof source !== "object" ||
+      typeof source.path !== "string" || !source.path.startsWith("/") ||
+      !Number.isSafeInteger(source.byteLength) || source.byteLength <= 0) {
+    throw new TypeError("invalid trusted Dolly bootstrap source");
+  }
+  const url = new URL(source.path.slice(1), applicationBase);
+  if (!/^https?:$/.test(url.protocol) || url.search || url.hash) {
+    throw new TypeError("invalid trusted Dolly bootstrap source URL");
+  }
+  return Object.freeze({
+    href: url.href,
+    bootstrap: true,
+    maxRequestBytes: 1,
+    maxResponseBytes: source.byteLength,
+    timeoutMilliseconds: defaultLimits.timeoutMilliseconds,
+    credentialHeaders: new Set(),
+  });
+}
+
+// A relay is the embedding's transport for an origin whose responses the
+// browser will not let a page read (no CORS headers). The policy still judges
+// the real destination; an admitted request is then fetched from
+// `through` + host + path + query. The relay sees the whole request, so it gets
+// no credential header the embedding did not name for it.
+function normalizeRelay(relay) {
+  if (relay === null || typeof relay !== "object") throw new TypeError("invalid Dolly HTTP relay");
+  const origin = new URL(relay.origin).origin;
+  const through = new URL(relay.through);
+  if (origin !== relay.origin || !/^https?:$/.test(new URL(origin).protocol) ||
+      through.href !== relay.through || !/^https?:$/.test(through.protocol) ||
+      !through.pathname.endsWith("/") || through.search || through.hash ||
+      through.username || through.password) {
+    throw new TypeError("a Dolly HTTP relay maps an exact origin to an HTTP(S) URL prefix ending in /");
+  }
+  const credentialHeaders = new Set((relay.credentialHeaders ?? []).map((value) => {
+    const name = String(value).toLowerCase();
+    if (!credentialHeaderNames.has(name)) throw new TypeError(`invalid Dolly HTTP credential header: ${name}`);
+    return name;
+  }));
+  return [origin, Object.freeze({ through: through.href, credentialHeaders })];
+}
+
+// Where an admitted request for a relayed origin is fetched from.
+function relayUrl(relays, target, headers) {
+  const relay = relays.get(target.origin);
+  if (!relay) return undefined;
+  for (const name of credentialHeaderNames) {
+    if (!relay.credentialHeaders.has(name)) headers.delete(name);
+  }
+  return `${relay.through}${target.host}${target.pathname}${target.search}`;
+}
+
+export class DollyHttpPolicy {
+  constructor(configuration, trustedSources = [], applicationBase = globalThis.location?.href, relays = []) {
+    if (!Array.isArray(relays) || relays.length > 64) throw new TypeError("invalid Dolly HTTP relays");
+    this.relays = new Map(relays.map(normalizeRelay));
+    this.hardened = configuration !== undefined;
+    this.rules = this.hardened
+      ? Object.freeze((configuration.rules ?? []).map(normalizeRule))
+      : Object.freeze([]);
+    this.maxRequests = this.hardened ? positiveInteger(
+      configuration?.maxRequests,
+      defaultLimits.maxRequests,
+      "maxRequests",
+    ) : Infinity;
+    this.trustedSources = new Map(trustedSources.map((source) => {
+      const rule = normalizeTrustedSource(source, applicationBase);
+      return [rule.href, rule];
+    }));
+    // Each exact build input may be fetched a few times per page, not endlessly.
+    this.maxBootstrapRequests = this.hardened ? 4 * this.trustedSources.size : Infinity;
+    this.requests = 0;
+    this.bootstrapRequests = 0;
+  }
+
+  authorize(target, method, headers, requestBytes) {
+    const upperMethod = method.toUpperCase();
+    let rule = upperMethod === "GET" && requestBytes === 0 &&
+      target.username === "" && target.password === "" &&
+      target.search === "" && target.hash === ""
+      ? this.trustedSources.get(target.href)
+      : undefined;
+    if (rule) {
+      // The release's recipes and sources are build inputs selected by the
+      // embedding page and fetched from its own copy, not capabilities granted
+      // by an untrusted Dollyfile. They are exact, read-only, credential-free
+      // URLs with byte-for-byte response limits and their own quota, so a
+      // large source graph cannot exhaust agent requests.
+      if (++this.bootstrapRequests > this.maxBootstrapRequests) {
+        throw new HttpError(DOLLY_ERRNO.EDQUOT, "Dolly bootstrap source quota exceeded");
+      }
+      for (const name of credentialHeaderNames) headers.delete(name);
+    } else {
+      if (++this.requests > this.maxRequests) {
+        throw new HttpError(DOLLY_ERRNO.EDQUOT, "Dolly HTTP request quota exceeded");
+      }
+      if (this.hardened) {
+        rule = this.rules.find((candidate) =>
+          candidate.origin === target.origin &&
+          (candidate.path === null
+            ? pathWithin(target.pathname, candidate.pathPrefix)
+            : target.pathname === candidate.path) &&
+          candidate.methods.has(upperMethod));
+        if (!rule) throw new HttpError(DOLLY_ERRNO.EACCES, "Dolly HTTP policy denied the request");
+      } else {
+        rule = {
+          followRedirects: true,
+          credentialHeaders: null,
+          maxRequestBytes: defaultLimits.maxRequestBytes,
+          maxResponseBytes: defaultLimits.maxResponseBytes,
+          timeoutMilliseconds: defaultLimits.timeoutMilliseconds,
+        };
+      }
+    }
+    if (requestBytes > rule.maxRequestBytes) {
+      throw new HttpError(DOLLY_ERRNO.E2BIG, "Dolly HTTP request exceeds its size limit");
+    }
+
+    // Credentials are ordinary sandbox state. Development mode preserves
+    // them. A hardened destination rule must explicitly name which common
+    // credential headers may leave for that exact destination.
+    if (rule.credentialHeaders !== null) {
+      for (const name of credentialHeaderNames) {
+        if (!rule.credentialHeaders.has(name)) headers.delete(name);
+      }
+    }
+    const relay = rule.bootstrap ? undefined : relayUrl(this.relays, target, headers);
+    return relay ? { ...rule, followRedirects: false, relay } : rule;
+  }
+}
+
+// Trusted browser state for an explicitly opened result tab, never Wasm data.
+export function httpPolicyConfigurations(policy) {
+  if (policy.configurations) return policy.configurations;
+  return [policy.hardened ? { maxRequests: policy.maxRequests, rules: policy.rules.map(rule => ({
+    origin: rule.origin, ...(rule.path === null ? { pathPrefix: rule.pathPrefix } : { path: rule.path }),
+    methods: [...rule.methods], credentialHeaders: [...rule.credentialHeaders],
+    maxRequestBytes: rule.maxRequestBytes,
+    ...(Number.isFinite(rule.maxResponseBytes) ? { maxResponseBytes: rule.maxResponseBytes } : {}),
+    timeoutMilliseconds: rule.timeoutMilliseconds,
+  })) } : null];
+}
+
+export function restrictDollyHttpPolicy(policy, inherited, trustedSources, applicationBase) {
+  if (!Array.isArray(inherited) || inherited.length === 0 || inherited.length > 16 ||
+      new TextEncoder().encode(JSON.stringify(inherited)).byteLength > 65536) {
+    throw new Error("Invalid inherited image HTTP policy");
+  }
+  const configurations = [...new Set([...httpPolicyConfigurations(policy), ...inherited].map(value => JSON.stringify(value)))].map(value => JSON.parse(value));
+  const policies = configurations.map(configuration => new DollyHttpPolicy(configuration ?? undefined, trustedSources, applicationBase));
+  return {
+    configurations,
+    // Relays are this page's transport, not inherited authority.
+    relays: policy.relays,
+    authorize(target, method, headers, bytes) {
+      // Every policy must allow it. Sequential header stripping intersects
+      // credentials too; neither the parent nor the new embedding can widen it.
+      const rules = policies.map(policy => policy.authorize(target, method, headers, bytes));
+      const bootstrap = rules.every(rule => rule.bootstrap === true);
+      const relay = bootstrap ? undefined : relayUrl(policy.relays, target, headers);
+      return {
+        bootstrap,
+        ...(relay && { relay }),
+        followRedirects: !relay && rules.every(rule => rule.followRedirects === true),
+        maxRequestBytes: Math.min(...rules.map(rule => rule.maxRequestBytes)),
+        maxResponseBytes: Math.min(...rules.map(rule => rule.maxResponseBytes)),
+        timeoutMilliseconds: Math.min(...rules.map(rule => rule.timeoutMilliseconds)),
+      };
+    },
+  };
+}

package/host/modules.mjs

@@ -0,0 +1,373 @@
+import { hostRequirement, hostRequirements } from "./requirements.mjs";
+import { DOLLY_ERRNO as E } from "../src/process-constants.mjs";
+
+// What a build enables beside the runtime its image declares: the broker the
+// engine fetches sources through, the threads its toolchain uses and the
+// modules its compilers and interpreters load.
+export const buildHost = Object.freeze(["http@0", "threads@0", "dso@0"]);
+
+// A page's host modules, from the URLs of their manifests. The embedding, trusted
+// code, names them; images select no JS or Worker URLs, and each module's provider
+// is the file its manifest names. A runtime is a module that provides the kernel
+// (README.md); an image declares exactly one, by the same line as any module.
+export async function hostRegistry(urls) {
+  const definitions = await Promise.all(urls.map(async url => {
+    const { default: manifest } = await import(url, { with: { type: "json" } });
+    const contract = Object.freeze({ ...manifest, url });
+    return { ...await import(new URL(contract.host, url).href), contract };
+  }));
+  const byName = new Map(), owners = new Map();
+  for (const module of definitions) {
+    if (byName.has(module.contract.name)) throw new Error(`duplicate host module: ${module.contract.name}`);
+    byName.set(module.contract.name, module);
+    for (const name of module.contract.imports) {
+      if (owners.has(name)) throw new Error(`duplicate host import owner: ${name}`);
+      owners.set(name, module.contract.name);
+    }
+  }
+  const contracts = Object.freeze(definitions.map(module => module.contract));
+  const runtimes = Object.freeze(contracts.filter(contract => contract.provides === "kernel")
+    .map(({ name, version }) => `${name}@${version}`));
+  const registry = { byName, owners, contracts, runtimes };
+  return Object.freeze({
+    urls: Object.freeze([...urls]),
+    buildHostFor: declared => [...declared.filter(value => runtimes.includes(value)), ...buildHost],
+    selectBoot: route => selectBoot(definitions, route),
+    createHost: (...values) => createHost(registry, ...values),
+  });
+}
+
+// A module may select what a route boots, as a saved session names its image:
+// at most one does, and the page then requires it. The selection carries the
+// image, a bootstrap label, the custom image record it restores and the
+// module's configuration, keyed for createHost.
+async function selectBoot(definitions, route) {
+  let selection = null;
+  for (const module of definitions) {
+    const selected = await module.boot?.(route);
+    if (!selected) continue;
+    if (selection) throw new Error("two host modules selected the boot");
+    const { name, version } = module.contract;
+    selection = { ...selected, module: `${name}@${version}`, configuration: { [name]: selected.configuration } };
+  }
+  return selection;
+}
+
+async function createHost({ byName, owners, contracts, runtimes }, side, enabled,
+  { send, resources = {}, configuration = {} } = {}) {
+  if (!["browser", "worker"].includes(side)) throw new TypeError("invalid host side");
+  const selected = hostRequirements(enabled), instances = new Map(), reasons = new Map(), messages = new Map();
+  // The kernel is the one requested module that provides it; a module others
+  // only depend on does not make it one.
+  const kernels = selected.filter(value => runtimes.includes(value));
+  const started = new Set(), pending = new Map(), transfers = [], config = {};
+  // nena@0: the acknowledgements of the Worker's side of a switch, the
+  // switches in order, the context its providers start with and whether the
+  // image ENTRY has started.
+  const switched = new Map();
+  let switching = Promise.resolve(), startContext, entryContext;
+  // The page API (window.__dolly) by property descriptor, so module getters
+  // stay live; a child build host's configuration; what an opened result tab
+  // or restored session inherits from this page.
+  const page = {}, builder = {}, inherited = {};
+  // What executables may require: name@version -> the ABI digest its provider
+  // implements, for exactly the modules the image declares (see admit) and
+  // those its session enabled since (nena@0).
+  const admittedAbi = new Map();
+  let disposed = false;
+  // ask(message) sends a message to the other side and resolves to what its
+  // handler returns there (or rejects with what it throws).
+  const answers = new Map();
+  let asked = 0;
+  const ask = (message, transfers = []) => new Promise((resolve, reject) => {
+    if (disposed) return reject(new Error("host providers closed"));
+    answers.set(++asked, { resolve, reject });
+    send({ ...message, answer: asked }, transfers);
+  });
+  function requireModules(requirements) {
+    for (const value of hostRequirements(requirements)) {
+      const { name, version } = hostRequirement(value), module = byName.get(name);
+      const reason = !module ? "unknown host module" : module.contract.version !== version
+        ? `host provides ABI ${module.contract.version}` : reasons.get(name) ?? (!instances.has(name) ? "not enabled by the host" : null);
+      if (reason) throw new Error(`Required host module ${value} is unavailable: ${reason}`);
+    }
+  }
+  const get = name => instances.get(name);
+  // Page UI across modules: the first module that claims a key event takes it
+  // from the guest's input and may act on it; a module drawing over the
+  // display canvas reports the pixel size pointer input maps to.
+  function claimsKey(event) {
+    for (const instance of instances.values()) {
+      const claim = instance.claimsKey?.(event);
+      if (claim) return claim;
+    }
+    return false;
+  }
+  const surfaceSize = () => [...instances.values()].find(instance => instance.surfaceSize)?.surfaceSize;
+  async function attach(value, visiting = new Set(), checked = false) {
+    const { name, version } = hostRequirement(value), module = byName.get(name);
+    if (instances.has(name) || reasons.has(name)) return;
+    if (!module || version !== module.contract.version) {
+      reasons.set(name, !module ? "unknown host module" : `host provides ABI ${module.contract.version}`); return;
+    }
+    if (visiting.has(name)) throw new Error(`host module dependency cycle: ${name}`);
+    visiting.add(name);
+    for (const dependency of module.contract.dependencies) await attach(dependency, visiting);
+    visiting.delete(name);
+    try { requireModules(module.contract.dependencies); }
+    catch (error) { reasons.set(name, error.message); return; }
+    if (side === "browser" && !checked) {
+      const reason = await module.check?.(resources);
+      if (reason) { reasons.set(name, reason); return; }
+    }
+    const dependency = name => {
+      if (!module.contract.dependencies.some(value => hostRequirement(value).name === name)) {
+        throw new Error(`${module.contract.name} accessed undeclared dependency ${name}`);
+      }
+      return get(name);
+    };
+    const instance = module[side]?.({ ...resources, send, ask, get: dependency,
+      service: () => { for (const instance of instances.values()) instance.service?.(); },
+      claimsKey, surfaceSize,
+      abi: admittedAbi, modules: module.contract.switches && side === "browser" ? { list, enable, disable } : undefined,
+      configuration: configuration[name] ?? {} }) ?? {};
+    instances.set(name, instance);
+    for (const [type, handler] of Object.entries(instance.messages ?? {})) {
+      if (messages.has(type)) throw new Error(`duplicate host message: ${type}`);
+      messages.set(type, handler);
+    }
+    config[name] = instance.configuration ?? {};
+    transfers.push(...instance.transfers ?? []);
+    for (const [key, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(instance.page ?? {}))) {
+      if (key in page) throw new Error(`duplicate page API member: ${key}`);
+      Object.defineProperty(page, key, descriptor);
+    }
+    if (instance.builder) builder[name] = instance.builder;
+    for (const [key, value] of Object.entries(instance.inherited ?? {})) {
+      if (key in inherited) throw new Error(`duplicate inherited record: ${key}`);
+      inherited[key] = value;
+    }
+  }
+  // What attach registered for one module, undone. Its provider lets go first,
+  // as when the page ends, and then of what a runtime that goes on must not
+  // keep: a service it registered, the thread provider.
+  function detach(name) {
+    const instance = instances.get(name);
+    instance.dispose?.();
+    instance.disabled?.();
+    for (const type of Object.keys(instance.messages ?? {})) messages.delete(type);
+    for (const key of Object.keys(instance.page ?? {})) delete page[key];
+    for (const key of Object.keys(instance.inherited ?? {})) delete inherited[key];
+    delete builder[name];
+    delete config[name];
+    instances.delete(name);
+    started.delete(name);
+    admittedAbi.delete(`${name}@${byName.get(name).contract.version}`);
+  }
+  // The Worker's side of a module starts once; a descriptor it returns is the
+  // page side's to acknowledge.
+  async function startProvider(name, instance, context) {
+    if (started.has(name)) throw new Error(`host provider ${name} initialized twice`);
+    started.add(name);
+    const descriptor = await instance.start(context);
+    if (descriptor === undefined) return;
+    await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => { pending.delete(name); reject(new Error(`host provider ${name} did not acknowledge initialization`)); }, 10_000);
+      pending.set(name, { resolve: () => { clearTimeout(timer); resolve(); }, reject: error => { clearTimeout(timer); reject(error); } });
+      send({ type: "host-ready", module: name, descriptor });
+    });
+  }
+  // Switching a module after boot, for the page side of the one module whose
+  // manifest says `switches` (nena@0): an image without that module has no
+  // caller, so its set stays what the page chose.
+  // The page decides and goes first when enabling, last when disabling; the
+  // Worker's side follows by message. Each resolves to null, or to one line
+  // saying why not. A module whose manifest says `fixed` is never switched;
+  // the modules others depend on (runtime@0, http@0) are among them.
+  const requirementOf = ({ name, version }) => `${name}@${version}`;
+  const list = () => contracts.map(contract => ({ name: contract.name, version: contract.version,
+    gives: contract.gives ?? "", fixed: contract.fixed ?? "", enabled: instances.has(contract.name),
+    declared: selected.includes(requirementOf(contract)) }));
+  // Enabling hands the Worker's side what boot would have: the page side's
+  // configuration and what it transfers, such as a canvas.
+  const workerSwitch = (value, enabling, name = hostRequirement(value).name) => new Promise(resolve => {
+    switched.set(value, resolve);
+    if (enabling) send({ type: "host-switch", module: value, enabling, configuration: config[name] }, instances.get(name).transfers ?? []);
+    else send({ type: "host-switch", module: value, enabling });
+  });
+  const serially = task => switching = switching.then(task, task);
+  const enable = value => serially(async () => {
+    const { name, version } = hostRequirement(value), module = byName.get(name);
+    if (!module || module.contract.version !== version) return "this page has no such host module";
+    if (instances.has(name)) return null;
+    if (module.contract.fixed) return `fixed: ${module.contract.fixed}`;
+    const missing = module.contract.dependencies.find(dependency => !instances.has(hostRequirement(dependency).name));
+    if (missing) return `it needs ${missing}`;
+    reasons.delete(name);
+    try {
+      // A browser that never answers a module's check must not hold every
+      // later switch: after five seconds the switch is refused and the check
+      // told so, that an answer coming later shows nothing on the page.
+      const abandoned = new AbortController(), timer = setTimeout(() => abandoned.abort(), 5000);
+      const unavailable = await Promise.race([module.check?.({ ...resources, signal: abandoned.signal }), new Promise(resolve =>
+        abandoned.signal.addEventListener("abort", () => resolve("the browser did not answer in time")))]);
+      clearTimeout(timer);
+      if (unavailable) return unavailable;
+      await attach(value, new Set(), true);
+      if (!instances.has(name)) return reasons.get(name);
+      const refusal = await workerSwitch(value, true);
+      if (refusal) { detach(name); return refusal; }
+      if (entryContext) await instances.get(name).entryStarted?.(entryContext);
+    } catch (error) {
+      if (instances.has(name)) { await workerSwitch(value, false); detach(name); }
+      return error.message;
+    }
+    return null;
+  });
+  const disable = value => serially(async () => {
+    const { name, version } = hostRequirement(value), module = byName.get(name);
+    if (!module || module.contract.version !== version) return "this page has no such host module";
+    if (!instances.has(name)) return null;
+    if (module.contract.fixed) return `fixed: ${module.contract.fixed}`;
+    const refusal = await workerSwitch(value, false);
+    if (refusal) return refusal;
+    detach(name);
+    return null;
+  });
+  function dispose() {
+    if (disposed) return;
+    disposed = true;
+    for (const wait of [...pending.values(), ...answers.values()]) wait.reject(new Error("host providers closed"));
+    pending.clear();
+    answers.clear();
+    for (const instance of [...instances.values()].reverse()) instance.dispose?.();
+  }
+  try {
+    for (const value of selected) await attach(value);
+    if (kernels.length !== 1) {
+      // A requested module this page lacks may be the runtime the image declares.
+      requireModules(selected);
+      throw new Error(kernels.length ? `${kernels.join(" and ")} both provide the kernel`
+        : `no enabled host module provides the kernel: add REQUIRES HOST ${runtimes.join(" or ")}`);
+    }
+    requireModules(kernels);
+  } catch (error) { dispose(); throw error; }
+  const kernel = hostRequirement(kernels[0]).name;
+  return {
+    transfers, configuration: config, page, builder, inherited,
+    kernel: instances.get(kernel),
+    get enabled() { return [...instances.keys()].map(name => requirementOf(byName.get(name).contract)); },
+    require: requireModules, dispose,
+    // Executables may use only the modules the image declares. A declared module
+    // this host does not enable (a build host) answers its calls with ENOSYS.
+    admit(requirements) {
+      admittedAbi.clear();
+      for (const value of hostRequirements(requirements)) {
+        const { name, version } = hostRequirement(value), module = byName.get(name);
+        if (module?.digest && module.contract.version === version) admittedAbi.set(value, module.digest);
+      }
+    },
+    // The Worker calls this after restoring the system image and before starting
+    // image-phase modules, in registry order.
+    async imageRestored(context) {
+      for (const instance of instances.values()) await instance.imageRestored?.(context);
+    },
+    // The page calls this once the image ENTRY may run, right before it lets
+    // the Worker start it: modules may then show their UI and admit services.
+    entryStarted(context) {
+      entryContext = context;
+      return Promise.all([...instances.values()].map(instance => instance.entryStarted?.(context)));
+    },
+    // The page asks this when the image has ended, before it lets go of the
+    // modules: the links ({ text, href }) each one offers beside "start again".
+    ended: () => [...instances.values()].flatMap(instance => instance.ended?.() ?? []),
+    // The kernel's whole import object: each import is the binding of the
+    // module whose manifest owns it.
+    imports(module) {
+      const imports = {};
+      for (const entry of WebAssembly.Module.imports(module)) {
+        const name = `${entry.module}.${entry.name}`, owner = owners.get(name);
+        // The import of a module this page does not have answers as a disabled one does.
+        if (!owner) { (imports[entry.module] ??= {})[entry.name] = () => -E.ENOSYS; continue; }
+        const binding = instances.has(owner) ? instances.get(owner).bindings?.[name] : () => -E.ENOSYS;
+        if (binding === undefined) throw new Error(`missing host binding: ${name}`);
+        // The kernel is instantiated once. An import of a module that can be
+        // switched asks at each call who answers it now; a disabled one is ENOSYS.
+        (imports[entry.module] ??= {})[entry.name] = byName.get(owner).contract.fixed ? binding
+          : (...values) => instances.has(owner) ? instances.get(owner).bindings[name](...values) : -E.ENOSYS;
+      }
+      return imports;
+    },
+    async handle(message) {
+      if (disposed) return false;
+      if (message.type === "host-ready-ack" && side === "worker") {
+        const wait = pending.get(message.module);
+        if (!wait) throw new Error("unexpected host acknowledgement");
+        pending.delete(message.module);
+        if (message.error) wait.reject(new Error(message.error)); else wait.resolve();
+        return true;
+      }
+      if (message.type === "host-ready" && side === "browser") {
+        try {
+          const instance = get(message.module);
+          if (!instance?.start || started.has(message.module)) throw new Error("invalid host provider handshake");
+          started.add(message.module);
+          await instance.start(message.descriptor);
+          send({ type: "host-ready-ack", module: message.module });
+        } catch (error) {
+          send({ type: "host-ready-ack", module: message.module, error: error.message });
+          throw error;
+        }
+        return true;
+      }
+      if (message.type === "host-switch" && side === "worker") {
+        const { name } = hostRequirement(message.module);
+        let refusal = null;
+        try {
+          if (message.enabling) {
+            configuration[name] = message.configuration;
+            reasons.delete(name);
+            await attach(message.module);
+            const instance = instances.get(name);
+            if (!instance) throw new Error(reasons.get(name));
+            if (instance.start) await startProvider(name, instance, startContext);
+            const { digest } = byName.get(name);
+            if (digest) admittedAbi.set(message.module, digest);
+          } else if (instances.has(name)) detach(name);
+        } catch (error) {
+          if (instances.has(name)) detach(name);
+          refusal = error.message;
+        }
+        send({ type: "host-switch-ack", module: message.module, refusal });
+        return true;
+      }
+      if (message.type === "host-switch-ack" && side === "browser") {
+        switched.get(message.module)?.(message.refusal);
+        switched.delete(message.module);
+        return true;
+      }
+      if (message.type === "host-answer") {
+        const waiting = answers.get(message.answer);
+        answers.delete(message.answer);
+        if (message.error === undefined) waiting?.resolve(message.result); else waiting?.reject(new Error(message.error));
+        return true;
+      }
+      const handler = messages.get(message.type);
+      if (!handler) return false;
+      if (message.answer === undefined) {
+        await handler(message);
+        return true;
+      }
+      try { send({ type: "host-answer", answer: message.answer, result: await handler(message) }); }
+      catch (error) { send({ type: "host-answer", answer: message.answer, error: error.message }); }
+      return true;
+    },
+    async start(phase, context) {
+      if (side !== "worker" || disposed) throw new Error("host cannot initialize providers");
+      startContext = context;
+      for (const [name, instance] of [...instances]) {
+        if (byName.get(name).contract.phase === phase && instance.start) await startProvider(name, instance, context);
+      }
+    },
+  };
+}