@ai-ecoverse/slicc-kernel 1.77.2 → 1.78.0

package/README.md

@@ -38,7 +38,7 @@ const { status, stdout, stderr } = await kernel.run(['bash', '-c', 'echo hi > he
 | `onMountPending` | none | `({ target, source, insert }) => void`: an `fsa` mount needs a folder; call `insert()` from a user gesture |
 | `processMounts` | `true` | whether programs may call `mount(2)` and `umount2(2)`: `false`, or `(req) => boolean \| Promise<boolean>` to decide each call (see [Mounting from a program](#mounting-from-a-program)) |
 | `hostname` | `'slicc'` | the kernel's node name (see [Node name](#node-name)) |
-| `users` | `'off'` | `'off'`, `'report'` or `'enforce'`: whether files have owners and their modes are checked (see [File owners](#file-owners) and [Permissions](#permissions)). `'off'` behaves exactly as kernels before owners did; any other value rejects. `createNodeKernel` takes it too |
+| `users` | `'enforce'` | `'off'`, `'report'` or `'enforce'`: whether files have owners and their modes are checked (see [File owners](#file-owners) and [Permissions](#permissions)), and whether `sudo` elevates (see [Sudo](#sudo)). `'off'` behaves exactly as kernels before owners did; any other value rejects. `createNodeKernel` takes it too, with the same default. Kernels up to 1.73 defaulted to `'off'` |
 | `onDenial` | none | `({ pid, uid, op, path, errno, tag? }) => void`: called for every permission check that fails, under `'report'` and `'enforce'` (see [Permissions](#permissions)). `createNodeKernel` takes it too |
 | `sealed` | none | `(req, { signal }) => Promise<object>`: answers requests written to [`/dev/sealed`](#devsealed). `createNodeKernel` takes it too |
 | `clipboard` | none | `{ read(stamp) => Promise<string>, write(text, stamp) => Promise<void> }`: the clipboard behind [`/dev/clipboard`](#devclipboard). `createNodeKernel` takes it too |
@@ -46,9 +46,9 @@ const { status, stdout, stderr } = await kernel.run(['bash', '-c', 'echo hi > he
 | `cdp` | none | `({ runtime }) => Promise<CdpConnection>`: a browser-level DevTools connection for programs that drive a browser (see [Browser automation](#browser-automation-cdp)) |
 | `protect` | none | `{ paths, writers? }`: directories no process may change, root included, in every `users` mode, except processes with one of the `writers` tags (see [Protected paths](#protected-paths)). `createNodeKernel` takes it too |
 
-### `kernel.run(argv, options?) → Promise<{ status, stdout, stderr }>`
+### `kernel.run(argv, options?) → Promise<{ status, signal, stdout, stderr }>`
 
-Runs `argv[0]` with `argv` as its arguments and resolves when it exits. `stdout` and `stderr` are decoded as UTF-8; `status` is the exit status, `128 + n` for a process killed by signal `n`, and `127` when `argv[0]` cannot be found.
+Runs `argv[0]` with `argv` as its arguments and resolves when it exits. `stdout` and `stderr` are decoded as UTF-8; `status` is the exit status, `128 + n` for a process killed by signal `n`, and `127` when `argv[0]` cannot be found. `signal` is there only when a signal ended the process, named as `'SIGKILL'`, so a `kill -9` (`status: 137, signal: 'SIGKILL'`) can be told from an `exit 137` (`status: 137`, no `signal`).
 
 | option | |
 | --- | --- |
@@ -77,6 +77,7 @@ Starts `argv` as the session leader on a new terminal and resolves once it is ru
 | `resize(cols, rows)` | sets the window size (`TIOCGWINSZ`) and sends `SIGWINCH` to the foreground process group |
 | `signal(name)` | sends a signal (`'SIGINT'`, `'SIGTSTP'`, `'SIGQUIT'`, `'SIGHUP'`, …) to the foreground process group, regardless of termios |
 | `exited` | resolves with the session leader's exit status (`128 + n` if killed by signal `n`) |
+| `ended` | resolves with `{ status, signal }` at the same time: `status` as `exited`, and `signal` named (`'SIGKILL'`) only when a signal ended it |
 | `close()` | hangs up: `SIGHUP` to the foreground process group, and reads from the terminal return end-of-file |
 
 ### `kernel.terminate()`
@@ -131,6 +132,7 @@ Reach a server a program runs on the kernel's loopback (a dev server, `python -m
 - **`loopbackFetch`** sends an HTTP/1.1 request over `dial` and resolves with a `Response` as soon as the headers arrive. The body streams (chunked, counted, or until the connection closes), so server-sent events and long polls work; cancelling the body or aborting `signal` closes the connection. The request is routed by `port`, not by the URL, whose host is sent as `Host`; a request body is sent with `Content-Length`, and every request uses a connection of its own (`Connection: close`).
 - **Errors** reject with an `Error` whose `code` is the errno: `ECONNREFUSED` when nothing listens on the port or the port is kernel-only (`9222`, the [CDP facade](#browser-automation-cdp)), `ENETUNREACH` for a host that is not the loopback, `EINVAL` for a port outside 1–65535.
 - **Names**: a page reaches the kernel's loopback as `<port>.kernel.localhost`, which is the loopback and a secure context, so a request no service worker routes lands on port 80 of the real machine instead of a real server on that port; the service worker routes the name to `loopbackFetch` with that port. Programs find the name in `SLICC_PAGE_LOOPBACK` (`kernel.localhost`) and `SLICC_PAGE_LOOPBACK_URL` (`http://{port}.kernel.localhost`), to print or inject the right URL.
+- **No per-user isolation**: as on Linux, any user's process can connect to any listener on `127.0.0.1`, and the page reaches every one as `<port>.kernel.localhost`, so the loopback is no privilege boundary; a service that needs one must authenticate its clients.
 
 ### `kernel.attest(path)` and `kernel.watch(paths, onChange)`
 
@@ -152,9 +154,9 @@ Attaches to a kernel over a port from `kernel.connect()`, in any realm: a worker
 
 | Client | |
 |---|---|
-| `spawn(argv, { cwd, user, env, stdin, pgid, onStdout, onStderr })` | runs over pipes and resolves with `{ pid, pgid, exited, signal(name) }` once the process has started; output arrives in chunks, as bytes, and the kernel keeps no copy; every spawn leads its own process group, which `signal` (default `SIGTERM`) signals, unless `pgid` names an existing group to join (protocol 1.3): the process then joins that group and that group's session, as `setpgid` would (a client has no session of its own: each of its spawns and terminals leads one, and `setpgid` cannot cross sessions), and `signal` signals the whole group. The group must have been started by this client (a spawn or a terminal it opened), even if its leader has exited; an unknown group rejects with `code: 'ESRCH'`, another session's with `code: 'EPERM'`, and against a 1.2 kernel the client rejects with `code: 'ENOSYS'` before sending anything, as an older kernel would ignore the option; a program that cannot start rejects with `code: 'ENOENT'`. `user` runs it as another user, which only a root client may (see `kernel.connect`); against a 1.7 kernel the client rejects with `code: 'ENOSYS'` |
-| `run(argv, options?)` | `spawn` and wait: `{ pid, status, stdout, stderr }` as text, with `onStdout`/`onStderr` streaming text |
-| `openTerminal(argv, options?)` | a pty session, as `kernel.openTerminal` |
+| `spawn(argv, { cwd, user, env, stdin, pgid, onStdout, onStderr })` | runs over pipes and resolves with `{ pid, pgid, exited, ended, signal(name) }` once the process has started; `ended` resolves with `{ status, signal }`, `signal` named only when a signal ended the process, as for `kernel.run` (an older kernel never names one); output arrives in chunks, as bytes, and the kernel keeps no copy; every spawn leads its own process group, which `signal` (default `SIGTERM`) signals, unless `pgid` names an existing group to join (protocol 1.3): the process then joins that group and that group's session, as `setpgid` would (a client has no session of its own: each of its spawns and terminals leads one, and `setpgid` cannot cross sessions), and `signal` signals the whole group. The group must have been started by this client (a spawn or a terminal it opened), even if its leader has exited; an unknown group rejects with `code: 'ESRCH'`, another session's with `code: 'EPERM'`, and against a 1.2 kernel the client rejects with `code: 'ENOSYS'` before sending anything, as an older kernel would ignore the option; a program that cannot start rejects with `code: 'ENOENT'`. `user` runs it as another user, which only a root client may (see `kernel.connect`); against a 1.7 kernel the client rejects with `code: 'ENOSYS'` |
+| `run(argv, options?)` | `spawn` and wait: `{ pid, status, signal, stdout, stderr }` as text, with `onStdout`/`onStderr` streaming text; `signal` as for `kernel.run` |
+| `openTerminal(argv, options?)` | a pty session, as `kernel.openTerminal`, `ended` included |
 | `ps()` | the kernel's processes: `{ pid, ppid, pgid, sid, argv, tty, started, state, rss, utime, stime, uid, gid }`, `state` being `'S'`, `'T'` (stopped) or `'Z'`, `rss` the process's resident memory in bytes (the size of its wasm memory, what `/proc/<pid>/status` shows as `VmRSS`; absent from kernels before 1.61), `utime`/`stime` the CPU time it has used, in milliseconds, in its program and in the kernel's calls (see [`/proc`](#proc); absent for a JS program and from kernels before 1.63) and `uid`/`gid` the effective ids (absent from a 1.7 kernel). A client bound to a user sees only that user's processes |
 | `kill(pid, signal?)` | a process, or a process group with a negative pid; no such process rejects with `code: 'ESRCH'`, and one the client's user may not signal with `code: 'EPERM'` |
 | `fs` | `readFile`, `readText`, `writeFile(path, string \| bytes)`, `stat`, `lstat`, `readdir`, `mkdir` (with parents), `rm(path, { force })` (recursive), `rename`, `realpath`, `symlink(target, path)`, `readlink`, `exists`, on the processes' file system, mounts included (a path under a `tmpfs`, `fsa` or `hostfs` mount reads and writes the mounted file system, as `cat` in a process would); failures reject with `KernelCallError` and a POSIX `code` |
@@ -570,7 +572,7 @@ Programs ask the kernel for their ids:
 
 ### File owners
 
-With `createKernel({ users: 'report' })` or `'enforce'`, files have owners, and [Permissions](#permissions) checks them against a process's credentials. With `'off'`, the default, nothing below happens: the kernel stores no owner, and every file looks owned by the caller as described under [Metadata](#metadata).
+With `users: 'enforce'`, the default, or `'report'`, files have owners, and [Permissions](#permissions) checks them against a process's credentials. With `'off'` nothing below happens: the kernel stores no owner, and every file looks owned by the caller as described under [Metadata](#metadata).
 
 - **Where owners live:** on the root file system, in the sidecar record's `uid` and `gid` (see [Metadata](#metadata)). A path with no owner of its own has the owner of its nearest ancestor that has one, and `/` belongs to root, so a root written before owners existed, or by the BIOS through the OPFS API, is root's throughout. A directory whose owner changes keeps the owner its unowned contents had, in `heir`, so `chown cone /old` gives `cone` the directory and leaves the files below it to their old owner. A rename keeps the owner of what it moves.
 - **New files:** a file, directory or symlink a process creates belongs to its effective uid, and to its effective gid, or to the directory's group when the directory has the setgid bit; a new directory in a setgid directory gets the setgid bit too. Every file and directory a process creates gets the mode it asked for (`0666` and `0777` when it can't ask, as a JS program's `ctx.fs` can't) less the process's umask, whichever runtime made it; an Emscripten program's file no longer gets `0644` whatever it asked for. A file written through a client's `fs` belongs to the client's user (root for a page) and gets `0666`, a directory `0777`, less the umask `kernel.users.add` gave that user (`022` for root and by default); the kernel's own files, such as `/etc/passwd`, have no owner of their own.
@@ -596,7 +598,7 @@ With `users: 'enforce'` the kernel checks every file call that reaches it agains
 - **A client's `fs`:** checked as the client's user; a page's client (root) passes.
 - **Removed files still open:** a process that holds a removed file may look it up (`stat`, `lstat`) under the hidden name the kernel gave it in `/.slicc-unlinked`, which is root's `0700`; every other process is refused there, so the kernel's own bookkeeping of held files raises no denials for their holders.
 
-`users: 'enforce'` is not the default yet; it becomes so once the embedders have checked their programs under `'report'`.
+`users: 'enforce'` is the default of `createKernel` and `createNodeKernel`; pass `'report'` to find what a program would be refused without refusing it, or `'off'` for kernels without owners. A `Launcher` made directly (see [What is in here](#what-is-in-here)) still defaults to `'off'`.
 
 ### Sudo
 
@@ -608,7 +610,7 @@ With `users: 'enforce'` the kernel checks every file call that reaches it agains
 - **The command** is found once, on `/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin` for a bare name or against the caller's directory for a path, and its real path (symlinks resolved) is what runs and what the policy sees. That file, and every file that will really run for it (a catalog command's glue, module and imports module, and the `package.json` that defines it, a script and the interpreter its `#!` line or `binfmt` suffix names), must be root's and writable by root only, and so must every directory above each, or `sudo` refuses (`EPERM`), whatever the policy says. A command that wouldn't start as the target user (a `#!` line naming an interpreter that is only the caller's, say) fails with `command not found` before anything is asked. Other files a program loads at run time (a package's libraries) are the admin's to keep safe, as on Linux. The caller's directory, which the program passes on, must be a directory the caller may enter, or `sudo` refuses (`EACCES`). The kernel resolves it to its real path once, shows that in the request, and runs the command there; if it no longer resolves the same, or the caller can no longer enter it, when the answer comes or when the command starts, nothing runs.
 - **The decision:** a caller whose effective uid is 0 runs anything (the check on the command's path still applies). Otherwise a matching `NOPASSWD` line runs the command at once; any other matching line asks `approve`; nothing matching is refused (`sudo: cone is not allowed to run /usr/bin/ls as root`).
 - **Approval:** `approve(req, { signal })` gets `{ id, kind: 'sudo', user, uid, target, argv, path, cwd, pid, tag?, tty?, createdAt, expiresAt, always: true }`: the caller's name and real uid, the target user, the argv as typed, the resolved `path`, the caller's directory, pid, tag and terminal, and the times in ms. It answers `'once'` (run it), `'always'` (run it, and append `NOPASSWD <user> (<target>) Cmnd <path> <args…>` to `/etc/sudoers.d/<user>`, root's `0440`, so it's never asked again; if that can't be written, nothing runs) or `'deny'`; a throw, any other answer or no hook at all is `sudo: approval denied`. After 5 minutes the request expires (`signal` aborts with `'expired'`, and `sudo` fails with `sudo: the request expired`); when the requester ends or gets a signal while it waits, `^C` included, `signal` aborts with `'withdrawn'` and `sudo` ends with that signal's status. A user has at most one request waiting; another fails with `sudo: another request is pending`. On the page, `createKernel` relays the request from the kernel worker and back, and the abort too; `terminate()` or a failed worker aborts every request still waiting with `'withdrawn'`.
-- **Running:** the command runs as the caller's child, with all six ids and the groups of the target user, in the caller's directory, on its terminal, standard input, output and error, and in its process group; `sudo` exits with its status, and passes `SIGTERM` and `SIGHUP` on to it, also one that comes while it starts (the kernel lets it signal the command it started, which its own user may not); `SIGINT` and `SIGQUIT` it leaves to the command, which gets them from the terminal itself. It's found among the system's commands only, never a user's own. Its environment is the kernel's (the embedder's `env` and the proxy settings), the target's `HOME`, `USER`, `LOGNAME`, `SHELL`, `PNPM_HOME` and `NPM_CONFIG_PREFIX`, `PATH` set to the path above, `PWD`, the caller's `TERM` when it is a plain name (letters, digits, `.`, `_`, `+`, `-`), and `SUDO_USER`, `SUDO_UID`, `SUDO_GID` and `SUDO_COMMAND`; nothing else of the caller's comes through.
+- **Running:** the command runs as the caller's child, with all six ids and the groups of the target user, in the caller's directory, on its terminal, standard input, output and error, and in its process group; `sudo` exits with its status, and passes `SIGTERM` and `SIGHUP` on to it, also one that comes while it starts (the kernel lets it signal the command it started, which its own user may not); `SIGINT` and `SIGQUIT` it leaves to the command, which gets them from the terminal itself. Two narrow gaps remain ([#424](https://github.com/ai-ecoverse/slicc-kernel/issues/424)): a relayed signal reaches the command but not the processes it started itself, which keep running as the target user if it ends; and right after the command starts, a `SIGINT` or `SIGQUIT` sent to `sudo`'s own pid (not through the terminal) ends `sudo` and leaves the command running. Closing both needs the command in a process group of its own, which changes job control. It's found among the system's commands only, never a user's own. Its environment is the kernel's (the embedder's `env` and the proxy settings), the target's `HOME`, `USER`, `LOGNAME`, `SHELL`, `PNPM_HOME` and `NPM_CONFIG_PREFIX`, `PATH` set to the path above, `PWD`, the caller's `TERM` when it is a plain name (letters, digits, `.`, `_`, `+`, `-`), and `SUDO_USER`, `SUDO_UID`, `SUDO_GID` and `SUDO_COMMAND`; nothing else of the caller's comes through.
 - **Cost:** with `users: 'off'`, and with owners on for programs that don't call `sudo`, nothing is added to any call.
 
 ### `/dev/sealed`

package/dist/driver-worker.js

@@ -280,6 +280,54 @@ var RemoteTransport = class {
   }
 };
 
+// src/kernel/signals.ts
+var SIG = {
+  HUP: 1,
+  INT: 2,
+  QUIT: 3,
+  ILL: 4,
+  TRAP: 5,
+  ABRT: 6,
+  BUS: 7,
+  FPE: 8,
+  KILL: 9,
+  USR1: 10,
+  SEGV: 11,
+  USR2: 12,
+  PIPE: 13,
+  ALRM: 14,
+  TERM: 15,
+  STKFLT: 16,
+  CHLD: 17,
+  CONT: 18,
+  STOP: 19,
+  TSTP: 20,
+  TTIN: 21,
+  TTOU: 22,
+  URG: 23,
+  XCPU: 24,
+  XFSZ: 25,
+  VTALRM: 26,
+  PROF: 27,
+  WINCH: 28,
+  POLL: 29,
+  PWR: 30,
+  SYS: 31
+};
+var IGNORED_BY_DEFAULT = /* @__PURE__ */ new Set([SIG.CHLD, SIG.URG, SIG.WINCH]);
+var STOPPING = /* @__PURE__ */ new Set([SIG.STOP, SIG.TSTP, SIG.TTIN, SIG.TTOU]);
+function quiet(p) {
+  p.catch(() => void 0);
+  return p;
+}
+var SIGNAL_BY_NAME = {
+  SIGINT: SIG.INT,
+  SIGTERM: SIG.TERM,
+  SIGKILL: SIG.KILL,
+  SIGSTOP: SIG.STOP,
+  SIGCONT: SIG.CONT
+};
+
 // src/bytes.ts
 function fresh(bytes, start = 0, end = bytes.length) {
   return new Uint8Array(bytes.subarray(start, end));
@@ -665,6 +713,7 @@ var Channel = class {
       return;
     }
     this.pending.delete(reply.id);
+    call.ended?.(reply.signal);
     if (reply.error !== void 0) call.reject(new KernelCallError(reply.error, reply.code));
     else call.resolve(reply.result);
   }
@@ -713,12 +762,14 @@ async function spawnOn(channel, argv, opts) {
   if (opts.user !== void 0) await since(channel, 8, "spawn as a user", async () => {
   });
   const started = Promise.withResolvers();
+  let endedBy;
   const options = { ...rest, ...stdin !== void 0 ? { stdin: bytesOf(stdin) } : {} };
   const { done } = channel.request(
     { op: "spawn", argv, options },
     {
       output: (fd, bytes) => (fd === 1 ? onStdout : onStderr)?.(bytes),
-      started: started.resolve
+      started: started.resolve,
+      ended: (signal) => endedBy = signal
     }
   );
   done.catch(started.reject);
@@ -728,9 +779,18 @@ async function spawnOn(channel, argv, opts) {
     pid,
     pgid,
     exited: done,
+    ended: endedOf(done, () => endedBy),
     signal: async (name = "SIGTERM") => void await channel.call({ op: "kill", pid: -pgid, signal: name })
   };
 }
+function endedOf(done, signal) {
+  return quiet(
+    done.then((status) => {
+      const by = signal();
+      return { status, ...by ? { signal: by } : {} };
+    })
+  );
+}
 async function runOn(channel, argv, opts) {
   const { onStdout, onStderr, ...rest } = opts;
   const chunks = { 1: [], 2: [] };
@@ -744,9 +804,15 @@ async function runOn(channel, argv, opts) {
     onStdout: tee(1, onStdout),
     onStderr: tee(2, onStderr)
   });
-  const status = await child.exited;
+  const { status, signal } = await child.ended;
   const text = (fd) => new TextDecoder().decode(concat(chunks[fd]));
-  return { pid: child.pid, status, stdout: text(1), stderr: text(2) };
+  return {
+    pid: child.pid,
+    status,
+    ...signal ? { signal } : {},
+    stdout: text(1),
+    stderr: text(2)
+  };
 }
 async function terminalOn(channel, argv, opts) {
   const { onData, ...options } = opts;
@@ -755,11 +821,13 @@ async function terminalOn(channel, argv, opts) {
   let listener = onData ?? null;
   const backlog = [];
   const started = Promise.withResolvers();
+  let endedBy;
   const { id, done } = channel.request(
     { op: "open-terminal", argv, options },
     {
       output: (_fd, bytes) => listener ? listener(bytes) : backlog.push(bytes),
-      started: started.resolve
+      started: started.resolve,
+      ended: (signal) => endedBy = signal
     }
   );
   done.catch(started.reject);
@@ -768,6 +836,7 @@ async function terminalOn(channel, argv, opts) {
   return {
     pid,
     exited: done,
+    ended: endedOf(done, () => endedBy),
     get onData() {
       return listener;
     },