README.md

hapi Auth Plugin for AWS SNS

Plugin for hapi to easily setup an auth strategy that validates an AWS SNS payload using the sns-payload-validator.

Installing

npm install --save hapi-auth-sns

Please note: While SignatureVersion 1 is the default, on 2022-09-19 AWS announced the ability to set topics with SignatureVersion 2. Starting with version 1.1.0 of this plugin, SignatureVersion 1 and 2 are supported.

Getting Started

const Hapi = require('hapi');
const Sns = require('hapi-auth-sns');

const init = async () => {

    const server = Hapi.server({
        port: 3000,
        host: '0.0.0.0'
    });

    // Register the plugin
    await server.register(Sns);

    // Declare an authentication strategy using the sns scheme.
    server.auth.strategy('mySnsStrategy', 'sns');

    // Add a route that requires authentication.
    server.route({
        method: 'POST',
        path: '/',
        config: {
            auth: {
                strategy: 'mySnsStrategy',
                scope: 'myTopic' // optional
            },
        },
        handler: (request, h) => {

            // Make sure the message is a notification, not a subscription confirmation.
            if (request.payload.Type === 'Notification') {
                return `The message from myTopic is: ${request.payload.Message}`;
            }

            return 'This is a subscription confirmation message.';
        }

        await server.start();
        console.log('Server running on %s', server.info.uri);
    });
};

init();

Scopes

The scope in the credentials is set to the topic name, derived from the TopicArn in the payload.

To limit the route to a single topic, set the scope option to the topic name:

auth: {
    strategy: 'mySnsStrategy',
    scope: 'myTopic'
}

To allow multiple topics, set the scope option to an array of topic names:

auth: {
    strategy: 'mySnsStrategy',
    scope: ['myTopic1', 'myTopic2']
}

To allow all topics, omit the scope option:

auth: {
    strategy: 'mySnsStrategy'
}

Options

There are four options available for the sns strategy:

• autoSubscribe - A message type of SubscriptionConfirmation automatically subscribes the route to the topic after validation, default true.
• autoResubscribe - A message type of UnsubscribeConfirmation automatically resubscribes the route to the topic after validation, default true.
• useCache - The plugin uses a cache to store the certificate for each topic. This is enabled by default, but can be disabled if you don't want to use the cache. If disabled, the certificate will be fetched from the SNS service for each request.
• maxCerts - The maximum number of certificates to store in the cache. This is only used if useCache is enabled. The default is 5000.

All settings can be changed when declaring the strategy:

server.auth.strategy('mySnsStrategy', 'sns', {
    autoSubscribe: false,
    autoResubscribe: false,
    useCache: true,
    maxCerts: 100
});

Additional Information

The request.payload will have the following properties:

• Type - The message type: Notification, SubscriptionConfirmation or UnsubscribeConfirmation.
• MessageId - A uuid provided by the SNS service for each message.
• Token - The token that must be passed to the SubscribeURL to confirm the subscription when the message type is SubscriptionConfirmation or UnsubscribeConfirmation.
• TopicArn - The ARN of the topic the message was sent from.
• Subject - The subject of the message when the message type is Notification. This is not present if a Subject was not provided when the message was published.
• Message - The message body when the message type is Notification.
• Timestamp - The time the message was sent.
• SignatureVersion - The version of the signature algorithm used to sign the message. Defaults to 1, can also be 2.
• Signature - The signature of the message used to verify the message integrity.
• SigningCertURL - The URL of the certificate used to sign the message.
• SubscribeURL - The URL used to subscribe the route when the message type is SubscriptionConfirmation or UnsubscribeConfirmation.
• UnsubscribeURL - The URL used to unsubscribe the route when the message type is Notification.

Due to how payload validation works, request.auth.credentials.sns will be set to true if payload is valid. However, it is not used by the plugin.

Acknowledgements

The format of the code was adapted from the @hapi/jwt module, BSD-3-Clause, which is maintained by the fine folks in the hapijs community.