arm64js 0.8.0 → 0.9.0

package/README.md

@@ -30,7 +30,7 @@ const { output, exitCode } = await vm.exec('apk add --no-cache curl');
 
 It returns raw `output` and `exitCode` so that you can verify the result.
 
-The VM _does not_ have access to the Internet except for the apk registry. To give it your own data, you can use one of the two options:
+The VM _does not_ have access to the Internet except for the apk registry, unless you run an internet gateway for it (see [Networking](#networking)). To give it your own data, you can use one of the two options:
 
 - `vm.writeFile`: copies the specified file into the VM. Changing or deleting the file happens only inside the VM. The file is saved and loaded with the snapshot. Uses VM memory to copy the file, thus is intended mainly for smaller (up to 100 MiB) files.
 - `vm.mount`: read-only, direct mount of the data blob. Doesn't use any VM memory. Not stored in the snapshot. To unmount use `vm.unmount()`.
@@ -114,7 +114,7 @@ npm install arm64js
 
 ## API
 
-### `Arm64JS.boot(image | snapshotId, { vcpus?, onProgress? })` → `Vm`
+### `Arm64JS.boot(image | snapshotId, { vcpus?, gateway?, onProgress? })` → `Vm`
 
 A VM can be created either from a base image or your own local snapshot.
 
@@ -123,6 +123,8 @@ A VM can be created either from a base image or your own local snapshot.
 
 Additionally, you can specify an `onProgress` callback to track VM loading phases and the number of virtual CPUs the VM will have (more is not always better).
 
+`gateway: { url, token? }` sends the VM's internet traffic through a gateway you run, see [Internet gateway](#internet-gateway).
+
 onProgress gets one argument, a BootProgress object:
 
 ```ts
@@ -390,10 +392,36 @@ It shows the VM console, sends what is typed to the VM, and sizes itself to the
 
 ## Networking
 
-The VM has an emulated network card, DNS, and can install Alpine packages with `apk` through the CDN's package mirror. It has no general internet access.
+The VM has an emulated network card, DNS, and can install Alpine packages with `apk` through the CDN's package mirror. It has no general internet access unless you give it a gateway.
 
 The name `host.internal` is the page itself: see `vm.listen` and `vm.serveHttp`.
 
+### Internet gateway
+
+A browser cannot open TCP connections, so a VM reaches the internet through a gateway: a small program that takes the VM's connections over a WebSocket and opens them from the machine it runs on. Download `arm64js-gateway` for Linux or macOS from [arm64js.com](https://arm64js.com/#internet-gateway), start it, and pass its address when booting:
+
+```sh
+./arm64js-gateway --ws 127.0.0.1:4434
+```
+
+```js
+const vm = await Arm64JS.boot('alpine', { gateway: { url: 'ws://127.0.0.1:4434' } });
+await vm.exec('wget -qO- https://example.com');
+```
+
+By default the gateway relays every connection from any page that reaches it, to any address, including the machine it runs on and its local network. To narrow that down:
+
+- `--allow-host registry.npmjs.org` (repeatable, `*.npmjs.org` for a whole domain) relays only TCP connections to those names. A name that resolves to a private or local address is still refused; give the IP itself to allow an address. UDP and ping are then not relayed. Names that share an address with an allowed name on a large CDN can still be reached, because the gateway sees addresses, not the site inside the encrypted connection.
+- `--allow-origin https://app.example.com` (repeatable) serves only web pages from that origin. It does not stop other programs, which can send any origin, so a gateway other machines can reach needs `--token`. In frame mode the VM runs in the CDN's frame, so the origin the gateway sees is `https://cdn.arm64js.com`: use `--token` instead.
+- `--token <secret>` serves only clients that pass the same `token` in the boot option: `{ gateway: { url, token } }`. Anyone who can read your page can read the token too. A client the gateway refuses gets no connection at all, so the VM boots without internet access.
+
+Things to know:
+
+- Chrome asks the user to allow access to apps on their device the first time a page on another site connects to a gateway on `127.0.0.1`. A page served from `localhost` is not asked.
+- A gateway on another machine needs `wss://`: browsers block a plain `ws://` connection from an `https` page to anything but the local machine. Put it behind a TLS proxy such as Caddy.
+- DNS does not go through the gateway: it is resolved over HTTPS by the browser (Cloudflare's resolver). `apk` packages come from the CDN's mirror and use the gateway only when that download fails.
+- Needs engine 0.9 or newer. A snapshot saved on an older engine resumes on that engine, and booting it with `gateway` fails with `engine-mismatch` rather than starting a VM without internet access.
+
 ## Development
 
 ```sh

package/dist/frame-host.js

@@ -27,6 +27,12 @@ export async function mountFrameHost(url, deps = {}) {
     iframe.src = url;
     iframe.setAttribute('title', 'arm64js');
     iframe.setAttribute('aria-hidden', 'true');
+    // The VM's network worker runs in this frame. To reach a gateway on the user's
+    // own machine (`gateway: { url: 'ws://127.0.0.1:…' }`) Chrome asks the user for
+    // local network access, and a cross-origin frame may only ask when the page
+    // delegates it. All three names are Chrome's (it split the permission in 145);
+    // a browser that knows none of them ignores the attribute.
+    iframe.setAttribute('allow', 'local-network-access; local-network; loopback-network');
     // In the layout and on screen, never display:none: a hidden frame's timers are
     // throttled by the browser. The VM steps in workers, but the frame's main
     // thread still relays.

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export { VERSION as version } from './version.js';
 export { Connection, type ConnectionData } from './connection.js';
 export type { HttpHandler } from './http.js';
 export { DEFAULT_MAX_BODY_BYTES, Vm, type FileData, type Listener, type Mount, type ServeHttpOptions } from './vm.js';
-export type { Arm64JSErrorCode, BootOptions, BootProgress, ExecOptions, ExecResult, OutputInfo, ReadFileOptions, SnapshotInfo, SnapshotOptions, StorageStatus, VmExit, WriteFileOptions, } from '@arm64js/protocol';
+export type { Arm64JSErrorCode, BootOptions, BootProgress, ExecOptions, ExecResult, GatewayOptions, OutputInfo, ReadFileOptions, SnapshotInfo, SnapshotOptions, StorageStatus, VmExit, WriteFileOptions, } from '@arm64js/protocol';
 export { Arm64JSError, HOST_INTERNAL_NAME } from '@arm64js/protocol';
 export declare const Arm64JS: Arm64JSApi;
 export default Arm64JS;

package/dist/loader.d.ts

@@ -4,6 +4,13 @@ export declare function packageEngine(): string;
 export declare function engineParts(tag: string): [number, number] | null;
 /** Whether engine `a` is newer than engine `b`. False unless both are exact tags. */
 export declare function isNewerEngine(a: string, b: string): boolean;
+/** The first engine whose runtime understands `BootOptions.gateway`. */
+export declare const GATEWAY_MIN_ENGINE = "0.9";
+/**
+ * Whether `engine` is known to predate `gateway`. Only an exact tag can say so;
+ * a development build (`'dev'`) is assumed current.
+ */
+export declare function predatesGateway(engine: string): boolean;
 /** The immutable runtime directory for an exact `X.Y`, with its trailing slash. */
 export declare function runtimeDir(version: string): string;
 export declare function runtimeModuleUrl(version: string): string;

package/dist/loader.js

@@ -24,6 +24,15 @@ export function isNewerEngine(a, b) {
     }
     return x[0] !== y[0] ? x[0] > y[0] : x[1] > y[1];
 }
+/** The first engine whose runtime understands `BootOptions.gateway`. */
+export const GATEWAY_MIN_ENGINE = '0.9';
+/**
+ * Whether `engine` is known to predate `gateway`. Only an exact tag can say so;
+ * a development build (`'dev'`) is assumed current.
+ */
+export function predatesGateway(engine) {
+    return engineParts(engine) !== null && isNewerEngine(GATEWAY_MIN_ENGINE, engine);
+}
 /** The immutable runtime directory for an exact `X.Y`, with its trailing slash. */
 export function runtimeDir(version) {
     return `${CDN_BASE}/sdk-v${version}/`;

package/dist/runtime.js

@@ -1,7 +1,7 @@
 import { Arm64JSError } from '@arm64js/protocol';
 import { withSdkErrors } from './errors.js';
 import { loadHost } from './hosts.js';
-import { engineParts, isNewerEngine, packageEngine } from './loader.js';
+import { engineParts, GATEWAY_MIN_ENGINE, isNewerEngine, packageEngine, predatesGateway } from './loader.js';
 import { Vm } from './vm.js';
 /**
  * The runtimes for this page: its own engine, loaded on the first call, and
@@ -71,6 +71,12 @@ export class Runtime {
         }
     }
     async bootOn(loaded, id, opts) {
+        // An older runtime drops the option it does not know, and the VM would boot
+        // with no internet and no error. A snapshot saved on an older engine resumes
+        // on that engine, so this can happen with a current SDK too.
+        if (opts?.gateway !== undefined && predatesGateway(loaded.engine)) {
+            throw new Arm64JSError('engine-mismatch', `the gateway option needs engine ${GATEWAY_MIN_ENGINE} or newer; this VM runs on ${loaded.engine}`);
+        }
         const { vmId } = await withSdkErrors(loaded.host.boot(id, opts));
         const vm = new Vm(vmId, loaded.host, loaded.engine, (v) => this.vms.delete(v));
         this.vms.add(vm);

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.8.0";
+export declare const VERSION = "0.9.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 // Generated by scripts/stamp-version.mjs from package.json. Do not edit.
-export const VERSION = "0.8.0";
+export const VERSION = "0.9.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arm64js",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Run a Linux VM inside your web page. Boots Alpine from the arm64js CDN, runs commands, keeps snapshots in the browser.",
   "type": "module",
   "license": "MIT",
@@ -34,7 +34,7 @@
     "prepare": "npm run stamp && npm run build:protocol && husky"
   },
   "dependencies": {
-    "@arm64js/protocol": "^1.2.0"
+    "@arm64js/protocol": "^1.3.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",