@nimbus-sh/core 0.1.0

package/src/runtime/wasm-memory.ts

@@ -0,0 +1,261 @@
+/**
+ * wasm-memory.ts — declared allocation limits for wasm processes.
+ *
+ * What the host can and cannot control
+ * ────────────────────────────────────
+ * `malloc` is dlmalloc compiled into the guest's own linear memory, and
+ * `memory.grow` is a wasm *instruction* (opcode 0x40), not an import. There is
+ * therefore no host hook on a guest allocation: the guest asks the engine for
+ * pages directly and the host is never consulted.
+ *
+ * The one lever the host does hold is the memory's DECLARED MAXIMUM. Every
+ * wasm binary Nimbus runs (bash, busybox, opentui, …) defines its own memory
+ * with limits flags `0x00` — a minimum and NO maximum — so `memory.grow`
+ * succeeds until the isolate itself dies. That is the silent-isolate-kill
+ * failure mode: the guest never learns it ran out of memory, because from its
+ * point of view every grow succeeded right up until the process vanished.
+ *
+ * `withMemoryLimit` rewrites the memory section's limits to carry an explicit
+ * maximum. Past that maximum `memory.grow` returns -1, dlmalloc's `sbrk`
+ * fails, `malloc` returns NULL, and the program reports an honest allocation
+ * failure through its own error path. The isolate survives; the guest reports
+ * ENOMEM. Nothing else about the module changes.
+ *
+ * Scope, stated honestly: this governs the ceiling, not the allocation rate.
+ * A guest that stays under the cap is unobserved, and there is no way to
+ * observe it — a compiled wasm load or store is a raw machine access with no
+ * host hook, so page-level accounting is unreachable for a natively-compiled
+ * module.
+ */
+
+/** wasm page size. Fixed by the specification. */
+export const WASM_PAGE_BYTES = 65536;
+
+/** wasm32 address-space ceiling: 65536 pages of 64 KiB = 4 GiB. */
+export const WASM32_MAX_PAGES = 65536;
+
+/**
+ * Default ceiling for one wasm process's linear memory.
+ *
+ * Measured on prod workerd (throwaway account-pinned DO, 2026-08-02): a
+ * Durable Object sustains ~200 MiB of live wasm linear memory and is then
+ * killed, and it makes no difference whether those pages were written to or
+ * merely reserved — the untouched and fully-filled arms died at exactly the
+ * same 200 MiB. Reserving address space is billed at full price, so there is
+ * no headroom to be had by growing lazily.
+ *
+ * 128 MiB leaves ~70 MiB of that measured ceiling for the facet's own JS
+ * heap, the module text, and the runner's buffers. It is a budget rather than
+ * a measurement of any particular workload's need, and unlike the supervisor
+ * heap budget this one IS enforced — `withMemoryLimit` puts it where a guest
+ * `memory.grow` can see it.
+ */
+export const DEFAULT_WASM_PROCESS_LIMIT_BYTES = 128 * 1024 * 1024;
+
+/** Limits declared by a wasm memory, in pages. */
+export interface WasmMemoryLimits {
+  readonly minPages: number;
+  /** `null` when the binary declares no maximum — growth is unbounded. */
+  readonly maxPages: number | null;
+  /** Raw limits flags. Bit 0 = has-maximum, bit 1 = shared, bit 2 = memory64. */
+  readonly flags: number;
+}
+
+// ── binary walking ───────────────────────────────────────────────────────────
+//
+// Only two sections matter here: the import section (id 2), which tells us
+// whether the memory is supplied by the host, and the memory section (id 5),
+// which declares it. Everything else is copied through byte-for-byte.
+
+const SECTION_IMPORT = 2;
+const SECTION_MEMORY = 5;
+
+class Cursor {
+  offset: number;
+  constructor(readonly bytes: Uint8Array, offset = 0) {
+    this.offset = offset;
+  }
+  u8(): number {
+    if (this.offset >= this.bytes.length) throw new Error('wasm: truncated');
+    return this.bytes[this.offset++];
+  }
+  /** Unsigned LEB128. */
+  varuint(): number {
+    let result = 0;
+    let shift = 0;
+    for (;;) {
+      const byte = this.u8();
+      result += (byte & 0x7f) * 2 ** shift;
+      if ((byte & 0x80) === 0) return result;
+      shift += 7;
+      if (shift > 35) throw new Error('wasm: varuint too long');
+    }
+  }
+  skip(n: number): void {
+    this.offset += n;
+  }
+}
+
+function encodeVaruint(value: number): number[] {
+  const out: number[] = [];
+  let v = value;
+  do {
+    let byte = v & 0x7f;
+    v = Math.floor(v / 128);
+    if (v !== 0) byte |= 0x80;
+    out.push(byte);
+  } while (v !== 0);
+  return out;
+}
+
+function readLimits(cursor: Cursor): WasmMemoryLimits {
+  const flags = cursor.varuint();
+  const minPages = cursor.varuint();
+  const maxPages = (flags & 1) !== 0 ? cursor.varuint() : null;
+  return { flags, minPages, maxPages };
+}
+
+interface Section {
+  readonly id: number;
+  /** Offset of the section id byte. */
+  readonly start: number;
+  /** Offset of the first payload byte. */
+  readonly payload: number;
+  readonly size: number;
+}
+
+function* sections(bytes: Uint8Array): Generator<Section> {
+  if (bytes.length < 8) throw new Error('wasm: not a module (too short)');
+  if (bytes[0] !== 0x00 || bytes[1] !== 0x61 || bytes[2] !== 0x73 || bytes[3] !== 0x6d) {
+    throw new Error('wasm: bad magic');
+  }
+  const cursor = new Cursor(bytes, 8);
+  while (cursor.offset < bytes.length) {
+    const start = cursor.offset;
+    const id = cursor.u8();
+    const size = cursor.varuint();
+    const payload = cursor.offset;
+    yield { id, start, payload, size };
+    cursor.offset = payload + size;
+  }
+}
+
+/** Skip one import entry's descriptor, returning its memory limits if it is one. */
+function readImportDescriptor(cursor: Cursor): WasmMemoryLimits | null {
+  const kind = cursor.u8();
+  switch (kind) {
+    case 0x00: // function: type index
+      cursor.varuint();
+      return null;
+    case 0x01: // table: reftype + limits
+      cursor.u8();
+      readLimits(cursor);
+      return null;
+    case 0x02: // memory: limits
+      return readLimits(cursor);
+    case 0x03: // global: valtype + mutability
+      cursor.u8();
+      cursor.u8();
+      return null;
+    default:
+      throw new Error(`wasm: unknown import kind ${kind}`);
+  }
+}
+
+/**
+ * Read the module's linear-memory declaration.
+ *
+ * Returns `null` for a module that neither defines nor imports a memory.
+ * `imported` distinguishes the two cases that matter: an imported memory is
+ * created by the host, so its limits are ours to choose at instantiation and
+ * no binary rewrite is needed.
+ */
+export function readMemoryLimits(
+  bytes: Uint8Array,
+): (WasmMemoryLimits & { imported: boolean }) | null {
+  for (const section of sections(bytes)) {
+    if (section.id === SECTION_IMPORT) {
+      const cursor = new Cursor(bytes, section.payload);
+      const count = cursor.varuint();
+      for (let i = 0; i < count; i++) {
+        cursor.skip(cursor.varuint()); // module name
+        cursor.skip(cursor.varuint()); // field name
+        const limits = readImportDescriptor(cursor);
+        if (limits) return { ...limits, imported: true };
+      }
+    } else if (section.id === SECTION_MEMORY) {
+      const cursor = new Cursor(bytes, section.payload);
+      const count = cursor.varuint();
+      if (count === 0) continue;
+      return { ...readLimits(cursor), imported: false };
+    }
+  }
+  return null;
+}
+
+/**
+ * Return a copy of `bytes` whose defined memory carries an explicit maximum of
+ * at most `limitBytes`.
+ *
+ * The cap is only ever lowered: a module that already declares a tighter
+ * maximum keeps it. Returns the input unchanged when the module imports its
+ * memory (the host picks the limits at instantiation instead) or declares no
+ * memory at all.
+ *
+ * Throws when `limitBytes` is below the module's declared minimum — capping
+ * there would produce a module that cannot instantiate, which is a worse
+ * failure than the one we are preventing.
+ */
+export function withMemoryLimit(bytes: Uint8Array, limitBytes: number): Uint8Array {
+  if (!Number.isFinite(limitBytes) || limitBytes <= 0) {
+    throw new RangeError(`withMemoryLimit: limitBytes must be positive, got ${limitBytes}`);
+  }
+  const limitPages = Math.min(Math.floor(limitBytes / WASM_PAGE_BYTES), WASM32_MAX_PAGES);
+
+  for (const section of sections(bytes)) {
+    if (section.id !== SECTION_MEMORY) continue;
+
+    const cursor = new Cursor(bytes, section.payload);
+    const count = cursor.varuint();
+    if (count === 0) return bytes;
+    const entryStart = cursor.offset;
+    const limits = readLimits(cursor);
+    const entryEnd = cursor.offset;
+
+    if (limits.minPages > limitPages) {
+      throw new RangeError(
+        `withMemoryLimit: limit of ${limitPages} pages is below the module's ` +
+        `declared minimum of ${limits.minPages} pages`,
+      );
+    }
+    const maxPages = limits.maxPages === null
+      ? limitPages
+      : Math.min(limits.maxPages, limitPages);
+    if (limits.maxPages === maxPages) return bytes;
+
+    // Re-encode this one entry with the has-maximum bit set, preserving the
+    // shared and memory64 bits, then rebuild the section around it.
+    const entry = [
+      ...encodeVaruint(limits.flags | 1),
+      ...encodeVaruint(limits.minPages),
+      ...encodeVaruint(maxPages),
+    ];
+    const tail = bytes.subarray(entryEnd, section.payload + section.size);
+    const countBytes = bytes.subarray(section.payload, entryStart);
+    const payload = new Uint8Array(countBytes.length + entry.length + tail.length);
+    payload.set(countBytes, 0);
+    payload.set(entry, countBytes.length);
+    payload.set(tail, countBytes.length + entry.length);
+
+    const header = [section.id, ...encodeVaruint(payload.length)];
+    const head = bytes.subarray(0, section.start);
+    const rest = bytes.subarray(section.payload + section.size);
+    const out = new Uint8Array(head.length + header.length + payload.length + rest.length);
+    out.set(head, 0);
+    out.set(header, head.length);
+    out.set(payload, head.length + header.length);
+    out.set(rest, head.length + header.length + payload.length);
+    return out;
+  }
+  return bytes;
+}

package/src/shell/elevation-commands.ts

@@ -0,0 +1,117 @@
+import { CRED_KERNEL } from '../runtime/os-contracts.js';
+import type { Command, CommandContext } from '../substrate/lifo/commands/types.js';
+import { credForUnixUser, findUnixUser } from './unix-accounts.js';
+
+function symbolicUmask(mask: number): string {
+  const permissions = 0o777 & ~mask;
+  const classText = (shift: number): string => {
+    const bits = (permissions >> shift) & 0o7;
+    return `${bits & 0o4 ? 'r' : ''}${bits & 0o2 ? 'w' : ''}${bits & 0o1 ? 'x' : ''}`;
+  };
+  return `u=${classText(6)},g=${classText(3)},o=${classText(0)}`;
+}
+
+export function createUmaskCommand(): Command {
+  return async (ctx) => {
+    if (!ctx.cred) {
+      ctx.stderr.write('umask: process credential is unavailable\n');
+      return 1;
+    }
+    if (ctx.args.length === 0 || (ctx.args.length === 1 && ctx.args[0] === '-S')) {
+      ctx.stdout.write(ctx.args[0] === '-S'
+        ? `${symbolicUmask(ctx.cred.umask)}\n`
+        : `${ctx.cred.umask.toString(8).padStart(4, '0')}\n`);
+      return 0;
+    }
+    if (ctx.args.length !== 1 || !/^[0-7]{1,4}$/.test(ctx.args[0])) {
+      ctx.stderr.write(`umask: invalid mask: ${ctx.args.join(' ')}\n`);
+      return 1;
+    }
+    const mask = Number.parseInt(ctx.args[0], 8);
+    if (mask > 0o777 || !ctx.setUmask) {
+      ctx.stderr.write(`umask: invalid mask: ${ctx.args[0]}\n`);
+      return 1;
+    }
+    ctx.setUmask(mask);
+    return 0;
+  };
+}
+
+function targetCredential(ctx: CommandContext, name: string) {
+  if (!ctx.cred) throw new Error('process credential is unavailable');
+  const user = findUnixUser(ctx.vfs, name);
+  if (!user) throw new Error(`unknown user: ${name}`);
+  if (user.uid === 0) return CRED_KERNEL;
+  return credForUnixUser(ctx.vfs, user, ctx.cred.umask);
+}
+
+async function runAs(
+  commandName: 'su' | 'sudo',
+  ctx: CommandContext,
+  userName: string,
+  argv: string[],
+): Promise<number> {
+  if (!ctx.runAs) {
+    ctx.stderr.write(`${commandName}: process spawning is unavailable\n`);
+    return 1;
+  }
+  try {
+    return await ctx.runAs(targetCredential(ctx, userName), argv);
+  } catch (error) {
+    ctx.stderr.write(`${commandName}: ${error instanceof Error ? error.message : String(error)}\n`);
+    return 1;
+  }
+}
+
+export function createSudoCommand(): Command {
+  return async (ctx) => {
+    let userName = 'root';
+    let index = 0;
+    if (ctx.args[index] === '-u') {
+      userName = ctx.args[index + 1] ?? '';
+      index += 2;
+      if (!userName) {
+        ctx.stderr.write('sudo: option -u requires a user\n');
+        return 1;
+      }
+    }
+    const argv = ctx.args.slice(index);
+    if (argv.length === 0) {
+      ctx.stderr.write('sudo: a command is required\n');
+      return 1;
+    }
+    return runAs('sudo', ctx, userName, argv);
+  };
+}
+
+export function createSuCommand(): Command {
+  return async (ctx) => {
+    let index = 0;
+    while (ctx.args[index] === '-' || ctx.args[index] === '-l' || ctx.args[index] === '--login') index++;
+
+    let userName = 'root';
+    const candidate = ctx.args[index];
+    if (candidate && candidate !== '-c' && candidate !== '--command') {
+      userName = candidate;
+      index++;
+    }
+
+    let argv = ['sh'];
+    if (ctx.args[index] === '-c' || ctx.args[index] === '--command') {
+      const command = ctx.args[index + 1];
+      if (command === undefined) {
+        ctx.stderr.write('su: option -c requires a command\n');
+        return 1;
+      }
+      if (index + 2 !== ctx.args.length) {
+        ctx.stderr.write('su: unexpected operand\n');
+        return 1;
+      }
+      argv = ['sh', '-c', command];
+    } else if (index !== ctx.args.length) {
+      ctx.stderr.write('su: unexpected operand\n');
+      return 1;
+    }
+    return runAs('su', ctx, userName, argv);
+  };
+}

package/src/shell/exec-dispatch.ts

@@ -0,0 +1,201 @@
+/**
+ * exec-dispatch — POSIX execve semantics for path-shaped shell invocations
+ * (`./x`, `/abs/x`, `../x`). Pure decision logic; the resolve-hook in
+ * session/init.ts turns decisions into commands (wasm-runner, shebang
+ * interpreter, sh fallback, or an error writer).
+ *
+ * Decision ladder (mirrors execve + the shell's ENOEXEC fallback):
+ *   1. no exec bit → EACCES ("permission denied"), with one grandfather
+ *      exception: wasm-magic files whose stored mode was never explicitly
+ *      set stay executable (see below).
+ *   2. `\0asm` magic → run via wasm-runner (the platform's native format).
+ *   3. `#!` line → run via the named interpreter.
+ *   4. binary-looking content (NUL byte in the head) → ENOEXEC surfaced as
+ *      an honest "exec format not supported" error (ELF and friends).
+ *   5. anything else → run as a shell script (POSIX ENOEXEC sh fallback).
+ *
+ * Grandfather rule (WASI-PLAN Stage 1): before Stage 1, chmod was a no-op,
+ * so no stored mode was ever explicitly chosen by a user — wasm binaries
+ * auto-ran on magic alone. Explicitly-set modes are stamped with POSIX
+ * S_IF* filetype bits (SqliteVFS.chmod); bare permission values mean "mode
+ * metadata was never set", and wasm-magic files with such modes stay
+ * executable until touched. No migration.
+ */
+
+import type { CommandRegistry } from '../substrate/lifo/commands/registry.js';
+import type { Command, CommandContext } from '../substrate/lifo/commands/types.js';
+import type { CredentialedVfs } from '../vfs/sqlite-vfs.js';
+import { normalizeVfsPath, resolveVfsPath } from '../vfs/path.js';
+
+export interface ShebangLine {
+  /** Interpreter as written (e.g. "/usr/bin/env" resolved → "node"). */
+  interpreter: string;
+  /** Optional interpreter arguments from the shebang line. */
+  args: string[];
+}
+
+export type ExecDispatchDecision =
+  | { kind: 'wasm' }
+  | { kind: 'shebang'; shebang: ShebangLine }
+  | { kind: 'shell-script' }
+  | { kind: 'denied' }
+  | { kind: 'exec-format-error' };
+
+/** Bytes of head to inspect: covers magic + the longest useful `#!` line. */
+export const EXEC_HEAD_BYTES = 512;
+
+export function isWasmMagic(head: Uint8Array): boolean {
+  return head.length >= 4
+    && head[0] === 0x00 && head[1] === 0x61
+    && head[2] === 0x73 && head[3] === 0x6d;
+}
+
+export function isExecutableMode(mode: number, wasmMagic: boolean): boolean {
+  if ((mode & 0o111) !== 0) return true;
+  return wasmMagic && (mode & 0o170000) === 0;
+}
+
+/**
+ * Parse a `#!interp [args...]` first line. `#!/usr/bin/env X [args]`
+ * resolves to interpreter X (env's `-S`/`--split-string` is transparent —
+ * both forms word-split here anyway).
+ */
+export function parseShebang(head: Uint8Array): ShebangLine | null {
+  if (head.length < 3 || head[0] !== 0x23 || head[1] !== 0x21) return null;
+  const nl = head.indexOf(0x0a);
+  const lineBytes = head.subarray(2, nl === -1 ? head.length : nl);
+  const line = new TextDecoder().decode(lineBytes).replace(/\r$/, '');
+  const words = line.trim().split(/[ \t]+/).filter(Boolean);
+  if (words.length === 0) return null;
+  let interpreter = words[0];
+  let args = words.slice(1);
+  if (basename(interpreter) === 'env') {
+    while (args[0] === '-S' || args[0] === '--split-string') args = args.slice(1);
+    if (args.length === 0) return null;
+    interpreter = args[0];
+    args = args.slice(1);
+  }
+  return { interpreter, args };
+}
+
+export function basename(path: string): string {
+  const slash = path.lastIndexOf('/');
+  return slash >= 0 ? path.slice(slash + 1) : path;
+}
+
+export function decideExecDispatch(mode: number, head: Uint8Array): ExecDispatchDecision {
+  const wasm = isWasmMagic(head);
+  if (!isExecutableMode(mode, wasm)) return { kind: 'denied' };
+  if (wasm) return { kind: 'wasm' };
+  const shebang = parseShebang(head);
+  if (shebang) return { kind: 'shebang', shebang };
+  if (head.includes(0)) return { kind: 'exec-format-error' };
+  return { kind: 'shell-script' };
+}
+
+export function installPathExecResolver(
+  registry: CommandRegistry,
+  kernelFs: CredentialedVfs,
+  getCwd: () => string,
+): void {
+  const originalResolve = registry.resolve.bind(registry);
+  registry.resolve = async (name: string): Promise<Command | undefined> => {
+    const found = await originalResolve(name);
+    if (found) return found;
+    if (!name || (!name.startsWith('./') && !name.startsWith('/') && !name.startsWith('../'))) {
+      return undefined;
+    }
+
+    const resolved = resolveVfsPath(name, normalizeVfsPath(getCwd()));
+    if (!kernelFs.exists(resolved)) return undefined;
+    if (kernelFs.isDirectory(resolved)) {
+      return async (ctx): Promise<number> => {
+        ctx.stderr.write(`${name}: Is a directory\n`);
+        return 126;
+      };
+    }
+
+    const target = kernelFs.isSymlink(resolved) ? kernelFs.resolveSymlink(resolved) : resolved;
+    if (!target || !kernelFs.exists(target) || kernelFs.isDirectory(target)) return undefined;
+
+    let mode: number;
+    let head: Uint8Array;
+    try {
+      mode = kernelFs.stat(target).mode;
+      head = kernelFs.readRange(target, 0, EXEC_HEAD_BYTES);
+    } catch {
+      return undefined;
+    }
+
+    const accessPath = '/' + resolved;
+    const absPath = '/' + target;
+    const authorize = (command: Command): Command => async (ctx): Promise<number> => {
+      try {
+        ctx.vfs.access(accessPath, 0o1);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.startsWith('ENOENT:')) {
+          ctx.stderr.write(`${name}: No such file or directory\n`);
+          return 127;
+        }
+        if (message.startsWith('EACCES:') || message.startsWith('EPERM:')) {
+          ctx.stderr.write(`${name}: Permission denied\n`);
+          return 126;
+        }
+        ctx.stderr.write(`${name}: ${message}\n`);
+        return 126;
+      }
+      return command(ctx);
+    };
+
+    const decision = decideExecDispatch(mode, head);
+    switch (decision.kind) {
+      case 'denied':
+        return authorize(async (ctx): Promise<number> => {
+          ctx.stderr.write(`${name}: Permission denied\n`);
+          return 126;
+        });
+      case 'exec-format-error':
+        return authorize(async (ctx): Promise<number> => {
+          ctx.stderr.write(`${name}: cannot execute binary file: exec format not supported on Nimbus (wasm32-wasi only)\n`);
+          return 126;
+        });
+      case 'wasm': {
+        const wasmRunnerCmd = await originalResolve('wasm-runner');
+        if (!wasmRunnerCmd) return undefined;
+        return authorize(async (ctx): Promise<number> => {
+          return await wasmRunnerCmd({ ...ctx, args: [absPath, ...ctx.args] });
+        });
+      }
+      case 'shebang':
+      case 'shell-script': {
+        const interp = decision.kind === 'shebang' ? decision.shebang.interpreter : 'sh';
+        const interpArgs = decision.kind === 'shebang' ? decision.shebang.args : [];
+        return authorize(async (ctx): Promise<number> => {
+          const depth = interpreterDepth(ctx);
+          if (depth >= 4) {
+            ctx.stderr.write(`${name}: too many levels of interpreters\n`);
+            return 126;
+          }
+          let interpCmd = await registry.resolve(interp);
+          if (!interpCmd && interp.includes('/')) {
+            interpCmd = await registry.resolve(basename(interp));
+          }
+          if (!interpCmd) {
+            ctx.stderr.write(`${name}: ${interp}: bad interpreter: No such file or directory\n`);
+            return 127;
+          }
+          return await interpCmd({
+            ...ctx,
+            args: [...interpArgs, absPath, ...ctx.args],
+            execInterpreterDepth: depth + 1,
+          });
+        });
+      }
+    }
+  };
+}
+
+function interpreterDepth(ctx: CommandContext): number {
+  return ctx.execInterpreterDepth ?? 0;
+}