@supermachine/core 0.5.2 → 0.5.5

package/README.md

@@ -182,6 +182,40 @@ const image = await Image.build({
 
 Host file contents are folded into the snapshot's input-hash, so editing the host file invalidates the cache and rebakes automatically.
 
+### Pattern 5: Live host directory mount (virtio-fs DAX)
+
+For dev loops, code-mounted-from-host workflows, and "run my project" sandboxes, you want a *live* host directory inside the guest — edits on the host show up in the guest immediately, and the guest can read/write back. This is what `mounts` does: a virtio-fs share with DAX (zero-copy reads through the host page cache, kqueue-driven cache invalidation when host files change).
+
+```ts
+const image = await Image.build({
+  ref: "node:20-alpine",
+  mounts: [
+    {
+      hostPath: "/Users/me/my-app",   // host source tree
+      guestTag: "workspace",          // guest mounts via this tag
+      symlinks: "opaque",             // see below
+    },
+  ],
+});
+
+const vm = await (await image.pool()).acquire();
+// Inside the guest:
+//   mount -t virtiofs workspace /work
+//   cd /work && npm install
+```
+
+**`symlinks` policy** picks the trust posture for the mount. Workspace tools (npm workspaces, pnpm, yarn berry) symlink prolifically — `node_modules/<member> → ../packages/<member>` — so symlink creation has to work. But symlinks are also the classic escape vector if you're running untrusted code. The policy lets integrators pick:
+
+| Value | Guest can create symlinks? | External host symlinks visible/traversable? | When |
+|---|---|---|---|
+| `"deny"` | no (`EPERM`) | no (`EACCES` at LOOKUP) | Paranoid mounts: pure file content, no metadata surprises |
+| `"opaque"` *(default)* | yes — targets stored verbatim, host never resolves them | no | **Safe multi-tenant default**: npm/pnpm/yarn all work; a hostile guest can plant `escape → /etc/passwd` but the host never follows it |
+| `"follow"` | yes | yes | Trusted single-tenant: dev trees that symlink into Homebrew/`~/.cache`/etc. |
+
+The `"opaque"` default exists because of how `symlink(2)` works: the target is opaque bytes stored on the symlink inode — POSIX never validates it. Resolution happens *in the guest's kernel* against the guest's own namespace, so a target like `/etc/passwd` resolves to the guest's `/etc/passwd`, not the host's. The host serves `readlink()` (returns those bytes) and refuses to follow them. That's the security model: guest can store arbitrary bytes, host never canonicalizes guest-supplied paths.
+
+A runnable example is in [`examples/06-mount-workspace.mjs`](./examples/06-mount-workspace.mjs).
+
 ---
 
 ## Full API
@@ -217,6 +251,7 @@ class Image {
 | `guestPort` | `number` | 80 | Listener port (used with `listenerRequired`) |
 | `listenerRequired` | `boolean` | `false` | Wait for workload's listener before snapshotting |
 | `extraFiles` | `ExtraFile[]` | — | Stage host files into guest at fixed paths |
+| `mounts` | `MountSpec[]` | — | Live host dir mounts via virtio-fs DAX. See Pattern 5. |
 | `warmupTag` | `string` | `"default"` | Cache key for the warmup; bump to invalidate |
 | `warmup` | `(vm: WarmupVm) => Promise<void>` | — | Post-bake state pre-population |
 | `snapshotsDir` | `string` | `~/.local/supermachine-snapshots` | Where to write the snapshot |

package/examples/06-mount-workspace.mjs

@@ -0,0 +1,97 @@
+// 06-mount-workspace.mjs — mount a host directory into the guest via
+// virtio-fs DAX, then run an `npm install`-style symlink workflow
+// from inside the VM.
+//
+// Demonstrates:
+//   - `mounts: [{ hostPath, guestTag, symlinks }]` on Image.build
+//   - The per-mount `symlinks` policy: "deny" | "opaque" | "follow"
+//   - The npm-workspace symlink pattern (node_modules/<name> →
+//     ../packages/<name>) working end-to-end through virtio-fs
+//
+// The mount surfaces host files in the guest with zero-copy DAX
+// reads and kqueue-driven cache invalidation when the host file
+// changes — edit a file on the host, the guest sees the new bytes
+// on the next read with no manual re-mount.
+//
+// `symlinks: "opaque"` is the safe default for guest-writable mounts
+// in a multi-tenant setting: guest can create symlinks (workspace
+// tools need this), targets are stored verbatim (POSIX symlink(2)),
+// and the host never resolves them. A guest planting
+// `escape -> /etc/passwd` gets a symlink whose readlink returns
+// "/etc/passwd" bytes — but the host won't follow it. Path
+// resolution happens in the guest's kernel against the guest's
+// own namespace.
+//
+// Run:
+//   node examples/06-mount-workspace.mjs
+
+import { Image } from "@supermachine/core";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+// 1. Build a host-side workspace tree that mimics what npm creates:
+//      project/
+//        packages/alpha/index.js   "ALPHA"
+//        packages/beta/index.js    "BETA"
+//    Inside the guest we'll add node_modules/<name> symlinks
+//    pointing at ../packages/<name>.
+const project = mkdtempSync(join(tmpdir(), "sm-workspace-"));
+mkdirSync(join(project, "packages", "alpha"), { recursive: true });
+mkdirSync(join(project, "packages", "beta"), { recursive: true });
+writeFileSync(join(project, "packages", "alpha", "index.js"), "ALPHA");
+writeFileSync(join(project, "packages", "beta", "index.js"), "BETA");
+
+// 2. Bake an image with the project mounted at guest tag "workspace".
+//    `symlinks: "opaque"` is the default but spelled out here for
+//    documentation value.
+const img = await Image.build({
+  ref: "alpine:latest",
+  name: "mount-workspace-demo",
+  memoryMib: 256,
+  cmd: ["/bin/sh", "-c", "sleep infinity"],
+  mounts: [
+    {
+      hostPath: project,
+      guestTag: "workspace",
+      symlinks: "opaque",
+    },
+  ],
+});
+
+const pool = await img.pool({ min: 1, max: 1, restoreOnRelease: false });
+const vm = await pool.acquire();
+
+// 3. Inside the guest: mount the virtio-fs share, create the
+//    workspace symlinks, resolve through them.
+const result = await vm.exec({
+  argv: [
+    "sh",
+    "-c",
+    [
+      "mkdir -p /work && mount -t virtiofs workspace /work",
+      "mkdir -p /work/node_modules",
+      "ln -s ../packages/alpha /work/node_modules/alpha",
+      "ln -s ../packages/beta  /work/node_modules/beta",
+      "echo === readlink ===",
+      "readlink /work/node_modules/alpha",
+      "readlink /work/node_modules/beta",
+      "echo === resolve through ===",
+      "cat /work/node_modules/alpha/index.js",
+      "cat /work/node_modules/beta/index.js",
+    ].join(" && "),
+  ],
+  timeoutMs: 10_000,
+});
+console.log(result.stdout.toString());
+
+// 4. Host-side: confirm the symlinks landed on disk as real
+//    symlinks (not regular files), with the bytes the guest asked
+//    for. This is the "store-target-verbatim" guarantee in action.
+console.log("=== host-side symlink targets ===");
+console.log("alpha →", readlinkSync(join(project, "node_modules", "alpha")));
+console.log("beta  →", readlinkSync(join(project, "node_modules", "beta")));
+
+await vm.release();
+await pool.shutdown();
+rmSync(project, { recursive: true, force: true });

package/examples/README.md

@@ -11,6 +11,7 @@ with the package installed.
 | `03-snapshot-then-restore.mjs` | `vm.writeFile` / `readFile`, mid-flight `vm.snapshot()`, `Image.fromSnapshot` |
 | `04-expose-tcp.mjs` | `listenerRequired: true` bakes, `vm.exposeTcp()`, `TcpForwarder` |
 | `05-spawn-streaming.mjs` | `vm.spawn()` → `ExecChild` (writeStdin / readStdout / wait) |
+| `06-mount-workspace.mjs` | `mounts` + `symlinks` policy: live host dir into guest, npm-workspace symlink pattern |
 
 ## Requirements
 
@@ -33,7 +34,7 @@ node --input-type=module -e \
   "$(sed 's|@supermachine/core|./index.js|' examples/01-hello.mjs)"
 ```
 
-For a quick smoke test that all five work end-to-end:
+For a quick smoke test that all examples work end-to-end:
 
 ```sh
 for f in examples/*.mjs; do

package/index.d.ts

@@ -39,6 +39,15 @@ export interface MountSpec {
   hostPath: string
   /** virtiofs tag the guest mounts by. Max 35 bytes. */
   guestTag: string
+  /**
+   * Symlink policy: `"deny"` | `"opaque"` | `"follow"`. Default
+   * `"opaque"` — guest may create symlinks (npm/pnpm/yarn rely on
+   * them) but host-side symlinks pointing outside the mount root
+   * are rejected. Use `"deny"` for paranoid mounts (no symlinks or
+   * hard links at all) or `"follow"` for trusted single-tenant
+   * workloads (pre-0.5.5 `allowExternalSymlinks: true` behaviour).
+   */
+  symlinks?: string
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supermachine/core",
-  "version": "0.5.2",
+  "version": "0.5.5",
   "description": "Run any OCI/Docker image as a hardware-isolated microVM. Node/Bun/Deno binding for the supermachine Rust crate.",
   "license": "Apache-2.0",
   "main": "index.js",
@@ -22,7 +22,7 @@
     "arm64"
   ],
   "optionalDependencies": {
-    "@supermachine/core-darwin-arm64": "0.5.2"
+    "@supermachine/core-darwin-arm64": "0.5.5"
   },
   "scripts": {
     "build:rust": "TYPE_DEF_TMP_PATH=$(pwd)/scripts/.napi_type_defs.tmp cargo build --release -p supermachine-napi && cargo build --release --bin supermachine-worker -p supermachine",