@ai-ecoverse/slicc-kernel 1.81.0 → 1.82.0

package/README.md

@@ -659,6 +659,13 @@ A character device (`0666`, major 10, minor 251), there in every `users` mode, t
 - **Clients:** a client's (`kernel.connect`) file calls, mounts and unmounts see the paths read-only, as its processes do.
 - **Not affected:** the page's own writes to OPFS.
 - **Writers:** `protect: { paths, writers: ['bios-installer'] }` names process tags whose processes may change the paths, such as the embedder's own installs (`kernel.run(['pnpm', 'install'], { tag: 'bios-installer' })`). A tag matches exactly, with no prefix or case folding. A process gets its tag only from the embedder, through `kernel.run`, `kernel.openTerminal` or `kernel.connect({ tag })`, and passes it to its children, forks and `exec`s; a program or a client can't choose one. Writers work on their own view of the root file system, so a file a writer changes is seen by other processes as between two tabs: close-to-open, at their next open after the writer closes it.
+- **Integrity:** `protect: { paths, integrity: { lookup, unknown } }` also checks what a program is made of before it runs. That covers a wasm module, an Emscripten program's glue, a WASI program's imports module, a JS program's module, the `package.json` of each package under a path (the kernel builds its commands, `binfmt` suffixes and drivers only from manifests that pass, so a package whose manifest changed has no commands, 127, and no drivers, `ENODEV`), a script started through its `#!` line or a `binfmt` suffix, a package driver's module and the TLS engine, when the file lies under a path.
+  - **The check:** the kernel hashes the exact bytes it is about to compile or hand to a worker (SHA-256, hex), and asks `lookup(path)` (the real path; on the page, it may be async) for the hash it expects. On a mismatch the program doesn't start: `kernel.run` rejects and a spawn fails with `EACCES` ("integrity check failed"; 126 in a shell, not `ENOEXEC`, which would make a shell run the file as a script), a driver fails to mount, TLS fails, and `onDenial` gets `{ op: 'exec-integrity', path, errno: 'EACCES', pid, uid, tag?, expected, actual }`. A `lookup` that throws counts as a mismatch.
+  - **No hash known:** when `lookup` has none (`undefined`), `unknown: 'allow'` (the default) runs the file and reports `{ op: 'exec-unverified', errno: 'ENODATA', … }` once per path, while `unknown: 'deny'` refuses it as a mismatch.
+  - **The cache:** a result is kept per real path and the version of the file OPFS itself reports (its `lastModified` and `size`), not the kernel's metadata, so a change made around the kernel is checked again at the next start. The compiled module is cached by the same key, so a program that hasn't changed costs nothing more to start.
+  - **Where `lookup` gets its hashes:** from a source independent of the installed files, such as the per-file hashes the embedder derives from the certified package tarball when it builds its catalog. Hashes read back from the installed files prove nothing.
+  - **Scripts** are checked when they're executed; the interpreter reads the file again afterwards, so a change in between isn't caught ([#454](https://github.com/ai-ecoverse/slicc-kernel/issues/454)).
+  - **Not covered:** what a running program reads itself, such as a JS runtime's modules, python's `.py` files and `dlopen`'s side modules ([#454](https://github.com/ai-ecoverse/slicc-kernel/issues/454)). Protected paths still keep those unwritable.
 - **Where it is a boundary:** it's one in a browser, where programs' own code can't reach OPFS around the kernel (see [JS programs](#js-programs)). Under the Node entry it isn't, until [#407](https://github.com/ai-ecoverse/slicc-kernel/issues/407), and there `kernel.writeFile` under a path fails too, so write those files into `root` before creating the kernel.
 
 ### `/proc`

package/dist/index.js

@@ -332,7 +332,12 @@ var DEFAULT_USERS = "enforce";
 // src/fs/protect.ts
 function protectInit(protection) {
   const writers = [...writerTags(protection)];
-  return { paths: [...protection.paths], ...writers.length > 0 ? { writers } : {} };
+  const { integrity } = protection;
+  return {
+    paths: [...protection.paths],
+    ...writers.length > 0 ? { writers } : {},
+    ...integrity ? { integrity: { unknown: integrityUnknown(integrity) } } : {}
+  };
 }
 function writerTags(protection) {
   const writers = protection?.writers ?? [];
@@ -342,6 +347,40 @@ function writerTags(protection) {
   return new Set(writers);
 }
 
+// src/fs/integrity.ts
+function integrityOptions(options) {
+  if (options && typeof options.lookup !== "function") {
+    throw new TypeError("protect.integrity.lookup must be a function");
+  }
+  integrityUnknown(options);
+}
+function integrityUnknown(options) {
+  const unknown = options?.unknown ?? "allow";
+  if (unknown !== "allow" && unknown !== "deny") {
+    throw new TypeError("protect.integrity.unknown must be 'allow' or 'deny'");
+  }
+  return unknown;
+}
+
+// src/integrity-relay.ts
+function integrityAnswerer(port, lookup) {
+  const ask = async ({ id, path }) => {
+    try {
+      const hash = lookup ? await lookup(path) : void 0;
+      port.postMessage({ integrityReply: { id, ...typeof hash === "string" ? { hash } : {} } });
+    } catch (err) {
+      const error = err instanceof Error ? err.message : String(err);
+      port.postMessage({ integrityReply: { id, error } });
+    }
+  };
+  return (data) => {
+    const asked = data?.integrityAsk;
+    if (!asked) return false;
+    void ask(asked);
+    return true;
+  };
+}
+
 // src/kernel/net/loopback-names.ts
 var HOST_LOOPBACK = "host.slicc.internal";
 var HOST_LOOPBACK_ADDRESS = [10, 0, 2, 2];
@@ -2099,12 +2138,15 @@ function checkOptions(options) {
   if (options.hostname !== void 0 && !isHostname(options.hostname)) {
     throw new Error(`not a host name: ${String(options.hostname)}`);
   }
+  if (options.protect) protectInit(options.protect);
+  integrityOptions(options.protect?.integrity);
 }
 function hookRelays(worker, options) {
   const sealed = sealedAnswerer(worker, options.sealed);
   const clipboard = clipboardAnswerer(worker, options.clipboard);
+  const integrity = integrityAnswerer(worker, options.protect?.integrity?.lookup);
   return {
-    handle: (data) => sealed.handle(data) || clipboard.handle(data),
+    handle: (data) => sealed.handle(data) || clipboard.handle(data) || integrity(data),
     close: () => sealed.close()
   };
 }
@@ -2133,7 +2175,6 @@ function traitsUpdater(transport, call) {
 }
 async function createKernel(options = {}) {
   checkOptions(options);
-  writerTags(options.protect);
   const url = options.worker ?? new URL("./kernel-worker.js", import.meta.url);
   const worker = new Worker(url, { type: "module", name: "slicc-kernel" });
   const pending = /* @__PURE__ */ new Map();