README.md

twitch-ebs-tools

As of 16 March 2023 this project is no longer maintained or updated.

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 twitch-ebs-tools

Manual build

git clone https://github.com/lwojcik/twitch-ebs-tools.git
cd twitch-ebs-tools
npm install
npm run build

Access via CDN

Twitch-ebs-tools is also available as UMD module and it can be accessed via CDN:

// Using jsDelivr:
<script src="https://cdn.jsdelivr.net/npm/twitch-ebs-tools/dist/index.umd.js"></script>

// Using unpkg:
<script src="https://unpkg.com/twitch-ebs-tools/dist/index.umd.js"></script>

Basic usage

Initialization

For methods starting with validate class initialization is needed:

const { TwitchEbsTools } = require("twitch-ebs-tools");

/**
 * Or using TypeScript / ES6 import:
 * import { TwitchEbsTools } from '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, ignoreExpiration?)

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
• ignoreExpiration (optional) - when true, token expiration time will not be checked

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.verifyTokenNotExpired(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

Legal

This project is not authored, affiliated or endorsed in any way by Twitch.tv.