capability-stem

Stability: 1 - Experimental

Capability stem enabling capabilities in GET HTTPS requests.

The capability is initially encoded as the fragment in the URI (see: https://tools.ietf.org/html/rfc3986#section-3.5). When the server receives the GET request, it returns JavaScript to the client that reads the fragment from the URI and encodes it as a Bearer token in a POST request (see: https://tools.ietf.org/html/rfc6750).

Contents

• Installation
• Usage
• Tests
• Documentation
  • CapabilityStem

Installation

npm install capability-stem

Usage

To run the below example run:

npm run readme

"use strict";

var crypto = require('crypto');
var fs = require('fs');
var path = require('path');
var StemServer = require('../server.js');

var EXAMPLE_CAPABILITY = crypto.randomBytes(42).toString('base64');

var stemServer = StemServer.listen({
    host: 'localhost',
    port: 4443,
    key: fs.readFileSync(path.normalize(path.join(__dirname, 'readme/server-key.pem'))),
    cert: fs.readFileSync(path.normalize(path.join(__dirname, 'readme/server-cert.pem'))),
    secureProtocol: "TLSv1_method"
});

stemServer.on('listening', function () {
    console.log('server listening on https://localhost:4443');
    console.log('   ...try visiting https://localhost:4443/#' + EXAMPLE_CAPABILITY);
    console.log('   ...then visit just https://localhost:4443 in another tab');
    console.log('');
    console.log('Ctrl+C to exit');
});

stemServer.on('request', function (capability, req, res) {
    // we have a capability string, a request, and a response object

    // for example, we only allow EXAMPLE_CAPABILITY
    if (capability !== EXAMPLE_CAPABILITY) {
        console.log('received invalid request...');
        res.writeHead(401, {'Content-Type': 'text/html'});
        res.write('<h2>401 Unauthorized</h2>');
        res.end();
        return;
    }

    console.log('received valid request...');
    console.log(req.url);
    console.dir(req.headers);
    res.writeHead(200, {'Content-Type': 'text/html'});
    fs.createReadStream(
        path.normalize(path.join(__dirname, 'readme', 'content.html')))
        .pipe(res);
});

Tests

None at this time.

Documentation

• CapabilityStem

CapabilityStem

Public API

• CapabilityStem.listen(config, [callback])
• new CapabilityStem(config)
• capabilityStem.close([callback])
• capabilityStem.listen([callback])
• Event 'request'

CapabilityStem.listen(config, [callback])

• config: See new CapabilityStem(config).
• callback: See capabilityStem.listen([callback]).
• Return: Object An instance of CapabilityStem with server listening for connections.

Creates a new CapabilityStem instance and starts listening for connections.

new CapabilityStem(config)

• config: Object
  • host: String (Default: localhost).
  • port: Integer (Default: 4443) A port value of zero will assign a random port.
  • pfx: See tls.createServer() options.
  • key: See tls.createServer() options.
  • passphrase: See tls.createServer() options.
  • cert: See tls.createServer() options.
  • ca: See tls.createServer() options.
  • crl: See tls.createServer() options.
  • ciphers: See tls.createServer() options.
  • handshakeTimeout: See tls.createServer() options.
  • honorCipherOrder: See tls.createServer() options.
  • requestCert: See tls.createServer() options.
  • rejectUnauthorized: See tls.createServer() options.
  • NPNProtocols: See tls.createServer() options.
  • SNICallback: See tls.createServer() options.
  • sessionIdContext: See tls.createServer() options.
  • secureProtocol: See tls.createServer() options.
  • secureOptions: See tls.createServer() options.

Creates a new CapabilityStem instance.

capabilityStem.close([callback])

• callback: Function (Default: undefined) function () {} Optional callback to call once the server is stopped.

Stops the CapabilityStem server from accepting new connections.

capabilityStem.listen([callback])

• callback: Function (Default: undefined) function () {} Optional callback to call once the server is listening for connections.

After listen() is called, the server will begin accepting new connections.

Event 'request'

• function (capability, request, response) {}
  • capability: String The capability string associated with the request.
  • request: Object An instance of http.IncomingMessage.
  • response: Object An instance of http.ServerResponse.

Emitted when the server receives a request with correctly encoded capability.

WARNING You still need to check that the capability is valid.