evr-websocket-server - a websocket adapter for everarch

1. Introduction
2. Installation
3. Run
4. Interface

Introduction

evr-websocket-server listens for websocket connections. Each connection can perform a subset of the evr cli commands after authentication.

Installation

$ npm install

Run

evr-websocket-server is configured via a JSON file. The configuration file might look like this:

{ "port": 8030, "user": { "test": { "password": "pazz", "signing-key": "BD1C9FFF…0F3B3", "gpg-keys": [ "BD1C9FFF…0F3B3" ] } } }

signing-key is the GPG key used for signing put claims. The property is optional. If omitted the default GPG key configured for evr cli is used.

gpg-keys contains a list of GPG key fingerprints. The related user should be the only one who can sign claims using these keys.

$ node . evr-websocket-server.conf.json

Interface

evr-websocket-server will listen on the configured port for connections following the WebSocket protocol as defined in RFC 6455. All sent and received messages are expected to be text messages which contain JSON. The client sends commands which are responded by the server. The client must provide a channel identifier with every command. The server responses will use the same channel number so that the response can be related to a command from the client.

The first command must be an authentication command.

{ "ch": 123, "cmd": "auth", "type": "basic", "user": "mr-x", "password": "pazz" }

After the authentication command any of the following commands can follow.

The watch command tells the server to watch for modified blobs.

{ "ch": 123, "cmd": "watch", "lastModifiedAfter": 1684012031, "flags": 1, "filter": { "type": "namespace", "ns": "https://evr.ma300k.de/claims/" } }

The lastModifiedAfter property is optional. The default value is 0. The meaning of lastModifiedAfter is defined by the --last-modified-after argument for the evr cli. See evr --help for more details.

The flags property is optional. The default value is that no flags are used. The meaning of flags is defined by the --flags argument for the evr cli.

The filter property is optional. The default value is no filtering. It specifies filters which are applied to the found blobs before reporting them to the client. Right now only a namespace filter is supported. It filters blobs which do not use the given namespace.

Responses from the server to the watch command might look like this:

{ "ch": 123, "status": "blob-modified", "ref": "sha3-224-…", "lastModified": 1684012032 }

If something goes wrong the server might respond with an error status:

{ "ch": 123, "status": "error", "errorCode": 1 }

The error code 1 is a general no further specified error. Could be anything like someone stumbled over the network cable or your dog ate the homework.

The meaning of the other error codes is defined by the evr cli program. It's exit code is reported as the error code. The most important ones are 2 for 'not found' and 5 for 'user data invalid'. For a complete list look at the source file src/errors.h.

This kind off errors can also be reported for the further commands described below.

The get-claim-set command tells the server to respond a claim set's content.

{ "ch": 123, "cmd": "get-verify", "ref": "sha3-224-…", "meta": true }

The meta property is optional. The default value is false. A value of true indicates that the response should also contain metadata about the fetched blob.

Responses from the server might look like this:

{ "ch": 123, "status": "get", "body": "…", "meta": { "signed-by": "BD1C9FFF…0F3B3", "signed-by-user": "test" } }

The put-claim-set command tells the server to store a provided claim set.

{ "ch": 123, "cmd": "sign-put", "body": "…" }

Responses from the server might look like this:

{ "ch": 123, "status": "put", "ref": "sha3-224-…" }

The list-users command asks the server for a list of user names.

{ "ch": 123, "cmd": "list-users" }

Responses from the server might look like this:

{ "ch": 123, "status": "users", "users": ["bob", "joe"] }