From 5c82dd84b44ea23f74d5699c1a9759ae1d0f654c Mon Sep 17 00:00:00 2001 From: Andrei Ciortea Date: Fri, 22 Oct 2021 12:39:50 +0200 Subject: [PATCH] Add instructions for setting up a local WebSub hub and MQTT broker --- tapas-auction-house/BROKERS.md | 121 +++++++++++++++++++++++++++++++++ 1 file changed, 121 insertions(+) create mode 100644 tapas-auction-house/BROKERS.md diff --git a/tapas-auction-house/BROKERS.md b/tapas-auction-house/BROKERS.md new file mode 100644 index 0000000..7e0d37a --- /dev/null +++ b/tapas-auction-house/BROKERS.md @@ -0,0 +1,121 @@ +# Event-based Interaction with W3C WebSub and MQTT + +## Setting up a local WebSub Hub + +W3C WebSub Recommendation: [https://www.w3.org/TR/websub/](https://www.w3.org/TR/websub/) + +There are several implementations of W3C WebSub available. One implementation that is easy to set up is: +[https://github.com/hemerajs/websub-hub](https://github.com/hemerajs/websub-hub) + +Running this WebSub Hub implementation requires Docker, Node.js, and npm: +* installation instructions for Docker: [https://docs.docker.com/get-docker/](https://docs.docker.com/get-docker/) +* installation instructions for Node.js and npm: [https://docs.npmjs.com/downloading-and-installing-node-js-and-npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) + +### How to run + +```shell +git clone https://github.com/hemerajs/websub-hub.git +cd websub-hub +docker run -d -p 27017:27017 -p 28017:28017 -e AUTH=no tutum/mongodb +npm i -g websub-hub-cli +websub-hub -l info -m mongodb://localhost:27017/hub +``` + +The third command launches a Docker container with a [MongoDB](https://www.mongodb.com/) instance, +which is used to persist all subscriptions made with the hub. See the README of the original project +for further details: [https://github.com/hemerajs/websub-hub](https://github.com/hemerajs/websub-hub) + +### Implementation note on verification of intents + +There are 3 main W3C WebSub hub implementations out of which: +* 2 are public but closed-source: [Google' WebHub hub](http://pubsubhubbub.appspot.com/) +and [Superfeedr's WebSub hub](https://websub.superfeedr.com/) +* 1 is public and open-source, but it requires additional overhead to set up for local development: + [Switchboard](https://switchboard.p3k.io/) + +The project we recommend above provides by far one of the easiest ways to run a W3C WebSub Hub locally. However, +**interoperability is hard**: this project diverges in one significant way from the [W3C WebSub Recommendation](https://www.w3.org/TR/websub/) +and the main [WebSub Hub](http://pubsubhubbub.appspot.com/) implementations. To save you from the +interoperability headaches, we document this divergence below. + +#### Verifying subscriber intents + +When a Subscriber registers with a WebSub Hub, the Hub is required to verify the intent of the subscriber +in order to prevent an attacker from creating unwanted subscriptions. + +To verify the Subscriber's intent, the Hub sends an HTTP GET request to the subscriber's callback +URL. The HTTP GET request includes several parameters, one of which is a hub-generated random string +with the name `hub.challenge`. To confirm the subscription, a Susbcriber must then respond with an +HTTP 2xx status code and a response body equal to the `hub.challenge` parameter. For more details on +the verification of intents, see [Section 5.3 in the W3C WebSub Recommendation](https://www.w3.org/TR/websub/#hub-verifies-intent). + +#### Verifying subscriber intents with the Hemerajs implementation + +The above Hemerajs implementation differs from the W3C WebSub Recommendation in that the Hub expects the +response body confirming the intent to be in the JSON format with the `application/json` media type. + +Sample HTTP request and the HTTP response expected by the Hemerajs WeSub Hub: + +```shell +curl -i --location --request GET 'localhost:8084/websub/?hub.mode=subscribe&hub.topic=http://example.org&hub.challenge=hub-generated-challenge' + +HTTP/1.1 200 +Content-Type: application/json +Content-Length: 46 +Date: Fri, 22 Oct 2021 10:14:03 GMT + +{ + "hub.challenge": "hub-generated-challenge" +} +``` + +#### Verifying subscriber intents in a standard W3C WebSub implementation + +In contrast to the Hemerajs implementation, a standard WebSub Hub implementation would require the reponse body to be exactly equal to the +hub-generated challenge parameter. Here is an example of a standard response, as expected by WebSub Hubs +that are fully standard-compliant: + +```shell +curl -i --location --request GET 'https://websub.flus.io/dummy-subscriber?hub.mode=subscribe&hub.topic=http://example.org&hub.challenge=hub-generated-challenge' + +HTTP/2 200 +server: nginx +date: Fri, 22 Oct 2021 10:15:58 GMT +content-type: text/plain;charset=UTF-8 +content-security-policy: default-src 'self' +strict-transport-security: max-age=63072000 + +hub-generated-challenge +``` + +#### What this means for your TAPAS application + +We recommend using the Hemerajs WebSub Hub implementation for local development. + +In our deployment, however, we will use one of the publicly available W3C WebSub hubs. You will then +have to change the response for intent verification to match the standard response: that is, to return +directly the `hub.challenge` parameter as shown above. + + +## Setting up a local MQTT broker + +An easy way to set up a local MQTT broker is with HiveMQ and Docker: +[https://www.hivemq.com/downloads/docker/](https://www.hivemq.com/downloads/docker/) + +```shell +docker run -p 8080:8080 -p 1883:1883 hivemq/hivemq4 +``` + +The above command launches a Docker container with a HiveMQT broker and binds to the container on 2 ports: +* port `1883` is used by the MQTT protocol +* port `8080` is used for the HiveMQ dashboard; point your browser to: [http://localhost:8080/](http://localhost:8080/) + +To bind the Docker container to a different HTTP port, you can configure the first parameter. E.g., +this command binds the HiveMQT dashboard to port `8085`: + +```shell +docker run -p 8085:8080 -p 1883:1883 hivemq/hivemq4 +``` + +For development and debugging, it might help to install an MQTT client as well. HiveMQ provides an MQTT +Command-Line Interface (CLI) that may help: [https://hivemq.github.io/mqtt-cli/](https://hivemq.github.io/mqtt-cli/)