Update Wasmtime's WASI documentation. (#9471)

* Update Wasmtime's WASI documentation.

Replace most of Wasmtime's original WASI documentation with links to
other resources that are now available.

This documentation was written when WASI was first released, and while
many of the big ideas are still present in WASI, many of the details have
changed. For example, [Jco] is now a much better way to run WASI programs
in Browsers than the original Web polyfill, and WASI is now goverened by
the WASI Subgroup rather than by Wasmtime itself, and so on.

[Jco]: https://github.com/bytecodealliance/jco

Fixes #9107.

* Fix documentation link.

* Fix another doc link.

docs/WASI-capabilities.md

@@ -1,81 +1,6 @@
 # Additional background on Capabilities
 
-## Unforgeable references
+For more information about capabilities in WASI, see the WASI Subgroup's
+[capabilities documentation].
 
-One of the key words that describes capabilities is *unforgeable*.
-
-A pointer in C is forgeable, because untrusted code could cast an integer
-to a pointer, thus *forging* access to whatever that pointer value points
-to.
-
-MVP WebAssembly doesn't have unforgeable references, but what we can do instead
-is just use integer values which are indices into a table that's held outside
-the reach of untrusted code. The indices themselves are forgeable, but
-ultimately the table is the thing which holds the actual capabilities, and
-its elements are unforgeable. There's no way to gain access to a new resource
-by making up a new index.
-
-When the reference-types proposal lands, references will be unforgeable, and
-will likely subsume the current integer-based APIs, at the WASI API layer.
-
-## Static vs dynamic capabilities
-
-There are two levels of capabilities that we can describe: static and dynamic.
-
-The static capabilities of a wasm module are its imports. These essentially
-declare the set of "rights" the module itself will be able to request.
-An important caveat though is that this doesn't consider capabilities which
-may be passed into an instance at runtime.
-
-The dynamic capabilities of a wasm module are a set of boolean values
-associated with a file descriptor, indicating individual "rights". This
-includes things like the right to read, or to write, using a given file
-descriptor.
-
-## Filesystem rules
-
-It happens that integer indices representing capabilities is same thing that
-POSIX does, except that POSIX calls these indices *file descriptors*.
-
-One difference though is that POSIX normally allows processes to request
-a file descriptor for any file in the entire filesystem hierarchy, which is
-granted based on whatever security policies are in place. This doesn't
-violate the capability model, but it doesn't take full advantage of it.
-
-CloudABI, Fuchsia, and other capability-oriented systems prefer to take
-advantage of the hierarchical nature of the filesystem and require untrusted
-code to have a capability for a directory in order to access things inside
-that directory.
-
-This way, you can launch untrusted code, and at runtime give it access to
-specific directories, without having to set permissions in the filesystem or
-in per-application or per-user configuration settings.
-
-See [this tutorial](WASI-tutorial.md) for an example of how this can look
-in practice.
-
-## Berkeley socket rules
-
-Sockets aren't naturally hierarchical though, so we'll need to decide what
-capabilities look like. This is an area that isn't yet implemented.
-
-In CloudABI, users launch programs with the sockets they need already
-created. That's potentially a starting point, which might be enough for
-simple cases.
-
-We also anticipate an eventual extension to that, where we create a capability
-that represents a set of possible sockets that can be created. A set
-might be described by ranges of permitted ports, ranges of permitted
-addresses, or sets of permitted protocols. In this case the actual socket
-wouldn't be created until the application actually requests it.
-
-## Other info
-
-CloudABI's intro to capability-based OS security provides additional background info:
-
-https://github.com/NuxiNL/cloudabi#capability-based-security
-
-
-The Fuchsia project has a blog post on the topic of capability-based OS security:
-
-https://fuchsia.dev/fuchsia-src/concepts/filesystems/dotdot
+[capabilities documentation]: https://github.com/WebAssembly/WASI/blob/main/docs/Capabilities.md

docs/WASI-documents.md

@@ -1,28 +1,5 @@
 # WASI Document Guide
 
-To get started using WASI, see [the intro document](WASI-intro.md) and
-[the tutorial](WASI-tutorial.md).
+For documentation about WASI, see the [Resources page on wasi.dev].
 
-For more detail on what WASI is, see [the overview](WASI-overview.md).
-
-For specifics on the API, see the [API documentation](https://github.com/WebAssembly/WASI/blob/main/legacy/preview1/docs.md).
-Additionally, a C header file describing the WASI API is
-[here](https://github.com/WebAssembly/wasi-libc/blob/master/libc-bottom-half/headers/public/wasi/api.h).
-
-The WASI C/C++ SDK repository is [wasi-sdk](https://github.com/WebAssembly/wasi-sdk/).
-
-The WASI libc repository, used by wasi-sdk, is [wasi-libc](https://github.com/WebAssembly/wasi-libc/).
-
-For some discussion of capability-based design, see the [Capabilities document](WASI-capabilities.md).
-
-For some discussion of WASI's design inspiration, see the [Background document](WASI-background.md).
-
-For background on some of the design decisions in WASI, see [the rationale](WASI-rationale.md).
-
-For documentation of the exports required of programs using, see
-[the application ABI](https://github.com/WebAssembly/WASI/blob/main/legacy/application-abi.md).
-
-For some ideas of things that we may want to change about WASI in the
-short term, see the [possible changes](WASI-some-possible-changes.md) document.
-For longer-term ideas, see the [possible future features](WASI-possible-future-features.md)
-document.
+[Resources page on wasi.dev]: https://wasi.dev/resources

docs/WASI-intro.md

@@ -1,60 +1,9 @@
 # Welcome to WASI!
 
-WASI stands for WebAssembly System Interface. It's an API designed by
-the [Wasmtime] project that provides access to several operating-system-like
-features, including files and filesystems, Berkeley sockets, clocks, and
-random numbers, that we'll be proposing for standardization.
+WebAssembly System Interface, or WASI, is a family of APIs being designed
+by the [WASI Subgroup] of the Wasm Community Group of the W3C.
 
-It's designed to be independent of browsers, so it doesn't depend on
-Web APIs or JS, and isn't limited by the need to be compatible with JS.
-And it has integrated capability-based security, so it extends
-WebAssembly's characteristic sandboxing to include I/O.
+To learn more about WASI, see [wasi.dev].
 
-See the [WASI Overview](WASI-overview.md) for more detailed background
-information, and the [WASI Tutorial](WASI-tutorial.md) for a walkthrough
-showing how various pieces fit together.
-
-Note that everything here is a prototype, and while a lot of stuff works,
-there are numerous missing features and some rough edges. For example,
-networking support is incomplete.
-
-## How can I write programs that use WASI?
-
-The two toolchains that currently work well are the Rust toolchain and
-a specially packaged C and C++ toolchain. Of course, we hope other
-toolchains will be able to implement WASI as well!
-
-### Rust
-
-To install a WASI-enabled Rust toolchain, see the [online section of the
-guide](https://bytecodealliance.github.io/wasmtime/examples-rust-embed.html)
-
-### C/C++
-
-To install a WASI-enabled C/C++ toolchain, see the [online section of the
-guide](https://bytecodealliance.github.io/wasmtime/lang-c.html)
-
-## How can I run programs that use WASI?
-
-Currently the options are [Wasmtime] and the [browser polyfill], though we
-intend WASI to be implementable in many wasm VMs.
-
-[Wasmtime]: https://github.com/bytecodealliance/wasmtime
-[browser polyfill]: https://github.com/bjorn3/browser_wasi_shim
-
-### Wasmtime
-
-[Wasmtime] is a non-Web WebAssembly engine which is part of the
-[Bytecode Alliance project](https://bytecodealliance.org). To build
-it, download the code and build with `cargo build --release`. It can
-run WASI-using wasm programs by simply running `wasmtime foo.wasm`,
-or `cargo run --bin wasmtime foo.wasm`.
-
-### The browser polyfill
-
-The source is [here](https://github.com/bjorn3/browser_wasi_shim).
-
-## Where can I learn more?
-
-Beyond the [WASI Overview](WASI-overview.md), take a look at the
-various [WASI documents](WASI-documents.md).
+[WASI Subgroup]: https://github.com/WebAssembly/wasi
+[wasi.dev]: https://wasi.dev/