fix(auth): accept equivalencies when comparing scopes

jest.config.js

@@ -0,0 +1,4 @@
+module.exports = {
+	preset: 'ts-jest',
+	verbose: true
+};

package.json

@@ -11,6 +11,10 @@
     "@d-fischer/documen.ts": "^0.14.1",
     "@d-fischer/eslint-config": "^5.0.0",
     "@types/node": "^12.12.47",
+    "@types/jest": "^27.4.1",
+    "jest": "^27.5.1",
+    "jest-environment-node": "^27.5.1",
+    "ts-jest": "^27.1.4",
     "cross-env": "^7.0.3",
     "eslint": "^7.17.0",
     "eslint-import-resolver-lerna": "^2.0.0",
@@ -29,7 +33,8 @@
     "build": "lerna run build",
     "rebuild": "lerna run rebuild",
     "docs": "documen.ts",
-    "lerna": "lerna"
+    "lerna": "lerna",
+    "test": "jest"
   },
   "husky": {
     "hooks": {

packages/api/src/api/helix/channel/HelixChannelApi.ts

@@ -77,7 +77,7 @@ export class HelixChannelApi extends BaseApi {
 			type: 'helix',
 			url: 'channels',
 			method: 'PATCH',
-			scope: 'user:edit:broadcast',
+			scope: 'channel:manage:broadcast',
 			query: {
 				broadcaster_id: userId
 			},

packages/api/src/api/helix/stream/HelixStreamApi.ts

@@ -221,7 +221,7 @@ export class HelixStreamApi extends BaseApi {
 				url: 'streams/markers',
 				method: 'POST',
 				type: 'helix',
-				scope: 'user:edit:broadcast',
+				scope: 'channel:manage:broadcast',
 				query: {
 					user_id: extractUserId(broadcaster),
 					description
@@ -265,7 +265,7 @@ export class HelixStreamApi extends BaseApi {
 		await this._client.callApi({
 			type: 'helix',
 			url: 'streams/tags',
-			scope: 'user:edit:broadcast',
+			scope: 'channel:manage:broadcast',
 			method: 'PUT',
 			query: {
 				broadcaster_id: extractUserId(broadcaster)

packages/auth/src/__tests__/helpers.test.ts

@@ -0,0 +1,66 @@
+import { compareScopes } from '../helpers';
+
+describe('Scope comparer', () => {
+	it('does nothing when required scopes are absent', () => {
+		compareScopes([]);
+		compareScopes([], []);
+		compareScopes(['channel:moderate']);
+		compareScopes(['channel:moderate'], []);
+	});
+
+	it('passes when required scopes are met', () => {
+		compareScopes(['bits:read'], ['bits:read']);
+		compareScopes(['bits:read', 'channel:moderate'], ['bits:read']);
+		compareScopes(['bits:read', 'channel:moderate'], ['bits:read', 'channel:moderate']);
+		compareScopes(['bits:read', 'channel:moderate', 'channel:read:goals'], ['bits:read', 'channel:moderate']);
+		compareScopes(
+			['bits:read', 'channel:moderate', 'channel:read:goals'],
+			['bits:read', 'channel:moderate', 'channel:read:goals']
+		);
+	});
+
+	function expectError(scopesToCompare: string[], requestedScopes?: string[]) {
+		expect(() => {
+			compareScopes(scopesToCompare, requestedScopes);
+		}).toThrow();
+	}
+
+	it('throws error when a require scope is not present', () => {
+		expectError([], ['bits:read']);
+		expectError(['channel:moderate'], ['bits:read']);
+		expectError(['channel:moderate'], ['bits:read', 'channel:moderate']);
+		expectError(['channel:moderate'], ['channel:moderate', 'bits:read']);
+		expectError(['channel:moderate', 'channel:read:goals'], ['channel:moderate', 'bits:read']);
+		expectError(
+			['channel:moderate', 'channel:read:goals'],
+			['channel:moderate', 'channel:read:goals', 'bits:read']
+		);
+	});
+
+	it('passes for scope equivalencies', () => {
+		compareScopes(['user:edit:broadcast'], ['channel:manage:broadcast']);
+		compareScopes(['channel_subscriptions'], ['channel:read:subscriptions']);
+		compareScopes(['channel_subscriptions', 'channel:read:subscriptions'], ['channel:read:subscriptions']);
+		compareScopes(
+			['channel_subscriptions', 'channel:read:subscriptions'],
+			['channel_subscriptions', 'channel:read:subscriptions']
+		);
+		compareScopes(['channel_subscriptions', 'user_blocks_read'], ['channel:read:subscriptions']);
+		compareScopes(
+			['channel_subscriptions', 'user_blocks_read'],
+			['channel:read:subscriptions', 'user:read:blocked_users']
+		);
+		compareScopes(
+			['channel_subscriptions', 'user_blocks_read', 'channel:read:goals'],
+			['channel:read:subscriptions', 'user:read:blocked_users']
+		);
+		compareScopes(
+			['channel_subscriptions', 'user_blocks_read', 'channel:read:goals'],
+			['channel:read:subscriptions', 'user:read:blocked_users', 'channel:read:goals']
+		);
+	});
+
+	it('avoids undesired reverse scope equivalencies', () => {
+		expectError(['channel:manage:broadcast'], ['user:edit:broadcast']);
+	});
+});

packages/auth/src/helpers.ts

@@ -190,20 +190,45 @@ export async function getValidTokenFromProvider(
 	throw lastTokenError ?? new Error('Could not retrieve a valid token');
 }
 
+const scopeEquivalencies = new Map([
+	['channel_commercial', 'channel:edit:commercial'],
+	['channel_editor', 'channel:manage:broadcast'],
+	['channel_read', 'channel:read:stream_key'],
+	['channel_subscriptions', 'channel:read:subscriptions'],
+	['user_blocks_read', 'user:read:blocked_users'],
+	['user_blocks_edit', 'user:manage:blocked_users'],
+	['user_follows_edit', 'user:edit:follows'],
+	['user_read', 'user:read:email'],
+	['user_subscriptions', 'user:read:subscriptions'],
+	['user:edit:broadcast', 'channel:manage:broadcast']
+]);
+
 /**
  * Compares scopes for a non-upgradable `AuthProvider` instance.
  *
  * @param scopesToCompare The scopes to compare against.
  * @param requestedScopes The scopes you requested.
  */
 export function compareScopes(scopesToCompare: string[], requestedScopes?: string[]): void {
-	if (requestedScopes?.some(scope => !scopesToCompare.includes(scope))) {
-		throw new Error(
-			`This token does not have the requested scopes (${requestedScopes.join(', ')}) and can not be upgraded.
+	if (requestedScopes !== undefined) {
+		const scopes = new Set<string>();
+		for (const scope of scopesToCompare) {
+			scopes.add(scope);
+
+			const equivalent = scopeEquivalencies.get(scope);
+			if (equivalent !== undefined) {
+				scopes.add(equivalent);
+			}
+		}
+
+		if (requestedScopes.some(scope => !scopes.has(scope))) {
+			throw new Error(
+				`This token does not have the requested scopes (${requestedScopes.join(', ')}) and can not be upgraded.
 If you need dynamically upgrading scopes, please implement the AuthProvider interface accordingly:
 
 \thttps://twurple.js.org/reference/auth/interfaces/AuthProvider.html`
-		);
+			);
+		}
 	}
 }
 

packages/pubsub/src/SingleUserPubSubClient.ts

@@ -165,7 +165,7 @@ export class SingleUserPubSubClient {
 	 * It receives a {@PubSubSubscriptionMessage} object.
 	 */
 	async onSubscription(callback: (message: PubSubSubscriptionMessage) => void): Promise<PubSubListener<never>> {
-		return await this._addListener('channel-subscribe-events-v1', callback, 'channel_subscriptions');
+		return await this._addListener('channel-subscribe-events-v1', callback, 'channel:read:subscriptions');
 	}
 
 	/**

tsconfig.json

@@ -15,5 +15,5 @@
 		"isolatedModules": true,
 		"declarationMap": true
 	},
-	"exclude": ["node_modules", "lib", "es"]
+	"exclude": ["node_modules", "lib", "es", "__tests__"]
 }