fix(bb-realtime): harden subscription token validation to prevent connect token reuse (#180)

Author: svidgen

.changeset/realtime-connect-token-scope.md

@@ -0,0 +1,5 @@
+---
+"@aws-blocks/bb-realtime": patch
+---
+
+Harden subscription token validation. Connect tokens now use a `$connect` suffix that prevents them from being reused as channel subscription tokens via prefix matching. Channel tokens remain valid as connect tokens. Backward-compatible during rollout.

packages/bb-realtime/src/aws-middleware.ts

@@ -227,6 +227,7 @@ function isRealtimeDescriptor(data: unknown): data is AwsRealtimeDescriptor {
 	return typeof data === 'object' && data !== null
 		&& (data as any).__blocks === 'realtime/channel'
 		&& typeof (data as any).wsUrl === 'string'
+		&& typeof (data as any).connectToken === 'string'
 		&& typeof (data as any).token === 'string';
 }
 

packages/bb-realtime/src/index.test.ts

@@ -3,6 +3,7 @@
 
 import { describe, it, beforeEach } from 'node:test';
 import assert from 'node:assert';
+import { createHmac } from 'node:crypto';
 import { Realtime, RealtimeErrors } from './index.js';
 import { LOCAL_TOKEN_SECRET } from './local-dev.js';
 import { mintChannelToken, validateChannelToken } from './utils.js';
@@ -512,6 +513,20 @@ describe('Realtime', () => {
 		assert.strictEqual(result, null);
 	});
 
+	it('validateChannelToken rejects token with missing channel field when requestedChannel is provided', () => {
+		// Craft a validly-signed token that has no channel field
+		const payload = { exp: Math.floor(Date.now() / 1000) + 3600 };
+		const payloadB64 = Buffer.from(JSON.stringify(payload)).toString('base64url');
+		const sig = createHmac('sha256', 'secret123').update(JSON.stringify(payload)).digest('base64url');
+		const token = `${payloadB64}.${sig}`;
+		// Without requestedChannel, it should pass (connection use)
+		const connResult = validateChannelToken(token, 'secret123');
+		assert.ok(connResult, 'token without channel should validate for connection');
+		// With requestedChannel, it must fail — tokens must declare what they authorize
+		const subResult = validateChannelToken(token, 'secret123', '/ns/chat/room-1');
+		assert.strictEqual(subResult, null, 'token without channel field must NOT authorize channel subscriptions');
+	});
+
 	// ── Channel Handle Token ─────────────────────────────────────────────
 
 	it('getChannel() toJSON includes a valid token', async () => {

packages/bb-realtime/src/index.ts

@@ -25,7 +25,7 @@ import type {
 	SubscribeOptions,
 } from './types.js';
 import { RealtimeErrors } from './errors.js';
-import { blocksError, validateSchema, mintChannelToken, validateChannelPath, validatePublishSize } from './utils.js';
+import { blocksError, validateSchema, mintChannelToken, mintConnectToken, validateChannelPath, validatePublishSize } from './utils.js';
 import { getBroadcastBus, LOCAL_TOKEN_SECRET } from './local-dev.js';
 import { Logger } from '@aws-blocks/bb-logger';
 import type { ChildLogger } from '@aws-blocks/bb-logger';
@@ -147,6 +147,7 @@ export const Realtime: {
 		const fullChannel = `${ns.prefix}/${channel}`;
 		validateChannelPath(fullChannel);
 		const token = mintChannelToken(fullChannel, LOCAL_TOKEN_SECRET);
+		const connectToken = mintConnectToken(this.fullId, LOCAL_TOKEN_SECRET);
 		return {
 			subscribe(handlerOrOptions: ((message: unknown) => void) | SubscribeOptions, _options?: never): RealtimeSubscription {
 				const handler = typeof handlerOrOptions === 'function' ? handlerOrOptions : handlerOrOptions.onMessage;
@@ -161,6 +162,7 @@ export const Realtime: {
 					__blocks: 'realtime/channel' as const,
 					channel: fullChannel,
 					wsUrl: (globalThis as any).__BLOCKS_REALTIME_WS_URL__,
+					connectToken,
 					token,
 				};
 			},

packages/bb-realtime/src/security.test.ts

@@ -101,9 +101,12 @@ describe('Security: mintConnectToken secret guard', () => {
 		const token = mintConnectToken('test-app-rt', 'valid-secret');
 		assert.ok(token);
 		assert.ok(token.includes('.'), 'token should have payload.signature format');
-		// connect token authorizes any sub-channel under the scope prefix
-		const result = validateChannelToken(token, 'valid-secret', 'test-app-rt/events/room-1');
-		assert.ok(result, 'connect token should authorize sub-channels');
+		// connect tokens should not authorize channel subscriptions
+		const subResult = validateChannelToken(token, 'valid-secret', 'test-app-rt/events/room-1');
+		assert.strictEqual(subResult, null, 'connect token must NOT authorize channel subscriptions');
+		// but it still validates without a requestedChannel (for connection establishment)
+		const connResult = validateChannelToken(token, 'valid-secret');
+		assert.ok(connResult, 'connect token should validate for connection establishment');
 	});
 });
 
@@ -152,7 +155,11 @@ describe('Security: getChannel() secret unavailability (AWS runtime simulation)'
 		assert.ok(chResult, 'channel token should validate');
 		assert.strictEqual(chResult!.channel, fullChannel);
 
+		// connect tokens should not authorize channel subscriptions
 		const connResult = validateChannelToken(connectToken, secret, fullChannel);
-		assert.ok(connResult, 'connect token should authorize the channel');
+		assert.strictEqual(connResult, null, 'connect token must NOT authorize channel subscriptions');
+		// but validates for connection (no requestedChannel)
+		const connValidation = validateChannelToken(connectToken, secret);
+		assert.ok(connValidation, 'connect token should validate for connection');
 	});
 });

packages/bb-realtime/src/token-scope.test.ts

@@ -0,0 +1,93 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Token scope isolation tests.
+ *
+ * Validates that connect tokens (scoped to the instance prefix) cannot be
+ * used to authorize channel subscriptions. Channel tokens scoped to a specific
+ * channel should still work as connect tokens since they already prove the
+ * holder has access to something within the instance.
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { mintChannelToken, mintConnectToken, validateChannelToken } from './utils.js';
+
+const SECRET = 'test-secret-key';
+const INSTANCE_PREFIX = 'myapp-rt';
+const CHANNEL = `${INSTANCE_PREFIX}/chat/room-1`;
+
+describe('Token scope isolation: connect tokens cannot subscribe to channels', () => {
+	it('channel token validates for its own channel', () => {
+		const token = mintChannelToken(CHANNEL, SECRET);
+		const result = validateChannelToken(token, SECRET, CHANNEL);
+		assert.ok(result, 'channel token should validate for its specific channel');
+		assert.strictEqual(result!.channel, CHANNEL);
+	});
+
+	it('connect token MUST NOT validate for a channel subscription', () => {
+		const connectToken = mintConnectToken(INSTANCE_PREFIX, SECRET);
+		// This is the critical assertion: a connect token should NOT authorize
+		// subscription to a specific channel under the instance prefix.
+		const result = validateChannelToken(connectToken, SECRET, CHANNEL);
+		assert.strictEqual(result, null, 'connect token must NOT authorize channel subscriptions');
+	});
+
+	it('connect token should not validate for any sub-channel', () => {
+		const connectToken = mintConnectToken(INSTANCE_PREFIX, SECRET);
+		// Try several channels under the instance prefix
+		const channels = [
+			`${INSTANCE_PREFIX}/events/room-1`,
+			`${INSTANCE_PREFIX}/notifications/user-123`,
+			`${INSTANCE_PREFIX}/cursors/doc-456`,
+		];
+		for (const ch of channels) {
+			const result = validateChannelToken(connectToken, SECRET, ch);
+			assert.strictEqual(result, null, `connect token must NOT authorize ${ch}`);
+		}
+	});
+
+	it('channel token works as a connect token (no requestedChannel)', () => {
+		const channelToken = mintChannelToken(CHANNEL, SECRET);
+		// When validating for connection (no requestedChannel), any valid token
+		// from this instance should be accepted
+		const result = validateChannelToken(channelToken, SECRET);
+		assert.ok(result, 'channel token should be valid as a connect token');
+	});
+
+	it('new-style connect token validates without requestedChannel (connection use)', () => {
+		const connectToken = mintConnectToken(INSTANCE_PREFIX, SECRET);
+		// Connect tokens should still work for connection establishment
+		const result = validateChannelToken(connectToken, SECRET);
+		assert.ok(result, 'connect token should validate for connection establishment');
+	});
+
+	it('channel token for one channel cannot subscribe to a different channel', () => {
+		const token = mintChannelToken(`${INSTANCE_PREFIX}/chat/room-1`, SECRET);
+		const result = validateChannelToken(token, SECRET, `${INSTANCE_PREFIX}/chat/room-2`);
+		assert.strictEqual(result, null, 'channel token for room-1 must NOT authorize room-2');
+	});
+
+	it('namespace-level token still works for sub-channels', () => {
+		// A token scoped to a namespace (not the instance root) should still
+		// authorize sub-channels within that namespace
+		const nsToken = mintChannelToken(`${INSTANCE_PREFIX}/chat`, SECRET);
+		const result = validateChannelToken(nsToken, SECRET, `${INSTANCE_PREFIX}/chat/room-1`);
+		assert.ok(result, 'namespace token should authorize sub-channels');
+	});
+
+	it('instance name containing $connect does not create ambiguity', () => {
+		// If an instance is literally named "foo$connect", its connect token
+		// channel field is "foo$connect$connect". This must NOT authorize
+		// channels under the instance like "foo$connect/cursors/room-1".
+		const weirdPrefix = 'foo$connect';
+		const connectToken = mintConnectToken(weirdPrefix, SECRET);
+		const channel = `${weirdPrefix}/cursors/room-1`;
+		const result = validateChannelToken(connectToken, SECRET, channel);
+		assert.strictEqual(result, null, 'connect token for $connect-named instance must NOT authorize its channels');
+
+		// But it still validates for connection establishment
+		const connResult = validateChannelToken(connectToken, SECRET);
+		assert.ok(connResult, 'connect token should still validate for connection');
+	});
+});

packages/bb-realtime/src/utils.ts

@@ -79,17 +79,19 @@ export function mintChannelToken(channel: string, secret: string, ttlSeconds = 3
 }
 
 /**
- * Mint a connect token. Scoped to a Realtime instance prefix (not a specific
- * channel). Used to gate WebSocket connection establishment. The connect token
- * validates for any channel that starts with the given scope prefix.
+ * Mint a connect token. Scoped to a Realtime instance prefix with a `$connect`
+ * suffix (e.g., `myapp-rt$connect`). Connect tokens authorize WebSocket
+ * connection establishment but not channel subscriptions — the `$connect`
+ * suffix ensures the token's channel field does not prefix-match real channel
+ * paths (which always contain a `/` separator after the instance prefix).
  *
  * Default TTL is 2 hours (matching API Gateway max connection duration).
  */
 export function mintConnectToken(scopePrefix: string, secret: string, ttlSeconds = 7200): string {
 	if (!secret) {
 		throw blocksError(RealtimeErrors.ConnectionFailed, 'Refusing to mint token: signing secret is empty or missing');
 	}
-	return mintChannelToken(scopePrefix, secret, ttlSeconds);
+	return mintChannelToken(scopePrefix + '$connect', secret, ttlSeconds);
 }
 
 /**
@@ -109,7 +111,10 @@ export function validateChannelToken(
 		const expectedSig = createHmac('sha256', secret).update(JSON.stringify(payload)).digest('base64url');
 		if (!constantTimeEquals(sig, expectedSig)) return null;
 		if (payload.exp && payload.exp < Math.floor(Date.now() / 1000)) return null;
-		if (requestedChannel && payload.channel && requestedChannel !== payload.channel && !requestedChannel.startsWith(payload.channel + '/')) return null;
+		if (requestedChannel) {
+			if (!payload.channel) return null;
+			if (requestedChannel !== payload.channel && !requestedChannel.startsWith(payload.channel + '/')) return null;
+		}
 		return payload;
 	} catch {
 		return null;

test-apps/comprehensive/aws-blocks/index.ts

@@ -1222,9 +1222,12 @@ export const api = new ApiNamespace(scope, 'api', (context) => ({
   },
 
   async realtimeGetRawDescriptor(subChannel: string) {
-    // Return the raw toJSON() descriptor (not hydrated) so tests can inspect/tamper with tokens
+    // Return the raw toJSON() descriptor with __blocks removed so client middleware
+    // does NOT hydrate it into a channel client. Tests need the raw token fields.
     const ch = await realtime.getChannel('cursors', subChannel);
-    return ch.toJSON();
+    const raw = ch.toJSON() as Record<string, unknown>;
+    const { __blocks, ...descriptor } = raw;
+    return descriptor;
   },
 
   async realtimeGetPoisonedChannel(subChannel: string) {

test-apps/comprehensive/test/realtime.test.ts

@@ -98,6 +98,65 @@ export function realtimeTests(getApi: () => typeof apiType) {
 			});
 		});
 
+		describe('Token Scope Isolation', () => {
+			test('connect token cannot be reused as a channel subscription token', async () => {
+				const api = getApi();
+
+				// Get raw descriptors to extract tokens and channel paths
+				// realtimeGetRawDescriptor strips __blocks so middleware won't hydrate them
+				const publicDescriptor = await api.realtimeGetRawDescriptor('public-room') as unknown as { connectToken: string; wsUrl: string; token: string; channel: string };
+				const privateDescriptor = await api.realtimeGetRawDescriptor('private-room') as unknown as { channel: string; token: string };
+
+				const { connectToken, wsUrl } = publicDescriptor;
+				const { channel: privateChannel } = privateDescriptor;
+
+				assert.ok(connectToken, 'Descriptor should include a connectToken');
+				assert.ok(wsUrl, 'Descriptor should include a wsUrl');
+				assert.ok(privateChannel, 'Private descriptor should include a channel path');
+
+				// Open a raw WebSocket using the connect token for connection auth
+				const ws = new WebSocket(`${wsUrl}?token=${encodeURIComponent(connectToken)}`);
+
+				const reply = await new Promise<{ type: string; channel?: string; message?: string }>((resolve, reject) => {
+					const timer = globalThis.setTimeout(() => {
+						ws.close();
+						reject(new Error('No reply from server within 5s'));
+					}, 5000);
+
+					ws.onopen = () => {
+						// Attempt to subscribe using the connect token AS the channel token.
+						// This should be rejected — connect tokens are scoped to the instance
+						// prefix ($connect) and must not authorize channel subscriptions.
+						ws.send(JSON.stringify({
+							action: 'subscribe',
+							channel: privateChannel,
+							token: connectToken,
+						}));
+					};
+
+					ws.onmessage = (event) => {
+						clearTimeout(timer);
+						resolve(JSON.parse(event.data as string));
+					};
+
+					ws.onerror = () => {
+						clearTimeout(timer);
+						reject(new Error('WebSocket error'));
+					};
+				});
+
+				ws.close();
+
+				// The server must reject the subscription — a connect token is NOT a valid channel token
+				assert.strictEqual(reply.type, 'error', 'Server should reject subscribe with a connect token used as channel token');
+				assert.strictEqual(reply.channel, privateChannel, 'Error should reference the requested channel');
+				assert.ok(
+					reply.message && reply.message.includes('Unauthorized'),
+					`Expected an Unauthorized error message, got: ${reply.message}`,
+				);
+			});
+		});
+
 		describe('Schema Validation', () => {
 			test('publish with wrong shape is rejected', async () => {
 				const api = getApi();