$ cats nobody@supertxt.net:git/wanine.s.txt

# git/wanine

You can learn more about this git repository by cloning it like this:

git clone https://supertxt.net/git/wanine

→ (home) ../../

# Git Tags

--id=v0.0.5 --date=2023-10-21T06:48:19-04:00
--id=v0.0.4 --date=2023-10-20T12:05:03-04:00
--id=v0.0.3 --date=2023-10-20T11:36:21-04:00
--id=v0.0.2 --date=2023-10-20T07:09:58-04:00
--id=v0.0.1 --date=2023-10-19T16:44:12-04:00

# Git Log

--hash=03e7e51 --date=2023-10-21T07:13:10-04:00 "fix the readme"
--hash=d79d623 --date=2023-10-21T06:48:19-04:00 "add a readme with a tour and overview of the waning functionality"
--hash=09c105e --date=2023-10-20T14:25:50-04:00 "run wasm binaries over ssh"
--hash=04d1937 --date=2023-10-20T12:05:03-04:00 "handle the case where the shiny server is started and the program does not use it"
--hash=be67d82 --date=2023-10-20T11:36:21-04:00 "upgrade shiny-wire to v0.0.6 for better close handling"
--hash=8d87f70 --date=2023-10-20T07:09:58-04:00 "start the shiny server on the original goroutine to support window systems where this is a constraint"
--hash=1b7e6b3 --date=2023-10-19T16:44:12-04:00 "Add license file"
--hash=6af8f05 --date=2023-10-19T16:38:22-04:00 "initial version of wanine WebAssembly runtime with 9p features"

# Git Branches

--id=main --hash=03e7e51 --date=2023-10-21T07:13:10-04:00

## WA-nine

WA-nine (WebAssembly 9) is a webassembly runtime based on [:@wazero] that is customized for the SuperTXT stack with a little extra.

note: this is EXPERIMENTAL and not intended for production use as of yet

Feature highlights:

→ (wazero) https://wazero.io/
→ (shiny-wire) https://supertxt.net/git/shiny-wire.html

### Quick start and tour

You can install wanine using the supertxt homebrew for Linux/macOS.

.sh
brew tap supertxt/tap ssh://nobody@supertxt.net/git/st-brew
brew install supertxt/tap/wanine

Now you can run programs, like this version of 'ls', from a remote computer in a sandbox. The WASM runtime protects you from the program by giving it no access to any information or services from your local computer.

.sh
wanine run supertxt.net:bin/ls --help

All this program gets from wanine is access to stdin, stdout, and stderr so that it can print things out, and perhaps accept keyboard input from you. With sufficient trust in supertxt.net and its ls program, you can give it access to one of your directories, "/tmp/seeonlythis/" visible to it as "/tmp." We are accepting that the ls command might read/write/delete anything in this directory.

.sh
mkdir /tmp/seeonlythis
echo "hello world" > /tmp/seeonlythis/hello.txt
wanine run --mount=/tmp/seeonlythis:/tmp supertxt.net:bin/ls -l /tmp

The output might look something like this:

.txt
total 0
-rw------- 1 unknown unknown 12 Oct 21 10:06 hello.txt

Maybe we trust it a little more, and are willing to give it read-only access to somplace a little more critical. Here's a log directory from a server where we don't want 'ls' to be able to write to the log, just give us the date it was last modified. Besides, even if it could read the secret information from log there's no way it can send that data anywhere since the sandbox excludes network access from the start. Nobody except for us can hear the scream.

.sh
wanine run --mount=/var/log/myserver:/var/log:ro supertxt.net:bin/ls -l /var/log

The "ls" command sees the directory as "/var/log" so that's the directory it's given. Also, notice that the mount option ends with the ":ro" suffix, which instructs wanine to provide read-only access, with no possibility of create/modify of the files there.

.txt
total 0
-rw------- 1 unknown unknown 48540935 Oct 21 10:16 daemon.log

You can compile and run your own WASM programs in a variety of programming languages. Wanine supports the WASI "preview 1" flavour, which is also what the Go programming language toolchain can produce. There are many other languages and toolchains that can compile WASI programs as well.

→ https://go.dev/blog/wasi

### Shiny GUIs

There is also an experimental support for GUI programs using the [:@shiny-wire] protocol. You can grant a program that can support a GUI in this way with a special "--shiny" switch.

.sh
wanine run supertxt.net:bin/draw-9p

This program will likely fail with an error message like the following showing that it was trying to access the "/dev/shiny" device that doesn't exist.

.txt
panic: open /dev/shiny: Bad file number

goroutine 1 [running]:
main.main()
	/home/supertxt/git/shiny-wire/cmd/draw-9p/main.go:11 +0x7

If we trust it enough to give it access to our GUI then we add the "--shiny" switch. It doesn't get access to anything else, none of our local data, filesystem, network, or even a clipboard.

.sh
wanine run --shiny supertxt.net:bin/draw-9p

### 9P mounts

9P is the protocol that powers the [:@plan 9] operating system, and lives on through various ports of its functionality including [:@plan 9 from user space], UTF-8 (where it was first invented), and much more.

→ (plan 9) http://9p.io/plan9/
→ (plan 9 from user space) https://9fans.github.io/plan9port/

Wanine has built-in support for the 9P protocol so that you can mount a variety of different servers into the namespace of the WASM program so that they appear as normal files to it. Here's an example where the contents of a zip file can be given to the ls command. For this example to work you need to have zipfs installed from [:@plan 9 from user space]. Any other kind of 9P server will work the same way.

.sh
zipfs -s cmusic ~/Downloads/ChristmasMusic.zip ## Start the zipfs file server named cmusic serving the zip file
wanine run --mount=/tmp/ns.supertxt.\:0/cmusic:/zip supertxt.net:bin/ls -l /zip

The example above will list the files in the zip along with their filestamps, sizes, etc.

If the mount points to a file, not a directory, then wanine will attempt to mount that name unix pipe, "/tmp/ns.supertxt.net.:0" in this case, created by zipfs. Just like directory mounts, the colon separates the path of the mount on the host from the path on the guest.

There are many other interesting and useful 9P file servers out there. Another notable example is the acme editor, that provides a file server for accessing and mutating its internal state. This works as an interface for plugging in customizations.