This is a library to include in your node.js app which will accept requests from an Unlock enabled frontend, and communicate with the Unlock servers to get you up and running with simple, socket-based, passwordless authentication.

If you haven't set up your frontend yet, check out the website for how to do that.

Install via npm:

npm install --save unlock-node

then just require it in your app:

const unlock=require('unlock-node');

The library exports several functions and objects for you to use. In its most basic form, you need only initialize the library with appropriate data and specify how it should behave when it receives a response from the Unlock servers.

const server=http.createServer();
unlock.init({
    server: server,
    apiKey: 'apikey123',
    version: 1,
    onResponse: function(socket, data){
        console.log(data);
        socket.send(JSON.stringify(data));
    }
});
server.listen(3000);

You can look in the example folder to see a simple express app that uses Unlock

Initializes the library with the given options. This will start a WebSocket server to listen for Unlock requests, as well as ping open connections every 30 seconds to ensure they stay open.

The behaviour can be set as follows:

Express compatible middleware which verifies authenticated requests based on a JWT.

const http=require('http');
const express=require('express');
const unlock=require('unlock');

const app=express();
app.use(unlock.verifyRequest);
const server=http.createServer(app);
unlock.init({...});
server.listen(3000);

The JWT can be passed several ways:

1. Through a query string: example.com/account?authToken=123
2. As an x-access-token header:

request
    .get('example.com/account')
    .set('x-access-token', '123')

3. In a cookie specified by cookieName
4. As a body parameter:

request
    .post('example.com/api/list')
    .send({authToken: '123'})

Unlock will set local variables for you to determine whether or not a request was authorized. If a request comes in with a valid JWT, the following variables will be made available:

res.locals.authenticated=true;
res.locals.decoded=tokenData;

tokenData will be the decoded data signed in the JWT. This will contain information about the user who made the request, as well as any payload data you specified using makePayload().

Invalid or no JWT will result in:

res.locals.authenticated=false;

If you're not using express, or you'd prefer not to use the middleware, this function attempts to decode a JWT. If the token is valid, this will return an object containing the data signed in the JWT, otherwise it will return null.

Sends a request to Unlock to delete a user's account from your site. This does not delete the user's data from Unlock, it just removes them from your site's list of registered users. If they would like to continue using your site in the future, they will simply have to register through Unlock again.

This can be called using either callback or Promise mode. If callback is supplied and is a function, it will be called after the successful deletion of the user. Otherwise, leave callback undefined to use it as a Promise. The result of the operation will be the updated user object after deletion, which will can be accessed in the callback or the promise chain.

// Callback mode
unlock.deleteUser('[email protected]', function(res){
    console.log(res);
});

// Promise mode
unlock.deleteUser('[email protected]')
    .then(function(response){
        console.log(response);
    });

This is an object listing the types of possible responses you can expect from the Unlock servers.

const responses={
    UNLOCKED: 'unlocked',
    NOT_UNLOCKED: 'notUnlocked',
    ERROR: 'error'
};

This is an object listing the possible error codes you can receive describing why a request was not unlocked.

const errorCodes={
    INTERNAL_ERROR: 0,
    USER_NOT_FOUND: 1,
    APP_NOT_FOUND: 2,
    APP_DISABLED: 3,
    NOT_VERIFIED: 4,
    TOO_SOON: 5,
    ACTIVE_REQUEST: 6,
    USER_DECLINED: 7,
    NO_RESPONSE: 8,
    USERS_EXCEEDED: 9,
    REQUESTS_EXCEEDED: 10,
    INVALID_TOKEN: 11,
    MISSING_FIELD: 12
};

MIT

Copyright (c) 2019 Shane Brass