README
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
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
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
: Objecthost
: 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.