Back to top

Wascap Specification - Capability Providers

The Wascap standard for communications between a host and a guest enforces no limits on the list of capability identifiers (IDs) that can be used in the embedded JWT. This means that any host can provide any set of capabilities. It’s the job of the host to enforce the contract such that no capability will be made available to a host that does not have a claim attestation for it.

There are, however, a set of well-known capabilities. These can be used by hosts to provide a set of default/common capabilities typical to a given domain (like cloud native capabilities).

Well-Known Capabilities

These capabilities are considered common enough among cloud usage to be defined within the wascap schema.
These capabilities are also included as first-class signing options in the wascap command line tool.
Capability IDDescription
wascap:messagingMessage broker capability, which includes typical publish and subscribe functionality
wascap:keyvalueKey-Value Store capability
wascap:http_serverCapability to grant guest modules an inbound HTTP endpoint
wascap:http_clientGives the guest module the ability to make outbound HTTP client requests
wascap:blobstoreGives the guest module the ability to work with binary large objects (blobs)

Provider Required FFI Functions

Capability providers are required to expose a plugin constructor via FFI on the assumption that the host will load said provider as a dynamic C library (cdylib)
Required FunctionDescription
__capability_provider_createFFI (Foreign Function Interface), C-standard, unmangled function exposed within the library. This is called by any Wascap-compliant host to initialize a capability provider plugin. These plugins must conform to a specific standard in order to be a legitimate capability provider.

Capability Provider Interface

The following functions must be exposed for calling by the wascap host
Required FunctionDescription
configure_dispatchThis function passes a reference to a dispatcher to the plugin. The dispatcher allows the plugin to communicate with the guest module
capability_idReturns a globally unique string representing the ID of the capability the plugin provides. Should be any of the wascap: prefixed identifiers or a domain specific one. Convention dictates a (provider category):(capability) naming convention, e.g. iot:gpio. The wascap prefixed should only be used for capability IDs that appear in the official well-known list.
nameReturns a human-friendly name for the capability provider. This should also include any specific binding used by the provider. For example, a Redis provider for the wascap:keyvalue capability should include Redis in the name, e.g. “Redis Key-Value Store”
handle_callThe wascap host will invoke this function when the guest module has sent a command targeted at a specific provider’s capability ID. The command will be a protobuf Command as described in the codec section

Capability Provider Trait (Rust)

If you are building your capability plugin in Rust (the preferred method), then this is the trait to which your plugin must conform:

pub trait CapabilityProvider: Any + Send + Sync {
    fn configure_dispatch(
        &self,
        dispatcher: Box<Dispatcher>,
        identity: ModuleIdentity,
    ) -> Result<(), Box<dyn Error>>;
    fn capability_id(&self) -> &'static str;
    fn name(&self) -> &'static str;
    fn handle_call(&self, cmd: &Command) -> Result<Event, Box<dyn Error>>;
}

This trait, as well as all of the core protobuf message definitions, can be found in the wascap-codec crate on crates.io.