twitch-ebs-tools

Pack of useful functions for Twitch Extension Backend Services (EBS). It provides Twitch JWT verification methods and various validation strategies.

Primarily intended as a backend for a Fastify plugin for my StarCraft II Twitch extension, it can also be used as a standalone package or ported to other Node servers. Internally it uses jsonwebtoken for validating JWT tokens issued by Twitch.

Install

npm install --save twitch-ebs-tools

Basic usage

Initialization

For methods starting with validate class initialization is needed:

const TwitchEbsTools = require('twitch-ebs-tools');

const twitchEbs = new TwitchEbsTools('twitch shared secret');

Methods starting with verify are static, as they don't rely on Twitch shared secret.

Example:

const TwitchEbsTools = require('twitch-ebs-tools');

const payload = new TwitchEbsTools('twitch shared secret').validateToken('token');

const validChannelId = TwitchEbsTools.verifyChannelId(payload, '123456789');
// true / false

validateToken(token)

Validates Twitch token by passing it to verify method of jsonwebtoken. Returns decoded Twitch payload or throws an error for invalid token.

It is the most basic method that serves as a basis for more granular strategies.

const TwitchEbsTools = require('twitch-ebs-tools');

const twitchEbs = new TwitchEbsTools('twitch shared secret');

const twitchPayload = twitchEbs.validateToken(token);

console.log(twitchPayload); // decoded Twitch payload

validatePermission(token, channelId, roles)

Validates whether supplied Twitch token:

• can be verified correctly as issued by Twitch (using validateToken method)
• contains correct channel ID
• contains correct channel role

const TwitchEbsTools = require('twitch-ebs-tools');

const twitchEbs = new TwitchEbsTools('twitch shared secret');

const permissionValid = twitchEbs.validatePermission('token', '123456789', [ 'viewer', 'broadcaster' ]);

console.log(permissionValid); // true or false

Parameters:

• token - JWT token issued by Twitch as string
• channelId - Twitch channel ID used for validating the Twitch token
• role - Twitch role(s) to be used for validating supplied token. It accepts strings (e.g. viewer) or arrays of string (e.g. ['viewer', 'broadcaster']). In case of arrays one of the roles is needed to pass the validation

Static methods

The following methods require decoded Twitch payload as one of their parameters. Payload can be supplied with validateToken method or passed as a variable from an outside source.

Static methods can be used pretty much out-of-the-box. They are intended to be helpful while building more detailed validation strategies and integrate easily with other tools.

verifyChannelId(payload, channelId)

Verifies whether supplied Twitch payload contains channel ID passed as a string parameter. Returns true / false. If Twitch payload is malformed, it returns false.

const TwitchEbsTools = require('twitch-ebs-tools');

const payload = new TwitchEbsTools('twitch shared secret').validateToken('token');

const validChannelId = TwitchEbsTools.verifyChannelId(payload, '123456789');
// true / false

verifyTokenNotExpired(payload)

Verifies whether supplied Twitch payload is time valid by comparing exp property with current server time. Twitch tokens are valid for one hour since being issued.

const TwitchEbsTools = require('twitch-ebs-tools');

const payload = new TwitchEbsTools('twitch shared secret').validateToken('token');

const tokenNotExpired = TwitchEbsTools.verifyChannelId(payload);
// true / false

verifyRole(payload, role)

Verifies whether supplied Twitch payload contains valid role. It accepts Twitch role (viewer or broadcaster) as string.

const TwitchEbsTools = require('twitch-ebs-tools');

const payload = new TwitchEbsTools('twitch shared secret').validateToken('token');

const correctRole = TwitchEbsTools.verifyRole(payload, 'viewer');
// true / false

verifyChannelIdAndRole(payload, channelId, role)

Verifies whether supplied Twitch payload contains valid channel id and role. It accepts Twitch channel ID as string and Twitch role (viewer or broadcaster) as string.

const TwitchEbsTools = require('twitch-ebs-tools');

const payload = new TwitchEbsTools('twitch shared secret').validateToken('token');

const correctChannelIdAndRole = TwitchEbsTools.verifyChannelIdAndRole(payload, 'viewer');
// true / false

verifyBroadcaster(payload)

Verifies whether supplied Twitch payload contains valid broadcaster role. This method is useful for verifying broadcaster-only routes (e.g. Twitch extension configuration sections).

Note that this only checks for a Twitch broadcaster role and does not perform any further checks.

const TwitchEbsTools = require('twitch-ebs-tools');

const payload = new TwitchEbsTools('twitch shared secret').validateToken('token');

const correctBroadcasterRole = TwitchEbsTools.verifyBroadcaster(payload);
// true / false

verifyViewerOrBroadcaster(payload)

Verifies whether supplied Twitch payload contains either broadcaster (Twitch channel owner) or viewer (channel viewer) role. This method is useful for verifying public routes (e.g. Twitch extension panels).

Note that checking for both roles is necessary for the extensions to work correctly. If you validate panel route against viewer route only, the extension will not work correctly for channel broadcaster.

Note that this only checks for Twitch broadcaster or viewer roles and does not perform any further checks.

const TwitchEbsTools = require('twitch-ebs-tools');

const payload = new TwitchEbsTools('twitch shared secret').validateToken('token');

const correctViewerOrBroadcasterRole = TwitchEbsTools.verifyViewerOrBroadcaster(payload);
// true / false

License

Licensed under MIT License. See LICENSE for more information.