Back to top

Publishing to the Wapm Registry

Learn How to Publish a Signed Module to the Wapm Registry

In this tutorial, you’ll be creating a new module that echoes the details of an incoming HTTP request back as an HTTP response. Not only is this a helpful diagnostic tool, but we’ll show you how to sign this module and then publish it to wapm.io.

What You’ll Need to Start

You’ll need to have a few things ready before you can do this tutorial:

  • waxosuit - you will need to either have compiled this binary and the default capability provider plugins, or you’ll need to run the docker image.
  • nkeys - you will need the nkeys tool installed (cargo install nkeys --features "cli"). This is used to create ed25519 signing keys.
  • wascap - you will need the wascap tool installed (cargo install wascap --features "cli"). This is used to sign and verify WebAssembly modules.
  • wapm - you will need to have installed the wapm CLI (required to publish to the registry)

Creating a New Module

The instructions here should be familiar if you’ve already gone through any of the basic tutorials. The first step is to generate your new module:

$ cargo generate --git https://github.com/waxosuit/waxosuit-guest-template

Choose a suitable name for this project. We selected EchoExample, which placed the code in the echo-example directory.

Next, add the serde dependency to your Cargo.toml file:

[package]
name = "echo-example"
version = "0.1.0"
authors = ["kevin"]
edition = "2018"

[lib]
crate-type = ["cdylib"]

[dependencies]
wascap-guest = "0.0.3"
serde = { version = "1.0.91", features = ["derive"]}

[profile.release]
# Optimize for small code size
opt-level = "s"

Now you can add the simple code that echoes HTTP request details as a JSON response to your src/lib.rs file:

Sign the Wasm Module

Make sure your module compiles (you should be able to simply cargo build and produce a wasm32-unknown-unknown target).

Next, use the wascap tool and some keys you may have generated in the previous tutorial(s) to sign the module (or you can use nk to create more keys):

$ wascap sign target/wasm32-unknown-unknown/debug/hello_example.wasm -k -s -g -a /path/to/account.nk -m /path/to/module.nk
Successfully signed ./hello_example.wasm.

Make sure you replace the placeholders with the actual paths to your keys and Wasm file.

We can verify that the module is signed and ready to run in waxosuit:

$ wascap caps ../echo-example-wapm/echo-example.wasm
╔════════════════════════════════════════════════════════════════════════════╗
║                                WASCAP Module                               ║
╠═══════════════╦════════════════════════════════════════════════════════════╣
║ Account       ║   ABHUOCYPSFAYVQXEVMOSGQKABFF4LUS35EFE3VCEG3BIEJBGI5GUOCUN ║
╠═══════════════╬════════════════════════════════════════════════════════════╣
║ Module        ║   MBY3SLBLMVLQY7KBULCUK3L2GVPPFY5AIWF3P5UBM2OON6NE3HW4JKRJ ║
╠═══════════════╬════════════════════════════════════════════════════════════╣
║ Expires       ║                                                      never ║
╠═══════════════╬════════════════════════════════════════════════════════════╣
║ Can Be Used   ║                                                immediately ║
╠═══════════════╩════════════════════════════════════════════════════════════╣
║                                Capabilities                                ║
╠════════════════════════════════════════════════════════════════════════════╣
║ K/V Store                                                                  ║
║ Messaging                                                                  ║
║ HTTP Server                                                                ║
╠════════════════════════════════════════════════════════════════════════════╣
║                                    Tags                                    ║
╠════════════════════════════════════════════════════════════════════════════╣
║ None                                                                       ║
╚════════════════════════════════════════════════════════════════════════════╝

Publishing the Module to the Wapm Registry

Now that we’ve got a compiled, signed WebAssembly module that we know conforms to wascap and runs within waxosuit, let’s publish it to wapm.io. The first thing we’ll need in order to publish it is a wapm module manifest. This is a simple toml file that describes our module. The one I used for the published echo example looks like this:

You’ll want to change the values for these properties and make sure that that the source property points to the Wasm module you created in the first step. To double-check and make sure everything works the way it should, you can do a dry-run:

$ wapm publish --dry-run
Successfully published package `autodidaddict/echo-example@0.0.3`
[INFO] Publish succeeded, but package was not published because it was run in dry-run mode

And when you’re ready to do the final publication, you can just execute wapm publish.

When Should I Publish To Wapm?

Wapm is a public registry, so at the very least you’ll want to be working on something you intend to distribute to the general public to use Wapm. The combination of Wapm and Waxosuit gives you the best of both worlds–you get public distribution of your module, and your module also remains signed and tamper-proof, allowing consumers of your module to make smart (possibly OPA-powered) decisions about whether the module should run or if its capability attestations should be honored.

If you wanted to make an application out of one or more WebAssembly modules that run within Waxosuit, you could use wapm.io as your distribution vehicle without sacrificing the security and provenance verification you get with Wascap.