txf v5.0.0

txf   

File transfer service which pipes PUT requests to matching GET requests.

• Uses shared secrets to make request paths unguessable.
• Doesn't store data.

The API is described here.

Example

Create a txf service on port 8000:

var server = require('http').createServer();
server.listen(8000);
require('txf')(server, { test: { sender: '', receiver: '' } });

Send data to the service:

$ echo 'some data' | curl -T - http://localhost:8000/test/hello

Receive data from the service:

$ curl http://localhost:8000/test/hello
some data

Note you can also start the receiver first — txf won't start the response to the receiver until the sender connects.

Access Control

Requests to a txf service should use paths of the following form:

/namespace/[hmac-sha256-hex/]resource

The first component in the path we call the txf namespace.

When creating the service, specify secrets for each namespace you want to support; one secret for senders (PUT requests) and one for receivers (GET requests).

If a namespace's secrets are empty strings then no access control is applied. Anyone can PUT or GET files to the namespace. In this case, the second component in the path we call the txf resource.

If the secrets aren't empty strings then they're used to apply access control to the namespace. In this case, the third component of the path must be the resource. The second component must be the hex-encoded HMAC-SHA256 of the resource, calculated using one of the secrets (depending on the request type) as the key.

Here's the same example as above but with access control. First the service:

var server = require('http').createServer();
server.listen(8000);
require('txf')(server, { test: { sender: 'secret1', receiver: 'secret2' } });

Send data to the service:

$ echo 'some data' | curl -T - http://localhost:8000/test/$(echo -n hello | openssl dgst -sha256 -hmac secret1 | awk '{print $2}')/hello

Receive data from the service:

$ curl http://localhost:8000/test/$(echo -n hello | openssl dgst -sha256 -hmac secret2 | awk '{print $2}')/hello
some data

Status Codes

txf can return the following HTTP status codes:

Installation

npm install txf

Licence

MIT

Test

grunt test

Lint

grunt lint

Code Coverage

grunt coverage

c8 results are available here.

Coveralls page is here.

API

Source: index.js

• module.exports

module.exports(server, secrets)

Create a txf service which pipes a PUT request's incoming stream to a GET request's outgoing stream on the same path. Request paths should be of the form /namespace/[hmac-sha256-hex/]resource. If access control is defined for namespace (see the secrets parameter below) then hmac-sha256-hex must be the hex-encoded HMAC-SHA256 of resource. Otherwise hmac-sha256-hex is not required.

Parameters:

• {[object Object] | [object Object]} server HTTP or HTTPS server which txf will use to listen for requests. It's up to the caller to set up the server (e.g. listen on a port). HTTPS servers will need to know about their certificates and keys. See make_server() in test/test.js for an example.
• {Object} secrets A dictionary of valid namespaces. Each entry in secrets should be a mapping from a namespace to a dictionary of HMAC keys, one for PUT requests (senders) and one for GET requests (receivers).

For example:

{ foo: { sender: 'some secret', receiver: 'another secret' } }

would mean PUT requests to the foo namespace for resource bar would have to use the following path:

/foo/c6eb7ab0584d4a8f62d64de6767798e09c9566308533cedb86d14547fcab3211/bar

and GET requests to the foo namespace for resource bar would have to use the following path:

/foo/be83aaf02fb252a1b21f522c95c09f5db563dc6180db034c9c236fb3ffc849ff/bar

If you specify empty strings for a namespace's secrets:

{ foo: { sender: '', receiver: '' } }

then the HMAC-SHA256 is not required. In that case, PUT and GET requests could use the following path:

/foo/bar

Requests to a namespace which don't have an entry in secrets will be rejected.

Go: TOC | module

—generated by apidox—