@trigo/hapi-auth-signedlink

Hapi plugin to authenticate with signed links

About

This plugin provides the ability to use cryptographic signed links as authentication strategy in Hapi. With this strategy enable on a route arequest with an ?auth=<signature> query parameter containing a valid signature value of the link is considered an authenticaed request.

When the url contains an expires_at=<millis since 1.1.1970> authentication fails when the links has expired.

Any link manipulation causes the signature to become invalid and hapi would by default return a 401 Unauthorized response. This behaviour can be overrwriten with the failAction option.

Compatiblity

hapi <= 17.0.0 => hapi-auth-signed-link <= 1.0.0 hapi >= 17.0.0 => hapi-auth-signed-link >= 1.0.0 hapi >= 21.0.0 => hapi-auth-signed-link >= 1.3.0

Usaage

Setup auth strategy and use it for a route

const hapiAuthSignedlink = require('@trigo/hapi-auth-signedlink')
server = new Hapi.Server();

// load the plugin
await server.register(hapiAuthSignedlink);

// configure strategy "default" to use the "signedlink" plugin
server.auth.strategy('default', 'signedlink', {
    // the secret used to sign the links. (required!)
    key: 'super secret signing key',

    // a custom failAction
    //
    // @param {Hapi request} request - the hapi request object 
    // @param {Hapi response toolkit} h - the hapi response toolkit. 
    //        See: https://github.com/hapijs/hapi/blob/master/API.md#response-toolkit
    // @param {string} reason - the fail reason ("param "auth" missing", "invalid signature" or "link expired")
    failAction: async (request, h, reason) => h.redirect('http://www.domain/my-error-page').takeover()
});

server.route([
    {
        method: 'POST',
        path: '/token',
        handler: tokenHandler,
        options: {
            auth: 'default',
        },
    },
]);

Usage of failAction option

A custom failAction method may be registered in order to customize the behaviour in case of failing authentication.

    // a custom failAction
    //
    // @param {Hapi request} request - the hapi request object 
    // @param {Hapi response toolkit} h - the hapi response toolkit. 
    //        See: https://github.com/hapijs/hapi/blob/master/API.md#response-toolkit
    // @param {string} error code - the fail reason 
    failAction: async (request, h, reason) => h.redirect(`http://www.domain/my-error-page?reason=${encodeURIComponent(reason)}`).takeover()

The default bahaviour is to return a HTTP 401 Unauthorized error with either one of the three possible error codes:

• E_AUTH_PARAM_MISSING - the URL did not contain the required auth=<signature> query parameter
• E_LINK_EXPIRED - the URL's expires_at=<timestamp> lies in the past
• E_INVALID_SIGNATURE - the siganture does not validate. e.g. the link was modified or created with another signing key

The error code that occoured is passed to the failAction method as third parameter reason

Create a signed link

Whe installed a helper method to create links is available in all hanlders throught the request object: request.server.plugins.hapiAuthSignedLink.createLink(<link>)