@amritk/nish-x86_64-linux 0.14.0 → 0.16.0

package/INSTALL.md

@@ -403,8 +403,15 @@ release is expected to move it. `--stages 1` stops one link sooner.
 and `--profile` spellings as an installed `nish`, because it is the same
 program, and makes every directory in the way of the IR, a sidecar or the
 binary itself. It looks for `scripts/build.sh` and the two `runtime/*.c` files
-one level up from wherever it was invoked, then in the working directory, so
-it wants a checkout or an installed package around it the way `nish` does.
+one level up from wherever it was invoked (and one level up from the file a
+symbolic link to it names), so it wants a checkout or an installed package
+around it the way `nish` does. It falls back to the working directory only
+when the compiler itself lies inside that directory, so a checkout you merely
+`cd` into cannot hand it a `scripts/build.sh` to run. Keep `bin/nish` beside
+`scripts/`, `runtime/` and `std/`, as every install above does, and keep that
+directory's parent writable only by you: the package root is the parent of
+the compiler's directory, so a compiler at `/tmp/x/nish` would trust
+`/tmp/scripts/build.sh` (CLI-9 in [docs/security/cli.md](security/cli.md)).
 
 Because the seed is the last release, `src/` may only *use* in its own
 source the constructs that release compiles. A new construct is implemented
@@ -457,9 +464,11 @@ nish run hello.ts
 `$XDG_CACHE_HOME/nish/run` (or `~/.cache/nish/run`) when that program has not
 been linked before, and starts it with the arguments after the file. The first
 run of a new edit pays for one link, and later runs start the cached binary.
-It needs clang only for that link. It needs `HOME` or `XDG_CACHE_HOME` set,
-and refuses the run without them rather than keep a binary in a shared
-directory.
+It needs clang only for that link. It needs `HOME` or `XDG_CACHE_HOME` set
+to an absolute path (a relative one is ignored, as if it were unset), and
+refuses the run without one rather than keep a binary in a shared directory.
+The first run that builds into the cache makes its root `0700`, so no other
+user can plant a binary in it ([docs/security/cli.md](security/cli.md)).
 
 ## 4. Exit codes
 
@@ -469,7 +478,7 @@ directory.
 | 1 | the program was rejected: compile error (`file:line:col: error: ...`), missing input file, or an `-o` layout that does not fit the module count |
 | 2 | usage error: unknown flag, missing argument, no input files |
 | 3 | toolchain error: `--link` found no `clang` (`CC` overrides), or `scripts/build.sh` failed (its output is shown; the `.ll` files are still written) — or the `nish` command found no prebuilt compiler for this platform, or one that would not start. Under `--json` all of these are one `NL0002` object |
-| | `nish run` answers these codes until the program starts, and the program's own exit status (`128 + n` for a signal) after that. With neither `HOME` nor `XDG_CACHE_HOME` set it answers 3 |
+| | `nish run` answers these codes until the program starts, and the program's own exit status (`128 + n` for a signal) after that. With neither `HOME` nor `XDG_CACHE_HOME` set to an absolute path it answers 3 |
 | 70 | internal compiler error: an unexpected exception. Please report it at <https://github.com/amritk/nish/issues> with the input and command line; `NISH_DEBUG=1` prints the stack trace |
 
 ## Troubleshooting

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/nish-x86_64-linux",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "The @amritk/nish native compiler for Linux on x86_64",
   "license": "MIT",
   "os": [

package/runtime/nish.d.ts

@@ -248,6 +248,55 @@ declare function signalFd(): i32;
  */
 declare function readSignal(fd: i32): i32;
 
+// ---- `nish:net` (WP34 N5) --------------------------------------------------------
+//
+// Every call answers an `i32`: `>= 0` on success, a negative errno otherwise, in
+// Linux's numbering on every platform for -11 (would block), -95, -32, -104,
+// -98 and -22. An address is 18 bytes of a `u8[]`: 16 of IPv6 address (IPv4 as
+// `::ffff:a.b.c.d`), then the port, big-endian. Every socket is non-blocking and
+// close-on-exec. No reading under Node, where each throws.
+
+/** Write the address form of a numeric `host` and `port` into `out`: 0, or -22. */
+declare function netAddress(out: u8[], host: string, port: i32): i32;
+/** The port the socket `fd` is bound to. */
+declare function netLocalPort(fd: i32): i32;
+/** A listening TCP socket with `SO_REUSEADDR`; `"::"` hears IPv4 and IPv6. */
+declare function tcpListen(host: string, port: i32, backlog: i32): i32;
+/** The next connection's descriptor, its address in `peer`; -11 when none waits. */
+declare function tcpAccept(fd: i32, peer: u8[]): i32;
+/** Up to `len` bytes into `buf` from `off`: the count, 0 at end of stream, or -11. */
+declare function netRead(fd: i32, buf: u8[], off: i32, len: i32): i32;
+/** Up to `len` bytes of `buf` from `off`: the count; a gone peer is -32, never SIGPIPE. */
+declare function netWrite(fd: i32, buf: readonly u8[], off: i32, len: i32): i32;
+/** Shut the read side (0), the write side (1) or both (2). */
+declare function netShutdown(fd: i32, how: i32): i32;
+/** Close the descriptor. */
+declare function netClose(fd: i32): i32;
+/** A UDP socket: flag 1 `SO_REUSEPORT`, flag 2 `UDP_GRO` (-95 on Darwin); ECN is always read. */
+declare function udpBind(host: string, port: i32, flags: i32): i32;
+/** `buf[off, off + len)` to `to`, cut into `segment`-byte datagrams when `segment > 0`, with ECN bits `ecn`. */
+declare function udpSendTo(
+  fd: i32,
+  buf: readonly u8[],
+  off: i32,
+  len: i32,
+  to: readonly u8[],
+  segment: i32,
+  ecn: i32
+): i32;
+/** One datagram, or several GRO coalesced, into `buf[off, off + len)`; the sender in `from`, `meta` [segment size, ECN]. */
+declare function udpRecvFrom(fd: i32, buf: u8[], off: i32, len: i32, from: u8[], meta: i32[]): i32;
+/** A readiness loop, level-triggered: epoll on Linux, kqueue on Darwin. */
+declare function pollCreate(): i32;
+/** Watch `fd` for `events` (1 readable, 2 writable) under `token`. */
+declare function pollAdd(loop: i32, fd: i32, events: i32, token: i32): i32;
+/** New events or a new token for a watched `fd`. */
+declare function pollModify(loop: i32, fd: i32, events: i32, token: i32): i32;
+/** Stop watching `fd`. */
+declare function pollRemove(loop: i32, fd: i32): i32;
+/** Wait up to `timeoutMs` (negative: forever); pairs `ready[2k]` token, `ready[2k + 1]` events (4: hang-up or error). */
+declare function pollWait(loop: i32, ready: i32[], timeoutMs: i32): i32;
+
 // ---- `Date` and `crypto` (WP34 N3) -----------------------------------------------
 //
 // `lib.es2022` already declares `Date`, whose `now()` is Nish's one member of it,
@@ -318,6 +367,48 @@ declare module "nish:process" {
   export const arch: string;
 }
 
+declare module "nish:net" {
+  /** The address form of a numeric `host` and `port` in `out`'s first 18 bytes: 0, or -22. */
+  export function netAddress(out: u8[], host: string, port: i32): i32;
+  /** The port the socket is bound to. */
+  export function netLocalPort(fd: i32): i32;
+  /** A listening TCP socket with `SO_REUSEADDR`; `"::"` hears IPv4 and IPv6. */
+  export function tcpListen(host: string, port: i32, backlog: i32): i32;
+  /** The next connection's descriptor, its address in `peer`; -11 when none waits. */
+  export function tcpAccept(fd: i32, peer: u8[]): i32;
+  /** Up to `len` bytes into `buf` from `off`: the count, 0 at end of stream, or -11. */
+  export function netRead(fd: i32, buf: u8[], off: i32, len: i32): i32;
+  /** Up to `len` bytes of `buf` from `off`: the count; a gone peer is -32, never SIGPIPE. */
+  export function netWrite(fd: i32, buf: readonly u8[], off: i32, len: i32): i32;
+  /** Shut the read side (0), the write side (1) or both (2). */
+  export function netShutdown(fd: i32, how: i32): i32;
+  export function netClose(fd: i32): i32;
+  /** A UDP socket: flag 1 `SO_REUSEPORT`, flag 2 `UDP_GRO` (-95 on Darwin); ECN is always read. */
+  export function udpBind(host: string, port: i32, flags: i32): i32;
+  /** `buf[off, off + len)` to `to`, cut into `segment`-byte datagrams when `segment > 0`, with ECN bits `ecn`. */
+  export function udpSendTo(
+    fd: i32,
+    buf: readonly u8[],
+    off: i32,
+    len: i32,
+    to: readonly u8[],
+    segment: i32,
+    ecn: i32
+  ): i32;
+  /** One datagram, or several GRO coalesced, into `buf[off, off + len)`; the sender in `from`, `meta` [segment size, ECN]. */
+  export function udpRecvFrom(fd: i32, buf: u8[], off: i32, len: i32, from: u8[], meta: i32[]): i32;
+  /** A readiness loop, level-triggered: epoll on Linux, kqueue on Darwin. */
+  export function pollCreate(): i32;
+  /** Watch `fd` for `events` (1 readable, 2 writable) under `token`. */
+  export function pollAdd(loop: i32, fd: i32, events: i32, token: i32): i32;
+  /** New events or a new token for a watched `fd`. */
+  export function pollModify(loop: i32, fd: i32, events: i32, token: i32): i32;
+  /** Stop watching `fd`. */
+  export function pollRemove(loop: i32, fd: i32): i32;
+  /** Wait up to `timeoutMs` (negative: forever); pairs `ready[2k]` token, `ready[2k + 1]` events (4: hang-up or error). */
+  export function pollWait(loop: i32, ready: i32[], timeoutMs: i32): i32;
+}
+
 declare module "nish:io" {
   /** `s` to stdout with no trailing newline and no conversion. */
   export function write(s: string): void;

package/runtime/nish.h

@@ -63,6 +63,17 @@ typedef struct nish_str {
   char data[];
 } nish_str;
 
+/* The bytes of `s` as the C string a system call takes, or "" when `s` holds
+ * a NUL. The kernel reads a path to its first NUL, so `"secret\0.txt"` would
+ * pass a `.txt` check and open `secret`; "" names nothing, so each caller
+ * answers it as it answers a missing path. The one test every path, name and
+ * argument the runtime hands the OS goes through (docs/security/runtime.md,
+ * RT-3). `__builtin_strlen`, so this header needs no libc header of its own,
+ * and `unused` because a host that includes it may never call it. */
+static inline __attribute__((unused)) const char *nish_cpath(const nish_str *s) {
+  return __builtin_strlen(s->data) == s->len ? s->data : "";
+}
+
 /* ---- Arena --------------------------------------------------------------
  * One bump allocator per process, or one per thread under `-DNISH_THREADS`
  * (WP20 T0; the layout and every function below are the same either way).
@@ -139,7 +150,16 @@ nish_str *nish_str_from_i64(int64_t v);
 nish_str *nish_str_from_u64(uint64_t v);
 
 /* Process and file I/O (WP7). `nish_exit` never returns; the file functions
- * print a message to stderr and exit(1) on a fatal error. Everything from here
+ * print a message to stderr and exit(1) on a fatal error.
+ *
+ * Every function here that takes a path, a name or an argument vector refuses
+ * one holding a NUL, answering as it answers a path that does not exist: the
+ * kernel would read only the bytes before the NUL, which is a different path
+ * from the one the program checked (docs/security/runtime.md, RT-3). A file
+ * longer than 2^31 - 1 bytes is unreadable, as it is to `nish_read_file_or_null`
+ * and `nish_read_file_bytes` too, because no string or array may be longer
+ * (RT-1). The two writers refuse a symbolic link as the last component of the
+ * path rather than follow it (RT-4). Everything from here
  * to the end of the clock section below is implemented in runtime-os.c, with
  * `nish_random` and `nish_argv_init` the exceptions: neither asks the operating
  * system anything (the clock only seeds the first, and the entry point hands the
@@ -194,6 +214,11 @@ typedef struct nish_array { uint64_t len; uint64_t cap; char *data; } nish_array
  * `elem_size` is `sizeof` one element, so for a record element type it is
  * `sizeof(struct Point)` and the block is a C array of them. */
 nish_array *nish_alloc_array(uint64_t elem_size, uint64_t len);
+/* No array grows past 2^31 - 1 elements and no string past 2^31 - 1 bytes:
+ * `nish_array_grow`, `nish_alloc_array` and `nish_str_concat` fail as an
+ * allocation does (`nish: out of memory`, exit 1; a trap on wasm) rather than
+ * make one, because under --number-mode i32 its `length` would read back
+ * negative (docs/security/codegen.md K1-6, docs/security/runtime.md RT-2). */
 /* The cold paths compiled code calls: `push` when len == cap, a failed bounds
  * check. `nish_array_grow` moves `cap * elem_size` bytes into a fresh arena
  * block and writes `data`/`cap`, so for a record element type it relocates the
@@ -254,12 +279,12 @@ nish_array *nish_read_file_bytes(const nish_str *path);
  * `128 + n` when signal `n` killed it. -1 when `argv` is empty, when the
  * child cannot be started or waited for, and always under WASI, which has no
  * processes. The elements are `nish_str *`; the child receives their bytes,
- * so an argument containing a NUL is truncated at it. */
+ * and an argument containing a NUL is refused (-1) rather than truncated. */
 int32_t nish_spawn(const nish_array *argv);
 /* `spawnSyncTo(argv, stdoutPath, stderrPath)`: exactly `nish_spawn` — the same
  * `PATH` search, the same wait, the same status, `128 + n` and -1 — except that
  * each non-empty path receives that stream, created or truncated at 0644 as
- * `nish_write_file` would leave it. An **empty** string leaves that stream
+ * `nish_write_file` would leave it, a symbolic link at the path refused. An **empty** string leaves that stream
  * inherited, so one call can capture stdout and let stderr through to the
  * terminal. The child opens the files, so a failed open is a child that could
  * not start and answers -1 rather than leaving this process redirected. The two
@@ -275,8 +300,8 @@ int32_t nish_spawn_to(const nish_array *argv, const nish_str *out, const nish_st
  * arena (so a later `setenv` cannot change a string the program still holds),
  * or NULL when it is unset — the language's `string | null`. An empty value
  * is a set variable and answers a zero-length string, not NULL. `name` is
- * read and never retained; a NUL inside it truncates the lookup, as it does
- * for every other path-like argument here. */
+ * read and never retained; a name holding a NUL is unset, as it is for every
+ * other path-like argument here. */
 nish_str *nish_getenv(const nish_str *name);
 
 /* ---- Symlinks (WP19 §5a item 4) -----------------------------------------
@@ -336,6 +361,73 @@ double nish_stat_mtime(const nish_str *path);
  * or a read that fails. */
 int32_t nish_signal_fd(void);
 int32_t nish_read_signal(int32_t fd);
+/* Who owns a path, and whether it runs (docs/security/runtime.md, RT-9; no
+ * builtin reaches these yet). `nish_lstat_owner_mode(path)`: `lstat`, so a
+ * symbolic link answers for itself, as the owner's uid in the high 32 bits
+ * and `st_mode` in the low 32, or exactly -1 when the path does not resolve.
+ * `nish_euid()`: the effective uid. `nish_is_executable(path)`:
+ * `access(path, X_OK)`, for the real uid. */
+int64_t nish_lstat_owner_mode(const nish_str *path);
+int64_t nish_euid(void);
+bool nish_is_executable(const nish_str *path);
+
+/* ---- The network (WP34 N5), runtime/runtime-net.c, `nish:net` ------------
+ * Every call answers an `int32_t`: `>= 0` on success (a descriptor, a byte
+ * count, 0) and a negative errno otherwise, in Linux's numbering on every
+ * platform for -11 (would block), -95 (unsupported), -32 (the peer is gone),
+ * -104 (reset), -98 (address in use) and -22 (a bad argument). Every socket
+ * is non-blocking and close-on-exec. An address is 18 bytes of a `u8[]`
+ * (element type `uint8_t`): 16 of IPv6 address, IPv4 as `::ffff:a.b.c.d`,
+ * then the port, big-endian; a shorter array is -22. Nothing allocates.
+ *
+ * `nish_net_address(out, host, port)`: the form of a numeric `host`.
+ * `nish_net_local_port(fd)`: the port a socket is bound to.
+ * `nish_tcp_listen(host, port, backlog)`: `SO_REUSEADDR`, and `::` hears
+ * both families, or IPv4 alone on a kernel without IPv6.
+ * `nish_tcp_accept(fd, peer)`: a new descriptor and the peer's address.
+ * `nish_net_read` / `nish_net_write(fd, buf, off, len)`: bytes `[off, off +
+ * len)` of `buf`, which the compiled call has range-checked; a write to a
+ * gone peer is -32, never SIGPIPE. `nish_net_shutdown(fd, how)`: 0 read, 1
+ * write, 2 both. `nish_net_close(fd)`.
+ *
+ * UDP: `nish_udp_bind(host, port, flags)` binds a datagram socket, flag 1
+ * `SO_REUSEPORT` and flag 2 `UDP_GRO` (-95 on Darwin). `nish_udp_send_to(fd,
+ * buf, off, len, to, segment, ecn)` sends `buf[off, off + len)` to the
+ * address `to` in one `sendmsg`, cut into `segment`-byte datagrams by
+ * `UDP_SEGMENT` when `segment > 0`, with the ECN bits `ecn` (0..3); either on
+ * Darwin is -95. `nish_udp_recv_from(fd, buf, off, len, from, meta)` takes
+ * one datagram, or several `UDP_GRO` coalesced, writes the sender into `from`
+ * and into `meta` (element type `int32_t`, at least 2) the segment size, 0
+ * when none was coalesced, and the ECN bits.
+ *
+ * The readiness loop, level-triggered: epoll on Linux, kqueue on Darwin.
+ * `nish_poll_create()` is a close-on-exec loop descriptor.
+ * `nish_poll_add(loop, fd, events, token)` and `nish_poll_modify` watch `fd`
+ * for `events` (1 readable, 2 writable; any other bit is -22) under `token`,
+ * and `nish_poll_remove(loop, fd)` stops. `nish_poll_wait(loop, ready,
+ * timeout_ms)` waits at most `timeout_ms` (a negative one forever) and writes
+ * into `ready` (element type `int32_t`) a token and its events, 4 added for a
+ * hang-up or an error, per ready descriptor: at most `ready->len / 2` pairs
+ * and at most 64 in one call. It answers the count, 0 on a timeout or an
+ * interrupting signal, and -22 for a `ready` shorter than 2. */
+int32_t nish_net_address(nish_array *out, const nish_str *host, int32_t port);
+int32_t nish_net_local_port(int32_t fd);
+int32_t nish_tcp_listen(const nish_str *host, int32_t port, int32_t backlog);
+int32_t nish_tcp_accept(int32_t fd, nish_array *peer);
+int32_t nish_net_read(int32_t fd, nish_array *buf, int64_t off, int64_t len);
+int32_t nish_net_write(int32_t fd, const nish_array *buf, int64_t off, int64_t len);
+int32_t nish_net_shutdown(int32_t fd, int32_t how);
+int32_t nish_net_close(int32_t fd);
+int32_t nish_udp_bind(const nish_str *host, int32_t port, int32_t flags);
+int32_t nish_udp_send_to(int32_t fd, const nish_array *buf, int64_t off, int64_t len, const nish_array *to,
+                         int32_t segment, int32_t ecn);
+int32_t nish_udp_recv_from(int32_t fd, nish_array *buf, int64_t off, int64_t len, nish_array *from,
+                           nish_array *meta);
+int32_t nish_poll_create(void);
+int32_t nish_poll_add(int32_t loop, int32_t fd, int32_t events, int32_t token);
+int32_t nish_poll_modify(int32_t loop, int32_t fd, int32_t events, int32_t token);
+int32_t nish_poll_remove(int32_t loop, int32_t fd);
+int32_t nish_poll_wait(int32_t loop, nish_array *ready, int32_t timeout_ms);
 
 /* String to number (WP7), ASCII whitespace only. mode 0 is `parseFloat`
  * (longest JS decimal literal or `Infinity`, else NaN), mode 1 is `Number`

package/runtime/nish.mjs

@@ -98,6 +98,29 @@ provide("statMtimeSync", shim.statMtimeSync);
 provide("signalFd", shim.signalFd);
 provide("readSignal", shim.readSignal);
 
+// `nish:net` (WP34 N5). Each throws, naming itself: a socket is ready only to
+// Node's event loop, which a program that owns its loop never returns to.
+for (const name of [
+  "netAddress",
+  "netLocalPort",
+  "tcpListen",
+  "tcpAccept",
+  "netRead",
+  "netWrite",
+  "netShutdown",
+  "netClose",
+  "udpBind",
+  "udpSendTo",
+  "udpRecvFrom",
+  "pollCreate",
+  "pollAdd",
+  "pollModify",
+  "pollRemove",
+  "pollWait",
+]) {
+  provide(name, () => shim.noNetReading(name));
+}
+
 // `crypto.getRandomValues(bytes)` (WP34 N3). Node has the global, but it
 // takes only a typed array and a `u8[]` is a plain `Array` here, so the one
 // method is replaced on Node's own `crypto` object by one that fills a plain

package/runtime/runtime-host.c

@@ -1,7 +1,8 @@
 /* Nish runtime, the host half: the wall clock, entropy, a file's modification
  * time and a descriptor that becomes readable when SIGTERM or SIGINT arrives
  * (WP34 N3) — the four facts a program that runs for days asks of the machine
- * it runs on.
+ * it runs on — and who owns a path and whether it runs, which a driver asks
+ * before it trusts one.
  *
  * A translation unit of its own for the reason runtime-os.c is one: each file
  * carries its own measured `.text*` ceiling in tests/run.js. runtime-os.c had
@@ -33,6 +34,7 @@ typedef int nish_host_unused;
 #include <signal.h>
 #include <stdint.h>
 #include <stdio.h>
+#include <string.h>
 #include <sys/stat.h>
 #include <time.h>
 #include <unistd.h>
@@ -98,7 +100,7 @@ void nish_random_fill(nish_array *bytes) {
    digits. `stat` follows a symbolic link, as `fs.statSync` does. */
 double nish_stat_mtime(const nish_str *path) {
   struct stat st;
-  if (stat(path->data, &st) != 0) return __builtin_nan("");
+  if (stat(nish_cpath(path), &st) != 0) return __builtin_nan("");
 #if defined(__APPLE__)
   struct timespec t = st.st_mtimespec;
 #else
@@ -107,6 +109,31 @@ double nish_stat_mtime(const nish_str *path) {
   return (double)t.tv_sec * 1e3 + (double)t.tv_nsec / 1e6;
 }
 
+/* ---- Who owns a path, and whether it runs (docs/security/runtime.md, RT-9)
+ *
+ * The primitives a driver needs before it trusts a directory or a program it
+ * found on its own. `nish_lstat_owner_mode` answers for the path itself, a
+ * symbolic link included, rather than for what it names: the owner's uid in
+ * the high 32 bits and `st_mode` in the low 32, or exactly -1 when the path
+ * does not resolve or holds a NUL. `nish_euid` is the user to compare the
+ * owner with, and `nish_is_executable` is `access(X_OK)`: whether the real
+ * user may run the file, which is what tells an executable `PATH` entry from
+ * one that is only readable. Nothing in the language reaches them yet: `src/` may call
+ * a runtime function only once the last release declares it, so they are here
+ * for the change after the next release (docs/security/cli.md, CLI-7 and
+ * CLI-9). */
+int64_t nish_lstat_owner_mode(const nish_str *path) {
+  struct stat st;
+  if (lstat(nish_cpath(path), &st) != 0) return -1;
+  return (int64_t)((uint64_t)(uint32_t)st.st_uid << 32 | (uint32_t)st.st_mode);
+}
+
+int64_t nish_euid(void) { return (int64_t)geteuid(); }
+
+_Bool nish_is_executable(const nish_str *path) {
+  return access(nish_cpath(path), X_OK) == 0;
+}
+
 /* ---- Signals: `signalFd()` and `readSignal(fd)`
  *
  * A descriptor rather than a handler in the language, because a handler would