@ai-ecoverse/slicc-kernel 1.180.0 → 1.181.0

package/README.md

@@ -97,6 +97,10 @@ Makes a port for another client of the same kernel. Hand it to a dedicated worke
 
 **`user`** (a name or uid) binds the client to that user; without it the client is root. The binding is a capability: the client's `spawn`, `run` and `openTerminal` run as that user, its `ps` lists only that user's processes, and its `kill` follows POSIX permission. A bound client can't run anything as another user (`code: 'EPERM'`). A root client may pass `user` to `spawn`, `run` or `openTerminal` to run one command as any user. An unknown user rejects with `code: 'ENOENT'`. **`tag`** is the tag (see `kernel.run`) of every process the client starts; its own `spawn`, `run` and `openTerminal` cannot name another. They may add one with their own `tag` option (protocol 1.12; an older kernel answers `ENOSYS`): the process then has both tags, the connection's first, and so does everything it starts. The option may also be a list of at most 8 tags, added in order (protocol 1.15; against an older kernel the client rejects with `code: 'ENOSYS'` before sending anything), so a caller can mark one call's tree with a tag of its own for [`trace`](#clienttracetag-onevents--limit---promise-close-) beside a tag that means something else. A per-spawn tag only adds; no client, program or child can remove or replace a tag ([#1380](https://github.com/ai-ecoverse/slicc-kernel/issues/1380)).
 
+### `kernel.sudoRun(request, { stdout, stderr, tag }?) → Promise<{ pid, pgid, ended }>`
+
+Runs a `sudo` request that nobody answered in time (or that was denied or withdrawn) as if the answer were `'once'`, after checking that what was asked still holds, detached from any terminal or process: see [Running a request later](#running-a-request-later-sudorun). An attached root client has the same call, `client.sudoRun` (protocol 1.16).
+
 ### `kernel.users`
 
 The user database, `/etc/passwd` and `/etc/group` (see [Users](#users)):
@@ -188,12 +192,13 @@ Attaches to a kernel over a port from `kernel.connect()`, in any realm: a worker
 | `serveCdp(hook, { runtime })` | offers this client's browser to the kernel's programs (protocol 1.5): `hook` is the `cdp` hook of `createKernel`, asked once per program connection; resolves with `{ close() }`, and closing or detaching takes the offer back and closes its connections (see [Browser automation](#browser-automation-cdp)) |
 | `serveFacade(name, hook) → { close() }` | serves a facade that `createKernel({ facades })` declared, the same way as its `hook` (protocol 1.11); the latest registration wins, over the embedder's hook too, and `close()` hands it back. An undeclared name is `EINVAL` |
 | `trace(tag, onEvents, { limit }?)` | reports, as events, every program that a process carrying `tag` runs and every such process's end, with nothing missed (protocol 1.15; against an older kernel the client rejects with `code: 'ENOSYS'`); resolves with `{ close() }` (see [below](#clienttracetag-onevents--limit---promise-close-)) |
+| `sudoRun(request, { stdout, stderr, tag }?)` | runs a `sudo` request again, as `kernel.sudoRun` does, and resolves with `{ pid, pgid, ended }` once it has started (protocol 1.16; against an older kernel the client rejects with `code: 'ENOSYS'` before sending anything). Only a root client may: a client bound to a user rejects with `code: 'EPERM'` (`sudo: only a root client may run a sudo request`). `ended` is tied to the client, as `spawn`'s is, while the process is not (see [Running a request later](#running-a-request-later-sudorun)) |
 | `onTraits(listener) → () => void` | calls `listener(traits)` each time the kernel announces new transport traits (`kernel.updateTransportTraits()`, protocol 1.10), after `client.transport.traits` has been updated; the function it returns removes the listener |
 | `close({ kill })` | detaches: the client's processes keep running unless `kill` is set, which ends their process groups with `SIGKILL`; its terminals are hung up |
 | `closed` | resolves with the error that ended the client |
 | `users` | the kernel's `users` mode, `'off'`, `'report'` or `'enforce'`; `'off'` from kernels that don't say |
 
-When the kernel goes away (the page closed or reloaded, `terminate()`), pending calls and `exited` reject with `KernelGoneError`, and so do later calls. Each side holds a Web Lock and waits on the other's, since a `MessagePort` reports no close in browsers; in Node, the port's `close` event does the same. The first message is a handshake on the protocol version, `1.15` (`1.0` had no `watch`, `1.1` no mounts, `1.2` no `spawn` into a group, `1.3` no `dial` and `1.4` no `serveCdp`, which reject with `code: 'ENOSYS'` on such a kernel; a `1.5` kernel has no [uplink](#uplink), a `1.6` kernel resolves names through one but connects nothing to it, a `1.7` kernel has no users, a `1.8` kernel has no `sudo` and no tags, a `1.9` kernel never announces new transport traits, a `1.11` kernel has no per-spawn `tag`, a `1.12` kernel takes no `requests` at attach, a `1.13` kernel has no `cwdMissing`, and a `1.14` kernel has no `trace` and takes one tag per spawn, not a list, which the client rejects with `code: 'ENOSYS'` before sending anything): a client or kernel of another major version is refused with an error naming both.
+When the kernel goes away (the page closed or reloaded, `terminate()`), pending calls and `exited` reject with `KernelGoneError`, and so do later calls. Each side holds a Web Lock and waits on the other's, since a `MessagePort` reports no close in browsers; in Node, the port's `close` event does the same. The first message is a handshake on the protocol version, `1.16` (`1.0` had no `watch`, `1.1` no mounts, `1.2` no `spawn` into a group, `1.3` no `dial` and `1.4` no `serveCdp`, which reject with `code: 'ENOSYS'` on such a kernel; a `1.5` kernel has no [uplink](#uplink), a `1.6` kernel resolves names through one but connects nothing to it, a `1.7` kernel has no users, a `1.8` kernel has no `sudo` and no tags, a `1.9` kernel never announces new transport traits, a `1.11` kernel has no per-spawn `tag`, a `1.12` kernel takes no `requests` at attach, a `1.13` kernel has no `cwdMissing`, a `1.14` kernel has no `trace` and takes one tag per spawn, not a list, and a `1.15` kernel has no `sudoRun`, which the client rejects with `code: 'ENOSYS'` before sending anything): a client or kernel of another major version is refused with an error naming both.
 
 #### `client.trace(tag, onEvents, { limit }?) → Promise<{ close() }>`
 
@@ -1144,6 +1149,25 @@ As in sudo(8), a person's approval is remembered for a few minutes: until then,
 - **In tests,** `createNodeKernel({ sudo: { clock } })` reads the time of timestamps from `clock.now()`, such as `fakeCronClock()` from `@ai-ecoverse/slicc-kernel/testing`; otherwise it is the monotonic `performance.now()`.
 - **Upgrading:** kernels before this asked for every `sudo` that needed approval. An approver that answers `{ answer, timestamp: true }` now opens a 5-minute window, so a second `sudo` in the same shell, script or terminal doesn't ask, and `sudo -n` succeeds inside it. Put `Defaults timestamp_timeout=0` in the policy to keep asking every time. Plain string answers behave as before. `visudo -c` now ends with the timestamp values.
 
+### Running a request later: `sudoRun`
+
+A request can end without an answer: nobody was there within the 5 minutes, and `sudo` failed with `sudo: the request expired`. The owner may still want it to run. `kernel.sudoRun(request, options)`, and `client.sudoRun` on a root client, run it then, as if the answer had been `'once'`, without the caller's shell, which has moved on.
+
+- **The request** is the object `approve` got, passed back as it is (`SudoReplay`: its `id`, `user`, `uid`, `target`, `argv`, `path`, `cwd`, `stdin`, `rootOnly`, `userWritable`, `tag`, `tags` and `validate`; other fields are ignored). The kernel keeps nothing of a request, so a request saved before a reload still runs, and every call runs it once more: running it at most once is the caller's to keep. It trusts none of the fields: it runs the decision again and refuses whatever has changed. Something that isn't such a request is `EINVAL` (`sudo: that isn't a sudo request this kernel can run`): a field missing or of the wrong type (`rootOnly` included, `{}` for none), an `argv` that is empty, holds a NUL or is over 4096 words or 1 MiB, and a `path` or `cwd` that isn't absolute, holds a NUL or is longer than 4096 characters. A kernel whose `users` isn't `'enforce'` refuses it too.
+- **What it refuses outright** (`EINVAL`): a `sudo -v` request (`sudo: a sudo -v request runs no command`), and one whose `stdin` was `'pipe'` or `'file'`, since that input is gone (`sudo: the request read a pipe, and that input is gone`).
+- **What it checks again,** in this order, before anything runs:
+  - `user` still exists, with `uid` (`ENOENT`, `sudo: unknown user <user>`; `EPERM`, `sudo: <user> is no longer uid <uid>`), and so does `target` (`ENOENT`).
+  - A policy line still lets `user` ask for `path` with these arguments as `target`, in `cwd`, with the contents in `userWritable`, `NOPASSWD` or not (`EACCES`, `sudo: <user> may no longer ask to run <command> as <target>`). There is no caller process any more, so its groups are the ones `/etc/group` gives the user now: a user taken out of `sudo` since can't have its old request run. A root user's request passes, as root's `sudo` does.
+  - `cwd` resolves to the same real path (`EACCES`, `sudo: <cwd> changed since it was requested`), and `user` may still enter it (`EACCES`, `sudo: cannot run in <cwd>: it isn't a directory <user> can enter`). Both are checked once more just before the command starts, as for a command `sudo` starts, and a directory that no longer resolves to itself then (a symlink swapped in meanwhile) is refused with the first sentence, so the command never runs somewhere else.
+  - The first word of `argv` still finds `path`, by the same search as `sudo`'s (`ENOENT`, `sudo: <word>: command not found`; `EPERM`, `sudo: <word> now runs <path now>, not <path>`).
+  - The command's user-writable files are the same files with the same sha256 as in `userWritable` (`EPERM`, `sudo: <file> changed since it was requested`).
+  - No entry of `rootOnly` that was `true` is false now (`EPERM`, `sudo: <path> is no longer root-only`).
+- **How it runs:** as `sudo` would have run it, as `target` with all six ids and its groups, with `sudo`'s environment (`SUDO_USER`, `SUDO_COMMAND`, the fixed `PATH` and the rest) and the caller's umask, in `cwd`, with the [symlink rule](#sudo) for it and everything it starts, and the binding of its user-writable files checked once more when the kernel loads them. It isn't the child of any process: it leads a session and a process group of its own (`pgid` and its session are its `pid`, its parent is pid 1), has no terminal, and reads `/dev/null`. It has every tag of the request, in their order, after the tag of the client's connection, and then `tag` (a string or a list of at most 8), so `ps` and [`trace`](#clienttracetag-onevents--limit---promise-close-) show it as the agent's and the run's: give each run a tag of its own (`sudo-run:<id>`) and subscribe to it before the call.
+- **Output:** `stdout` and `stderr` are absolute paths that the kernel opens as `user`, as the caller's shell opens `sudo command > file`: the caller must be able to write the file, or create it in its directory (`EACCES`, `sudo: <path>: Permission denied`; a missing directory is `ENOENT`, `sudo: <path>: No such file or directory`, since the kernel makes none), a symlink on the way must be root's or the caller's, and the file is truncated, or created as the caller's with mode `0600`. Once the kernel holds the file, it checks the path again, and refuses one that changed meanwhile (a symlink in its place: `EACCES`, `sudo: <path> changed while it was opened`). The same path for both opens one file, as `> file 2>&1` does. Without them, output goes to `/dev/null`. Because the output goes to files, not to the client, the run doesn't depend on the client: it goes on when the client detaches or its worker restarts, and nothing kills it for writing to a reader that is gone.
+- **The answer:** the call (`SudoRunOptions` in, `SudoRun` out) resolves with `{ pid, pgid, ended }` once the command has started, and `ended` with `{ status, signal? }` as for `spawn`, `128 + n` and the signal's name when a signal ended it. A client's `ended` rejects with `KernelGoneError` when the client goes away, while the process runs on: a new client finds it by its tag in `ps()` and `trace`. To stop it, signal its group (`client.kill(-pgid)`). A refusal rejects before anything runs, with the errno as `code` and the sentence above as the message, ready to show.
+- **Nothing else changes:** no [timestamp](#sudo-timestamps) is written or used, nothing is recorded in `/etc/sudoers.d`, and no request is pending for the user. The run is logged on the kernel's console like a run a timestamp allowed, with `REPLAY=<request id>` where that line has `TIMESTAMP=`: `sudo: cone : TTY=unknown ; PWD=/home/cone ; USER=root ; REPLAY=sudo-1-… ; COMMAND=/usr/bin/systemctl restart nginx`.
+- **Who may call it:** the embedder, and a root client, which may already run anything as anyone; the checks are there so that a run late is the run that was asked for, not to decide who may run it. That's the embedder's to decide, typically only on a person's click.
+
 ### Cron
 
 The kernel runs scheduled jobs itself, with no daemon process: a cron service starts with the kernel and stops with `terminate()`. It reads `/etc/crontab` and the per-user tables in `/var/spool/cron/crontabs/<user>`, and runs each due job as `$SHELL -c '<command>'` (`/bin/bash` unless the table sets `SHELL`) as the table's user, in that user's home (`/` if the home is missing), with no terminal and `/dev/null` as standard input.

package/dist/driver-worker.js

@@ -824,7 +824,7 @@ async function loopbackFetch(dial, input, options) {
 }
 
 // src/client/protocol.ts
-var PROTOCOL = [1, 15];
+var PROTOCOL = [1, 16];
 function locksOf(scope = globalThis) {
   const locks = scope.navigator?.locks;
   return typeof locks?.request === "function" ? locks : void 0;
@@ -1130,6 +1130,19 @@ async function spawnOn(channel, argv, opts) {
     signal: async (name = "SIGTERM") => void await channel.call({ op: "kill", pid: -pgid, signal: name })
   };
 }
+async function sudoRunOn(channel, replay, { stdout, stderr, tag }) {
+  await since(channel, 16, "sudoRun", async () => {
+  });
+  const started = Promise.withResolvers();
+  let endedBy;
+  const { done } = channel.request(
+    { op: "sudo-run", replay, options: { stdout, stderr, tag } },
+    { started: started.resolve, ended: (signal) => endedBy = signal }
+  );
+  done.catch(started.reject);
+  const pid = await started.promise;
+  return { pid, pgid: pid, ended: endedOf(done, () => endedBy) };
+}
 function endedOf(done, signal) {
   return quiet(
     done.then((status) => {
@@ -1331,6 +1344,7 @@ async function attachKernel(port, options = {}) {
       return () => channel.traitsListeners.delete(listener);
     },
     trace: (tag, onEvents, options2 = {}) => traceOn(channel, tag, onEvents, options2),
+    sudoRun: (replay, options2 = {}) => sudoRunOn(channel, replay, options2),
     async close(o = {}) {
       if (channel.failure) return;
       await channel.call({ op: "detach", ...o.kill ? { kill: true } : {} }).catch(() => void 0);