Channel Authentication and Authorization

This document describes the channel authentication and authorization system in Hypervel's broadcasting implementation. It covers how channel access is controlled through authentication routes, authorization callbacks, multi-guard user retrieval, and protocol-specific signature generation for Pusher and Ably.

For information about the overall broadcasting architecture and driver management, see Broadcasting Architecture and Drivers. For event broadcasting and anonymous events, see Event Broadcasting and Anonymous Events.

Overview

Channel authentication protects private and presence channels by verifying that the requesting user has permission to subscribe. The system provides:

• HTTP routes for channel and user authentication (/broadcasting/auth, /broadcasting/user-auth)
• Registration of authorization callbacks with pattern matching
• Multi-guard user retrieval with fallback support
• Parameter binding and model resolution from channel names
• Protocol-specific signature generation (Pusher, Ably)

Figure 1: Channel Authentication Flow

Sources: src/broadcasting/src/BroadcastManager.php72-114 src/broadcasting/src/BroadcastController.php13-19 src/broadcasting/src/Broadcasters/Broadcaster.php88-114

Authentication Routes Registration

The BroadcastManager provides methods to register authentication routes that handle channel subscription requests from WebSocket clients.

Channel Authentication Route

The routes() method (aliased as channelRoutes()) registers the /broadcasting/auth endpoint:

Figure 2: Route Registration Process

The route registration automatically:

• Applies the web middleware group by default
• Excludes VerifyCsrfToken middleware (CSRF protection not needed for WebSocket auth)
• Registers for all configured server kernels (e.g., http, https)
• Accepts both GET and POST methods for client compatibility

src/broadcasting/src/BroadcastManager.php72-94

User Authentication Route

The userRoutes() method registers /broadcasting/user-auth for user-level authentication:

This endpoint is used by Pusher's user authentication feature to authenticate individual users rather than channel subscriptions. The BroadcastController::authenticateUser() method handles these requests.

src/broadcasting/src/BroadcastManager.php100-114 src/broadcasting/src/BroadcastController.php22-31

Route Attribute Configuration

Attribute	Default Value	Purpose
middleware	['web']	Applies session and cookie handling
without_middleware	[VerifyCsrfToken::class]	Excludes CSRF verification

Custom attributes can be passed to override defaults:

Sources: src/broadcasting/src/BroadcastManager.php76-81 tests/Broadcasting/BroadcastManagerTest.php124-156

Channel Authorization Callbacks

Channel authorization callbacks determine whether a user can access a specific channel. Callbacks are registered using the channel() method on the Broadcaster class.

Registering Authorization Callbacks

Figure 3: Channel Authorization Lifecycle

The channel() method accepts three parameters:

1. Pattern: Channel name pattern with optional parameters (e.g., "chat.{roomId}")
2. Callback: Closure or class name that performs authorization
3. Options: Array of options including guards for authentication

src/broadcasting/src/Broadcasters/Broadcaster.php70-84

Channel Name Patterns

Channel patterns support parameter placeholders using curly braces:

Pattern	Matches	Parameters Extracted
"chat.{roomId}"	"chat.42"	['roomId' => '42']
"user.{userId}.notifications"	"user.123.notifications"	['userId' => '123']
"order.{orderId}.status.{statusId}"	"order.456.status.789"	['orderId' => '456', 'statusId' => '789']

Pattern matching uses regex conversion:

src/broadcasting/src/Broadcasters/Broadcaster.php280-286 tests/Broadcasting/BroadcasterTest.php360-383

Authorization Callback Types

Closure Callbacks

The callback receives:

1. The authenticated user (first parameter)
2. Extracted channel parameters (subsequent parameters)

Class-Based Callbacks

Class-based callbacks must define a join() method. The broadcaster resolves the class from the container and calls the method.

src/broadcasting/src/Broadcasters/Broadcaster.php150-160 src/broadcasting/src/Broadcasters/Broadcaster.php233-238

Authorization Return Values

Return Value	Behavior
true	Grants access with no additional data
false	Denies access, throws AccessDeniedHttpException
array	Grants access, includes data in presence channel info
null	Denies access (treated as falsy)

For presence channels, returning an array provides user information to other channel members:

src/broadcasting/src/Broadcasters/Broadcaster.php103-110

Sources: src/broadcasting/src/Broadcasters/Broadcaster.php88-114 tests/Broadcasting/BroadcasterTest.php52-75

User Retrieval and Guard Configuration

The authentication system supports multiple authentication guards with fallback behavior, allowing different authentication mechanisms to be tried in order.

Guard Configuration

Guards are specified in the channel options during registration:

src/broadcasting/src/Broadcasters/Broadcaster.php72-84

User Retrieval Logic

Figure 4: Multi-Guard User Retrieval

The retrieveUser() method implements the following logic:

1. Retrieve channel options using pattern matching
2. If no guards specified, use default guard (AuthManager::user())
3. If guards specified, iterate through them in order
4. Return the first authenticated user found
5. Return null if no guards authenticate a user

src/broadcasting/src/Broadcasters/Broadcaster.php240-262

Channel Options Retrieval

Channel options are stored alongside channel callbacks and retrieved using pattern matching:

This allows different channels with the same pattern to share options while supporting wildcard patterns.

src/broadcasting/src/Broadcasters/Broadcaster.php264-278

Sources: src/broadcasting/src/Broadcasters/Broadcaster.php240-278 tests/Broadcasting/BroadcasterTest.php172-316

Parameter Binding and Model Resolution

The authentication system supports automatic model binding, similar to route model binding, allowing Eloquent models to be injected into authorization callbacks.

Parameter Extraction Process

Figure 5: Parameter Binding and Model Resolution

Extraction Steps

1. Pattern Matching: Convert channel pattern to regex and extract named parameters

2. Callback Reflection: Use PHP reflection to analyze callback parameters

3. Implicit Binding: Check if parameter type implements UrlRoutable interface

4. Model Resolution: Call resolveRouteBinding() on the model

src/broadcasting/src/Broadcasters/Broadcaster.php116-206

Example: Model Binding

If the model is not found, an AccessDeniedHttpException is thrown, denying channel access.

Sources: src/broadcasting/src/Broadcasters/Broadcaster.php116-206 tests/Broadcasting/BroadcasterTest.php52-107

Signature Generation

Different broadcasting protocols require different authentication signatures. The system supports protocol-specific signature generation for Pusher, Ably, and other broadcasters.

Pusher Signature Generation

The PusherBroadcaster (implementation referenced but not shown in provided files) generates signatures following the Pusher authentication protocol:

Private Channels:

auth = app_key:signature
signature = HMAC-SHA256(socket_id:channel_name, app_secret)

Presence Channels:

auth = app_key:signature
signature = HMAC-SHA256(socket_id:channel_name:channel_data, app_secret)
channel_data = JSON({user_id: string, user_info: object})

Ably Signature Generation

The AblyBroadcaster implements Ably-specific signature generation:

src/broadcasting/src/Broadcasters/AblyBroadcaster.php88-98

Authentication Response Format

Figure 6: Authentication Response Generation

The validAuthenticationResponse() method formats the response based on channel type:

For Private Channels:

For Presence Channels:

src/broadcasting/src/Broadcasters/AblyBroadcaster.php50-86

User Identifier for Broadcasting

The system determines the user identifier for signatures using the following priority:

1. getAuthIdentifierForBroadcasting() method if it exists
2. getAuthIdentifier() method (standard Authenticatable interface)

This allows custom user identifiers for broadcasting without affecting authentication.

src/broadcasting/src/Broadcasters/AblyBroadcaster.php69-71

Sources: src/broadcasting/src/Broadcasters/AblyBroadcaster.php50-98 tests/Broadcasting/AblyBroadcasterTest.php44-120

Channel Types and Naming Conventions

The broadcasting system distinguishes between public, private, and presence channels using naming conventions.

Channel Type Detection

Figure 7: Channel Type Classification

The isGuardedChannel() method determines if authentication is required:

src/broadcasting/src/Broadcasters/AblyBroadcaster.php135-138

Channel Name Normalization

Protocol-specific broadcasters normalize channel names by removing prefixes:

Original Channel	Normalized Channel	Type
private-chat.42	chat.42	Private
private-encrypted-secret	secret	Private Encrypted
presence-lobby	lobby	Presence
public-news	public-news	Public

The normalized name is used for pattern matching with registered authorization callbacks:

src/broadcasting/src/Broadcasters/AblyBroadcaster.php140-152

Sources: src/broadcasting/src/Broadcasters/AblyBroadcaster.php135-152 tests/Broadcasting/UsePusherChannelsNamesTest.php19-92

User Authentication for Connections

Beyond channel-specific authentication, the system supports user-level authentication for WebSocket connections using the resolveAuthenticatedUser() callback.

Custom User Resolution

The callback should return:

• An array with id and optional user_info for authenticated users
• null for unauthenticated requests

src/broadcasting/src/Broadcasters/Broadcaster.php46-67

User Authentication Endpoint

The /broadcasting/user-auth endpoint uses the configured callback:

This endpoint is used by Pusher's user authentication feature to establish the user's identity before subscribing to any channels.

src/broadcasting/src/BroadcastController.php22-31

Sources: src/broadcasting/src/Broadcasters/Broadcaster.php46-67 src/broadcasting/src/BroadcastController.php22-31 tests/Broadcasting/BroadcasterTest.php318-358

Static Channel Storage

Channel registrations and options are stored statically across all Broadcaster instances, ensuring that channels registered during application bootstrap are available during request handling.

Shared State Architecture

Figure 8: Static Channel Storage

The static storage pattern ensures:

1. Channels registered at boot time are available during requests
2. Multiple broadcaster instances (from pool proxies) share the same channels
3. Channel registrations persist across coroutine contexts

Testing utilities can flush static state:

src/broadcasting/src/Broadcasters/Broadcaster.php36-44 src/broadcasting/src/Broadcasters/Broadcaster.php296-303

Sources: src/broadcasting/src/Broadcasters/Broadcaster.php36-44 src/broadcasting/src/Broadcasters/Broadcaster.php296-303 tests/Broadcasting/BroadcasterTest.php385-401