@daugasauron/dolly 0.1.5-rc.0 → 0.1.6

package/host/dso/dso.mjs

@@ -1,4 +1,4 @@
-import { parseWasmInterface } from "../../src/wasm-interface.mjs";
+import { parseWasmInterface } from "../../page/wasm-interface.mjs";
 export { DOLLY_DSO_ABI_DIGEST as digest } from "./abi.mjs";
 
 // The loader and the FFI dispatcher (process.mjs) run inside the process Worker
@@ -10,7 +10,7 @@ export function worker({ get, abi, runtimeBase }) {
     async start() {
       const [contract, bundle] = await Promise.all(["dolly-dso-0.wasm", "dolly-process-dso.mjs"].map(async name => {
         const response = await fetch(new URL(`dist/${name}`, runtimeBase), {
-          cache: "no-store", credentials: "same-origin", redirect: "error",
+          credentials: "same-origin", redirect: "error",
         });
         if (!response.ok) throw new Error(`Dolly ${name} returned HTTP ${response.status}`);
         return response.arrayBuffer();

package/host/dso/module.json

@@ -1,6 +1,7 @@
 {
   "name": "dso",
   "version": 0,
+  "build": true,
   "gives": "dlopen and FFI in the process's own Worker",
   "dependencies": ["runtime@0"],
   "phase": "kernel",
@@ -11,5 +12,7 @@
   "process": ["dolly-dso-0.wat"],
   "headers": ["dso.h", "dso-abi.h"],
   "kernel": [],
-  "client": ["client.c", "ffi.c"]
+  "client": ["client.c", "ffi.c"],
+  "ccExports": { "rdynamic": ["__dolly_dso_allocate"] },
+  "fixtures": "../../test/build-dso-fixtures.mjs"
 }

package/host/http/abi.mjs

@@ -24,5 +24,7 @@ export const DOLLY_HTTP_START = 80;
 export const DOLLY_HTTP_POLL = 81;
 export const DOLLY_HTTP_CANCEL = 82;
 export const DOLLY_HTTP_BODY_WRITE = 83;
+export const DOLLY_HTTP_FAIL_STATUS = 1;
+export const DOLLY_HTTP_FOLLOW_REDIRECTS = 2;
 export const DOLLY_ERRNO = Object.freeze({ E2BIG: 1, EACCES: 2, EADDRINUSE: 3, EADDRNOTAVAIL: 4, EAFNOSUPPORT: 5, EAGAIN: 6, EALREADY: 7, EBADF: 8, EBADMSG: 9, EBUSY: 10, ECANCELED: 11, ECHILD: 12, ECONNABORTED: 13, ECONNREFUSED: 14, ECONNRESET: 15, EDEADLK: 16, EDESTADDRREQ: 17, EDOM: 18, EDQUOT: 19, EEXIST: 20, EFAULT: 21, EFBIG: 22, EHOSTUNREACH: 23, EIDRM: 24, EILSEQ: 25, EINPROGRESS: 26, EINTR: 27, EINVAL: 28, EIO: 29, EISCONN: 30, EISDIR: 31, ELOOP: 32, EMFILE: 33, EMLINK: 34, EMSGSIZE: 35, EMULTIHOP: 36, ENAMETOOLONG: 37, ENETDOWN: 38, ENETRESET: 39, ENETUNREACH: 40, ENFILE: 41, ENOBUFS: 42, ENODEV: 43, ENOENT: 44, ENOEXEC: 45, ENOLCK: 46, ENOLINK: 47, ENOMEM: 48, ENOMSG: 49, ENOPROTOOPT: 50, ENOSPC: 51, ENOSYS: 52, ENOTCONN: 53, ENOTDIR: 54, ENOTEMPTY: 55, ENOTRECOVERABLE: 56, ENOTSOCK: 57, ENOTTY: 59, ENXIO: 60, EOVERFLOW: 61, EOWNERDEAD: 62, EPERM: 63, EPIPE: 64, EPROTO: 65, EPROTONOSUPPORT: 66, EPROTOTYPE: 67, ERANGE: 68, EROFS: 69, ESPIPE: 70, ESRCH: 71, ESTALE: 72, ETIMEDOUT: 73, ETXTBSY: 74, EXDEV: 75, ENODATA: 116, ENOTSUP: 138 });
-export const DOLLY_HTTP_ABI_DIGEST = "9e3dd4f36f656a23f477c67ce6fe723130caa9b4bf69f6af8670859ea653470f";
+export const DOLLY_HTTP_ABI_DIGEST = "fc788cef38bb5cd423369a5c12c274fa6203ff14eef72540347e778236986aee";

package/host/http/broker.mjs

@@ -1,11 +1,12 @@
 import { HttpError, isDollyCredentialHeader, stripDollyBrowserOwnedHeaders } from "./policy.mjs";
 import { DOLLY_ERRNO as errno } from "./abi.mjs";
-import { decodeStaticAsset, sitePath } from "../../src/static-asset.mjs";
+import { decodeStaticAsset, sitePath } from "../../page/static-asset.mjs";
 import { DOLLY_HTTP_SLOT_COUNT, DOLLY_HTTP_CHUNK_CAPACITY, DOLLY_HTTP_MAX_METHOD, DOLLY_HTTP_MAX_URL,
   DOLLY_HTTP_MAX_HEADERS, DOLLY_HTTP_MAX_BODY, DOLLY_HTTP_HEADER_SIZE, DOLLY_HTTP_WORD_SEQUENCE,
   DOLLY_HTTP_WORD_STATUS, DOLLY_HTTP_WORD_LENGTH, DOLLY_HTTP_WORD_EOF, DOLLY_HTTP_WORD_ERROR,
   DOLLY_HTTP_WORD_KIND, DOLLY_HTTP_STATE_WRITABLE, DOLLY_HTTP_STATE_READABLE, DOLLY_HTTP_STATE_FAILED,
-  DOLLY_HTTP_KIND_URL, DOLLY_HTTP_KIND_HEADER, DOLLY_HTTP_KIND_BODY } from "./abi.mjs";
+  DOLLY_HTTP_KIND_URL, DOLLY_HTTP_KIND_HEADER, DOLLY_HTTP_KIND_BODY, DOLLY_HTTP_FAIL_STATUS,
+  DOLLY_HTTP_FOLLOW_REDIRECTS } from "./abi.mjs";
 
 const encoder = new TextEncoder();
 const now = () => performance.timeOrigin + performance.now();
@@ -54,7 +55,7 @@ export class HttpMailbox {
         message.flags === 0 };
     }
     try {
-      if (!(memory instanceof SharedArrayBuffer) || (message.flags & ~3) !== 0)
+      if (!(memory instanceof SharedArrayBuffer) || (message.flags & ~(DOLLY_HTTP_FAIL_STATUS | DOLLY_HTTP_FOLLOW_REDIRECTS)) !== 0)
         throw new HttpError(errno.EINVAL, "invalid HTTP admission");
       const spans = {};
       for (const [name, maximum] of Object.entries(DOLLY_HTTP_LIMITS)) {
@@ -127,13 +128,15 @@ export class HttpMailbox {
 // The page's broker: policy, Fetch and the slots' bookkeeping. It never reads
 // kernel memory: `mailbox` (HttpMailbox, or messages to it) writes the slots.
 export class NetworkTransport {
-  // `site` is the URL of the root of the site serving this release, if any.
-  constructor(mailbox, policy, { fetchRequest = globalThis.fetch.bind(globalThis), site } = {}) {
+  // `site` is the URL of the root of the site serving this release, if any;
+  // `refused({ method, target, reason })` hears of each request the policy refuses.
+  constructor(mailbox, policy, { fetchRequest = globalThis.fetch.bind(globalThis), site, refused } = {}) {
     this.mailbox = mailbox;
     this.capacity = DOLLY_HTTP_CHUNK_CAPACITY;
     this.policy = policy;
     this.fetchRequest = fetchRequest;
     this.site = site;
+    this.refused = refused;
     // Host bookkeeping, never derived from a guest's claimed active count.
     this.slots = Array(DOLLY_HTTP_SLOT_COUNT).fill(null);
     this.closed = false;
@@ -278,7 +281,14 @@ class HttpTransfer {
       }
       stripDollyBrowserOwnedHeaders(headers);
       const upperMethod = method.toUpperCase();
-      const rule = this.broker.policy.authorize(target, upperMethod, headers, body?.byteLength ?? 0);
+      let rule;
+      try { rule = this.broker.policy.authorize(target, upperMethod, headers, body?.byteLength ?? 0); }
+      catch (error) {
+        if (error instanceof HttpError && [errno.EACCES, errno.EDQUOT].includes(error.errno)) {
+          this.broker.refused?.({ method: upperMethod, target, reason: error.message });
+        }
+        throw error;
+      }
       this.timeout = rule.timeoutMilliseconds;
       this.moved();
       failure = errno.EIO;
@@ -286,7 +296,7 @@ class HttpTransfer {
         method: upperMethod, headers,
         body: body === null || upperMethod === "GET" || upperMethod === "HEAD" ? undefined : body,
         credentials: "omit",
-        redirect: (flags & 2) && rule.followRedirects === true ? "follow" : "error",
+        redirect: (flags & DOLLY_HTTP_FOLLOW_REDIRECTS) && rule.followRedirects === true ? "follow" : "error",
         referrerPolicy: "no-referrer",
         signal: this.controller.signal,
       };

package/host/http/http.mjs

@@ -1,15 +1,17 @@
 import { createHttpAdmission, HttpMailbox, NetworkTransport } from "./broker.mjs";
 import { DollyHttpPolicy, httpPolicyConfigurations, restrictDollyHttpPolicy } from "./policy.mjs";
 import { localServicesTransport } from "./local-services.mjs";
+import { refusalNotices } from "./refusals.mjs";
 export { DOLLY_HTTP_ABI_DIGEST as digest } from "./abi.mjs";
 
 // The page takes the embedding's policy once, with the image directory's
 // trusted sources and, in a custom tab, the policies it inherited; a builder or
 // headless host is given its network instead. Modules depending on http@0 add
-// their local services to `services`.
-export function browser({ applicationBase, configuration, send, ask }) {
+// their local services to `services`. Each request the policy refuses is a line in the
+// console and a notice on the page (refusals.mjs).
+export function browser({ applicationBase, configuration, mount, keyboard, send, ask }) {
   let transport, admission, network = configuration.network;
-  const services = {};
+  const services = {}, refusals = refusalNotices(mount, keyboard);
   const instance = {
     services,
     page: {
@@ -25,7 +27,8 @@ export function browser({ applicationBase, configuration, send, ask }) {
       // The Worker writes the records into the guest's slots.
       const mailbox = { publish: record => ask({ type: "http-publish", ...record }, [record.bytes.buffer]),
         fail: ending => send({ type: "http-fail", ...ending }) };
-      transport = new NetworkTransport(mailbox, network.policy, { fetchRequest: network.fetchRequest, site: network.site });
+      transport = new NetworkTransport(mailbox, network.policy, { fetchRequest: network.fetchRequest, site: network.site,
+        refused: refusals.refused });
     },
     messages: {
       async "http-request"(message) {
@@ -36,7 +39,18 @@ export function browser({ applicationBase, configuration, send, ask }) {
         Atomics.notify(admission, 0);
       },
     },
-    dispose() { transport?.close(); },
+    // A GET a host module makes for the guest, judged by the page's policy as
+    // the guest's own requests are, and shown as theirs when refused.
+    admit(url) {
+      try {
+        network.policy.authorize(url, "GET", new Headers(), 0);
+      } catch (error) {
+        refusals.refused({ method: "GET", target: url, reason: error.message });
+        throw error;
+      }
+    },
+    claimsKey: refusals.claimsKey,
+    dispose() { transport?.close(); refusals.dispose(); },
   };
   if (!network) {
     // A custom tab intersects the policy of the page that built it with its

package/host/http/module.json

@@ -1,6 +1,7 @@
 {
   "name": "http",
   "version": 0,
+  "build": true,
   "gives": "HTTP(S) requests under the page's policy",
   "fixed": "the page's HTTP policy is consumed once, at load",
   "dependencies": ["runtime@0"],
@@ -11,5 +12,6 @@
   "process": [],
   "headers": ["http.h", "http-abi.h"],
   "kernel": ["kernel.c"],
-  "client": ["client.c"]
+  "client": ["client.c"],
+  "tools": ["libcurl.c"]
 }

package/host/http/policy.mjs

@@ -27,6 +27,13 @@ const browserOwnedTransportHeaderNames = new Set([
   "user-agent",
 ]);
 
+// What an ordinary request carries: under a hardened rule these and the
+// headers the rule names leave the sandbox, and nothing else does, a token in
+// a header of any other name included.
+const ordinaryHeaderNames = new Set(["accept", "accept-language", "content-encoding", "content-language", "content-type",
+  "range", "if-match", "if-none-match", "if-modified-since", "if-unmodified-since", "if-range",
+  "cache-control", "pragma"]);
+
 export function isDollyCredentialHeader(name) {
   return credentialHeaderNames.has(String(name).toLowerCase());
 }
@@ -86,8 +93,8 @@ function normalizeRule(rule) {
   }
   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}`);
+    if (!/^[!#$%&'*+.^_`|~0-9a-z-]+$/.test(name)) {
+      throw new TypeError(`invalid Dolly HTTP header name: ${name}`);
     }
     return name;
   }));
@@ -243,11 +250,11 @@ export class DollyHttpPolicy {
     }
 
     // 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.
+    // them. A hardened destination rule names every header beyond an
+    // ordinary request's that may leave for that exact destination.
     if (rule.credentialHeaders !== null) {
-      for (const name of credentialHeaderNames) {
-        if (!rule.credentialHeaders.has(name)) headers.delete(name);
+      for (const name of [...headers.keys()]) {
+        if (!ordinaryHeaderNames.has(name) && !rule.credentialHeaders.has(name)) headers.delete(name);
       }
     }
     const relay = rule.bootstrap ? undefined : relayUrl(this.relays, target, headers);

package/host/http/refusals.mjs

@@ -0,0 +1,77 @@
+// What the HTTP policy refuses, for whoever runs the page: each refusal is a line in the
+// browser's console, and a notice in boot()'s element that stays until the user closes it.
+// Refusals of one method and URL are one notice with a count; the newest few show, with a
+// line for the rest and Close all. A URL is shown without its query, which may hold a key.
+// The list lies over the display: its words let the pointer through to the program, and only
+// its buttons take a click.
+const shownAtOnce = 5;
+
+const style = `
+  #http-refusals { position: absolute; left: 0.6rem; top: 0.6rem; z-index: 7; width: min(34rem, calc(100% - 1.2rem));
+    margin: 0; padding: 0.35rem 0.35rem 0; list-style: none; color: var(--dolly-ui-color); background: var(--dolly-ui-background); font-size: 14px; line-height: 1.4;
+    pointer-events: none; }
+  #http-refusals[hidden] { display: none; }
+  #http-refusals li { display: flex; gap: 0.5rem; align-items: baseline; margin-bottom: 0.35rem; padding: 0.4rem 0.5rem;
+    background: var(--dolly-ui-background); border: 1px solid var(--dolly-ui-alert); overflow-wrap: anywhere; }
+  #http-refusals li span { flex: 1; }
+  #http-refusals li.rest { border-color: var(--dolly-ui-quiet); }
+  #http-refusals button { color: inherit; background: var(--dolly-ui-raised); border: 1px solid var(--dolly-ui-quiet); font: inherit; cursor: pointer;
+    pointer-events: auto; }
+`;
+
+export function refusalNotices(mount, keyboard) {
+  const notices = new Map();
+  let list, look;
+  if (mount) {
+    look = new CSSStyleSheet();
+    look.replaceSync(style);
+    document.adoptedStyleSheets = [...document.adoptedStyleSheets, look];
+    list = mount.appendChild(Object.assign(document.createElement("ul"), { id: "http-refusals", hidden: true }));
+    list.setAttribute("role", "status");
+    list.setAttribute("aria-label", "Requests the HTTP policy refused");
+  }
+  const button = (label, name, press) => {
+    const element = Object.assign(document.createElement("button"), { type: "button", textContent: label });
+    element.setAttribute("aria-label", name);
+    element.addEventListener("click", () => {
+      press();
+      render();
+      keyboard?.focus({ preventScroll: true });
+    });
+    return element;
+  };
+  function render() {
+    const newest = [...notices].reverse(), shown = newest.slice(0, shownAtOnce);
+    list.replaceChildren(...shown.map(([key, { text, count }]) => {
+      const item = document.createElement("li"), words = document.createElement("span");
+      words.textContent = `The HTTP policy refused ${text}${count > 1 ? ` (${count} times)` : ""}`;
+      item.append(words, button("×", `Close: ${text}`, () => notices.delete(key)));
+      return item;
+    }));
+    if (notices.size > 1) {
+      const rest = document.createElement("li"), words = document.createElement("span");
+      rest.className = "rest";
+      const hidden = notices.size - shown.length;
+      words.textContent = hidden ? `${hidden} more refused (the console lists every one)` : "";
+      rest.append(words, button("Close all", "Close all refusals", () => notices.clear()));
+      list.append(rest);
+    }
+    list.hidden = notices.size === 0;
+  }
+  return {
+    refused({ method, target, reason }) {
+      const text = `${method} ${target.origin}${target.pathname}`;
+      console.warn(`${reason}: ${text}`);
+      if (!list) return;
+      const notice = notices.get(text);
+      notices.delete(text);
+      notices.set(text, { text, count: (notice?.count ?? 0) + 1 });
+      render();
+    },
+    claimsKey: event => list?.contains(event.target) ?? false,
+    dispose() {
+      list?.remove();
+      if (look) document.adoptedStyleSheets = document.adoptedStyleSheets.filter(sheet => sheet !== look);
+    },
+  };
+}

package/host/input/abi.mjs

@@ -44,4 +44,4 @@ export const DOLLY_INPUT_NEXT_EVENT = 89;
 export const DOLLY_INPUT_SET_POINTER = 90;
 export const DOLLY_INPUT_RELEASE = 91;
 export const DOLLY_ERRNO = Object.freeze({ E2BIG: 1, EACCES: 2, EADDRINUSE: 3, EADDRNOTAVAIL: 4, EAFNOSUPPORT: 5, EAGAIN: 6, EALREADY: 7, EBADF: 8, EBADMSG: 9, EBUSY: 10, ECANCELED: 11, ECHILD: 12, ECONNABORTED: 13, ECONNREFUSED: 14, ECONNRESET: 15, EDEADLK: 16, EDESTADDRREQ: 17, EDOM: 18, EDQUOT: 19, EEXIST: 20, EFAULT: 21, EFBIG: 22, EHOSTUNREACH: 23, EIDRM: 24, EILSEQ: 25, EINPROGRESS: 26, EINTR: 27, EINVAL: 28, EIO: 29, EISCONN: 30, EISDIR: 31, ELOOP: 32, EMFILE: 33, EMLINK: 34, EMSGSIZE: 35, EMULTIHOP: 36, ENAMETOOLONG: 37, ENETDOWN: 38, ENETRESET: 39, ENETUNREACH: 40, ENFILE: 41, ENOBUFS: 42, ENODEV: 43, ENOENT: 44, ENOEXEC: 45, ENOLCK: 46, ENOLINK: 47, ENOMEM: 48, ENOMSG: 49, ENOPROTOOPT: 50, ENOSPC: 51, ENOSYS: 52, ENOTCONN: 53, ENOTDIR: 54, ENOTEMPTY: 55, ENOTRECOVERABLE: 56, ENOTSOCK: 57, ENOTTY: 59, ENXIO: 60, EOVERFLOW: 61, EOWNERDEAD: 62, EPERM: 63, EPIPE: 64, EPROTO: 65, EPROTONOSUPPORT: 66, EPROTOTYPE: 67, ERANGE: 68, EROFS: 69, ESPIPE: 70, ESRCH: 71, ESTALE: 72, ETIMEDOUT: 73, ETXTBSY: 74, EXDEV: 75, ENODATA: 116, ENOTSUP: 138 });
-export const DOLLY_INPUT_ABI_DIGEST = "862edb42d7dbb04c1c49411d740a97503fe387678a1b660f19b3b2dc4f18b9c6";
+export const DOLLY_INPUT_ABI_DIGEST = "6bdd3f083670e13711d45c6bb787d6a6545ccee2c60d6de2ba9111780fc6c174";

package/host/modules.mjs

@@ -1,11 +1,5 @@
 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, the
-// modules its compilers and interpreters load and the fresh stacks of the
-// tools stack-wrap rewrote.
-export const buildHost = Object.freeze(["http@0", "threads@0", "dso@0", "stack@0"]);
+import { DOLLY_ERRNO as E } from "../page/process-constants.mjs";
 
 // 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
@@ -15,7 +9,10 @@ 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 };
+    // A module's provider is imported when the page or a Worker first needs it:
+    // its module attached or admitted, or a session route's boot selected.
+    let provider;
+    return { contract, provider: () => provider ??= import(new URL(contract.host, url).href) };
   }));
   const byName = new Map(), owners = new Map();
   for (const module of definitions) {
@@ -27,25 +24,30 @@ export async function hostRegistry(urls) {
     }
   }
   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 requirementsOf = keep => Object.freeze(contracts.filter(keep).map(({ name, version }) => `${name}@${version}`));
+  const runtimes = requirementsOf(contract => contract.provides === "kernel");
+  // What a build enables beside the runtime its image declares: the modules
+  // whose manifests say `build` (README.md).
+  const buildHost = requirementsOf(contract => contract.build);
   const registry = { byName, owners, contracts, runtimes };
   return Object.freeze({
     urls: Object.freeze([...urls]),
     buildHostFor: declared => [...declared.filter(value => runtimes.includes(value)), ...buildHost],
+    load: values => loadProviders(byName, values),
     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
+// A module may select what a session 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) {
+  if (!route.loadSession) return null;
   let selection = null;
   for (const module of definitions) {
-    const selected = await module.boot?.(route);
+    const selected = await (await module.provider()).boot?.(route);
     if (!selected) continue;
     if (selection) throw new Error("two host modules selected the boot");
     const { name, version } = module.contract;
@@ -54,6 +56,18 @@ async function selectBoot(definitions, route) {
   return selection;
 }
 
+// The providers of these modules and their dependencies start loading together; createHost
+// attaches them in order.
+function loadProviders(byName, values, seen = new Set()) {
+  for (const value of values) {
+    const { name, version } = hostRequirement(value), module = byName.get(name);
+    if (seen.has(name) || module?.contract.version !== version) continue;
+    seen.add(name);
+    module.provider().catch(() => {});
+    loadProviders(byName, module.contract.dependencies, seen);
+  }
+}
+
 async function createHost({ byName, owners, contracts, runtimes }, side, enabled,
   { send, resources = {}, configuration = {} } = {}) {
   if (!["browser", "worker"].includes(side)) throw new TypeError("invalid host side");
@@ -96,7 +110,7 @@ async function createHost({ byName, owners, contracts, runtimes }, side, enabled
   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.
+  // display canvas reports the pixel size of its frame.
   function claimsKey(event) {
     for (const instance of instances.values()) {
       const claim = instance.claimsKey?.(event);
@@ -105,6 +119,15 @@ async function createHost({ byName, owners, contracts, runtimes }, side, enabled
     return false;
   }
   const surfaceSize = () => [...instances.values()].find(instance => instance.surfaceSize)?.surfaceSize;
+  // A pointer's position in pixels of the frame shown, which the canvas fits
+  // within its box at the frame's own shape, centred (object-fit: contain).
+  function framePoint({ clientX, clientY }) {
+    const bounds = resources.canvas.getBoundingClientRect(), { width, height } = surfaceSize() ?? resources.canvas;
+    const scale = Math.min(bounds.width / width, bounds.height / height);
+    if (!(scale > 0)) return { x: 0, y: 0 };
+    return { x: (clientX - bounds.left - (bounds.width - width * scale) / 2) / scale,
+      y: (clientY - bounds.top - (bounds.height - height * scale) / 2) / scale };
+  }
   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;
@@ -117,8 +140,9 @@ async function createHost({ byName, owners, contracts, runtimes }, side, enabled
     visiting.delete(name);
     try { requireModules(module.contract.dependencies); }
     catch (error) { reasons.set(name, error.message); return; }
+    const provider = await module.provider();
     if (side === "browser" && !checked) {
-      const reason = await module.check?.(resources);
+      const reason = await provider.check?.(resources);
       if (reason) { reasons.set(name, reason); return; }
     }
     const dependency = name => {
@@ -127,9 +151,10 @@ async function createHost({ byName, owners, contracts, runtimes }, side, enabled
       }
       return get(name);
     };
-    const instance = module[side]?.({ ...resources, send, ask, get: dependency,
+    // `switched`: the page enabled the module after boot (nena@0), not the image.
+    const instance = provider[side]?.({ ...resources, switched: checked, send, ask, get: dependency,
       service: () => { for (const instance of instances.values()) instance.service?.(); },
-      claimsKey, surfaceSize,
+      claimsKey, framePoint,
       abi: admittedAbi, modules: module.contract.switches && side === "browser" ? { list, enable, disable } : undefined,
       configuration: configuration[name] ?? {} }) ?? {};
     instances.set(name, instance);
@@ -210,7 +235,7 @@ async function createHost({ byName, owners, contracts, runtimes }, side, enabled
       // 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 =>
+      const unavailable = await Promise.race([(await module.provider()).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;
@@ -244,6 +269,7 @@ async function createHost({ byName, owners, contracts, runtimes }, side, enabled
     for (const instance of [...instances.values()].reverse()) instance.dispose?.();
   }
   try {
+    loadProviders(byName, selected);
     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.
@@ -261,12 +287,27 @@ async function createHost({ byName, owners, contracts, runtimes }, side, enabled
     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();
+    async admit(requirements) {
+      const admitted = new Map();
       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);
+        const digest = module?.contract.version === version ? (await module.provider()).digest : undefined;
+        if (digest) admitted.set(value, digest);
       }
+      admittedAbi.clear();
+      for (const [value, digest] of admitted) admittedAbi.set(value, digest);
+    },
+    // The Worker asks this before it restores the image: a module that restores
+    // the whole filesystem itself (a saved session, host/snapshot) says so, and
+    // no image is loaded.
+    async restoreFilesystem(context) {
+      for (const instance of instances.values()) if (await instance.restoreFilesystem?.(context)) return true;
+      return false;
+    },
+    // Whether restoreFilesystem will restore one, known from the configuration,
+    // before a kernel exists.
+    restoresFilesystem() {
+      return [...instances.values()].some(instance => instance.restoresFilesystem?.());
     },
     // The Worker calls this after restoring the system image and before starting
     // image-phase modules, in registry order.
@@ -332,7 +373,7 @@ async function createHost({ byName, owners, contracts, runtimes }, side, enabled
             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);
+            const { digest } = await byName.get(name).provider();
             if (digest) admittedAbi.set(message.module, digest);
           } else if (instances.has(name)) detach(name);
         } catch (error) {

package/host/nena/module.json

@@ -11,5 +11,6 @@
   "process": [],
   "headers": ["nena.h", "nena-abi.h"],
   "kernel": ["kernel.c"],
-  "client": ["client.c"]
+  "client": ["client.c"],
+  "package": "libdolly-nena"
 }

package/host/nena/nena.mjs

@@ -66,6 +66,8 @@ export function browser({ send, modules, showStatus }) {
     // travels through the provider that the switch takes away.
     if (!enabling && name === "nena") return { bytes: moduleRecord({ ...found(), enabled: false }), after: () => modules.disable(value) };
     const refusal = await (enabling ? modules.enable(value) : modules.disable(value));
+    // The page says every switch: what a session gives itself is seen.
+    if (!refusal) showStatus(`This session ${enabling ? "enabled" : "disabled"} ${value}.`);
     return { bytes: moduleRecord(found(), refusal ?? undefined), enabled: enabledSince() };
   }
   return {

package/host/packages/abi.mjs

@@ -0,0 +1,27 @@
+// Generated from host/packages/dolly-packages-0.wat, host/packages/packages.h, include/dolly/process.h.
+export const DOLLY_PACKAGES_HEADER_SIZE = 64;
+export const DOLLY_PACKAGES_WORD_REQUEST = 0;
+export const DOLLY_PACKAGES_WORD_CANCELLED = 1;
+export const DOLLY_PACKAGES_WORD_COMPLETED = 2;
+export const DOLLY_PACKAGES_WORD_CHUNK = 3;
+export const DOLLY_PACKAGES_WORD_CONSUMED = 4;
+export const DOLLY_PACKAGES_WORD_LENGTH = 5;
+export const DOLLY_PACKAGES_WORD_ERROR = 6;
+export const DOLLY_PACKAGES_WORD_EOF = 7;
+export const DOLLY_PACKAGES_WORD_ENABLED = 8;
+export const DOLLY_PACKAGES_WORD_SIZE = 9;
+export const DOLLY_PACKAGES_WORD_KIND = 10;
+export const DOLLY_PACKAGES_WORD_DIRECTORY_LENGTH = 11;
+export const DOLLY_PACKAGES_DIRECTORY_OFFSET = 64;
+export const DOLLY_PACKAGES_DIRECTORY_CAPACITY = 2048;
+export const DOLLY_PACKAGES_PIN_OFFSET = 2112;
+export const DOLLY_PACKAGES_PIN_BYTES = 64;
+export const DOLLY_PACKAGES_CHUNK_OFFSET = 2176;
+export const DOLLY_PACKAGES_CHUNK_CAPACITY = 1048576;
+export const DOLLY_PACKAGES_MAX_SIZE = 2147483647;
+export const DOLLY_PACKAGES_KIND_DIRECTORY = 1;
+export const DOLLY_PACKAGES_KIND_INDEX = 2;
+export const DOLLY_PACKAGES_KIND_SNAPSHOT = 3;
+export const DOLLY_PACKAGES_FETCH = 134;
+export const DOLLY_ERRNO = Object.freeze({ E2BIG: 1, EACCES: 2, EADDRINUSE: 3, EADDRNOTAVAIL: 4, EAFNOSUPPORT: 5, EAGAIN: 6, EALREADY: 7, EBADF: 8, EBADMSG: 9, EBUSY: 10, ECANCELED: 11, ECHILD: 12, ECONNABORTED: 13, ECONNREFUSED: 14, ECONNRESET: 15, EDEADLK: 16, EDESTADDRREQ: 17, EDOM: 18, EDQUOT: 19, EEXIST: 20, EFAULT: 21, EFBIG: 22, EHOSTUNREACH: 23, EIDRM: 24, EILSEQ: 25, EINPROGRESS: 26, EINTR: 27, EINVAL: 28, EIO: 29, EISCONN: 30, EISDIR: 31, ELOOP: 32, EMFILE: 33, EMLINK: 34, EMSGSIZE: 35, EMULTIHOP: 36, ENAMETOOLONG: 37, ENETDOWN: 38, ENETRESET: 39, ENETUNREACH: 40, ENFILE: 41, ENOBUFS: 42, ENODEV: 43, ENOENT: 44, ENOEXEC: 45, ENOLCK: 46, ENOLINK: 47, ENOMEM: 48, ENOMSG: 49, ENOPROTOOPT: 50, ENOSPC: 51, ENOSYS: 52, ENOTCONN: 53, ENOTDIR: 54, ENOTEMPTY: 55, ENOTRECOVERABLE: 56, ENOTSOCK: 57, ENOTTY: 59, ENXIO: 60, EOVERFLOW: 61, EOWNERDEAD: 62, EPERM: 63, EPIPE: 64, EPROTO: 65, EPROTONOSUPPORT: 66, EPROTOTYPE: 67, ERANGE: 68, EROFS: 69, ESPIPE: 70, ESRCH: 71, ESTALE: 72, ETIMEDOUT: 73, ETXTBSY: 74, EXDEV: 75, ENODATA: 116, ENOTSUP: 138 });
+export const DOLLY_PACKAGES_ABI_DIGEST = "2e7905a73d0f041833b239074042ed9ca77e692c3caa0d9d147be98f94ea95b8";

package/host/packages/module.json

@@ -3,11 +3,13 @@
   "version": 0,
   "gives": "the release's published packages, for amy",
   "dependencies": ["http@0"],
+  "phase": "image",
   "imports": [],
   "host": "packages.mjs",
-  "contracts": [],
+  "contracts": ["dolly-packages-0.wat"],
   "process": [],
-  "headers": [],
-  "kernel": [],
-  "client": []
+  "headers": ["packages.h", "packages-abi.h"],
+  "kernel": ["kernel.c"],
+  "client": ["client.c"],
+  "package": "libdolly-packages"
 }

package/host/packages/packages.mjs

@@ -1,15 +1,30 @@
-// Published package snapshots for a running image. No Wasm imports: enabling
-// packages@0 only lets the page admit GET https://packages.dolly.invalid/v1/…
-// (host/http/local-services.mjs) once the image ENTRY starts. The guest names
-// a package by the recipe pin this release publishes; the page materializes
-// and verifies its snapshot exactly as it does a build input, then serves the
-// bytes. A request grants no network or other authority. The index of names
-// is a public file of the site, amy-index.txt, read like any other URL.
+// Published package snapshots for a running image. The guest names a package
+// by the recipe pin an image directory publishes, by default the page's own;
+// the page materializes and verifies its snapshot exactly as it does a build
+// input. From the page's own directory the index, amy-index.txt, and the
+// snapshots come over this module's own mailbox (dolly-packages-0.wat,
+// transport.mjs); another directory is read through http@0's broker, as
+// https://packages.dolly.invalid/v1/… (host/http/local-services.mjs), only
+// where the page's HTTP policy admits it, as a request of the guest's would be.
 import { PackageService } from "./service.mjs";
+import { PackagesTransport } from "./transport.mjs";
+export { DOLLY_PACKAGES_ABI_DIGEST as digest } from "./abi.mjs";
 
 export function browser({ get }) {
   return {
-    entryStarted() { get("http").services.packages = new PackageService(); },
+    entryStarted() { const http = get("http"); http.services.packages = new PackageService(http.admit); },
     disabled() { delete get("http").services.packages; },
   };
 }
+
+// The kernel's mailbox reports each request at the service tick.
+export function worker({ images }) {
+  let transport;
+  return {
+    start({ kernel, memory }) {
+      transport = new PackagesTransport(memory.buffer, Number(kernel.dolly_packages_mailbox_address()), images);
+    },
+    service() { transport?.service(); },
+    dispose() { transport?.close(); },
+  };
+}