AsyncAPI 3.0 specification for the AuthSocketServer / AuthSocket
WebSocket channel used by the BSV MessageBox Server.
AuthSocketServer wraps Socket.IO and sits on top of an HTTP server.
All Socket.IO events are standard Socket.IO framing; this spec describes
the application-level event names and payload shapes that flow over the
Socket.IO connection.
Every Socket.IO connection undergoes BRC-103 (Peer) handshake before
application events are exchanged. The handshake is carried on the
authMessage event using the AuthMessage envelope defined in the
@bsv/sdk Transport interface.
Once the handshake succeeds the peer's identityKey (compressed secp256k1
public key, 66-char hex) is known server-side and stored in memory for the
lifetime of the connection.
After authentication the server emits and listens for the events described
below. All application payloads are serialized as JSON inside the
BRC-103 general message (Peer.toPeer). The transport layer
(SocketServerTransport) wraps them in an { eventName, data } envelope
before signing.
Source of truth:
packages/messaging/authsocket/src/AuthSocketServer.tspackages/messaging/authsocket/src/SocketServerTransport.tspackages/messaging/message-box-server/src/index.tsProduction MessageBox WebSocket endpoint (Socket.IO over WSS).
Local development Socket.IO server.
HTTP port the MessageBox Server listens on.
Low-level Socket.IO event used by SocketServerTransport to carry
BRC-103 AuthMessage frames. This event is NOT an application event;
it is emitted and received transparently by the Peer class from
@bsv/sdk. Application developers do not interact with this channel
directly — they use the typed events below.
See packages/messaging/authsocket/src/SocketServerTransport.ts.
Server receives an AuthMessage frame from the client during BRC-103 handshake.
Available only on servers:
Accepts the following message:
BRC-103 auth frame (both directions — client and server).
BRC-103 auth envelope as defined in @bsv/sdk. Carried on the
low-level authMessage Socket.IO event. Not an application-level event.
{
"messageType": "initialRequest",
"version": "string",
"identityKey": "string",
"nonce": "string",
"yourNonce": "string",
"initialNonce": "string",
"payload": [
0
],
"signature": [
0
],
"requestedCertificates": {}
}
Low-level Socket.IO event used by SocketServerTransport to carry
BRC-103 AuthMessage frames. This event is NOT an application event;
it is emitted and received transparently by the Peer class from
@bsv/sdk. Application developers do not interact with this channel
directly — they use the typed events below.
See packages/messaging/authsocket/src/SocketServerTransport.ts.
Server sends an AuthMessage frame to the client during BRC-103 handshake.
Available only on servers:
Accepts the following message:
BRC-103 auth frame (both directions — client and server).
BRC-103 auth envelope as defined in @bsv/sdk. Carried on the
low-level authMessage Socket.IO event. Not an application-level event.
{
"messageType": "initialRequest",
"version": "string",
"identityKey": "string",
"nonce": "string",
"yourNonce": "string",
"initialNonce": "string",
"payload": [
0
],
"signature": [
0
],
"requestedCertificates": {}
}
Fallback authentication event. The client emits this when its identity
key was not included in the Socket.IO handshake. The server validates
the key, updates its in-memory authenticatedSockets map, and emits
authenticationSuccess or authenticationFailed in response.
Server receives the client's identity key on the 'authenticated' event.
Available only on servers:
Accepts the following message:
Client sends its identity key for post-connection auth.
Sent by the client on the authenticated event when the identity key
was not available at connection time (fallback path). The server validates
the key and responds with authenticationSuccess or authenticationFailed.
{
"identityKey": "string"
}
Emitted by the server after successful identity key validation.
Server confirms successful identity key validation.
Available only on servers:
Accepts the following message:
{
"status": "success"
}
Emitted by the server when identity key validation fails.
Server rejects an invalid identity key.
Available only on servers:
Accepts the following message:
{
"reason": "string"
}
Client requests to subscribe to a room. Only authenticated sockets may
join rooms. The server responds with joinedRoom on success or
joinFailed on error.
Room ID convention: <recipientIdentityKey>-<messageBoxType>.
Server receives a room join request.
Available only on servers:
Accepts the following message:
Room ID string to join.
The room ID string sent by the client on the joinRoom event.
Room IDs use the convention <recipientKey>-<messageBoxType>.
Example: 028d37b9...-payment_inbox.
string
Server confirms the client has joined the specified room.
Server confirms room join.
Available only on servers:
Accepts the following message:
{
"roomId": "string"
}
Emitted when joinRoom fails (unauthenticated or invalid roomId).
Server signals room join failure.
Available only on servers:
Accepts the following message:
{
"reason": "string"
}
Client requests to leave a room.
Server receives a room leave request.
Available only on servers:
Accepts the following message:
Room ID string to leave.
The room ID string sent by the client on the leaveRoom event.
string
Server confirms the client has left the room.
Server confirms room leave.
Available only on servers:
Accepts the following message:
{
"roomId": "string"
}
Emitted when leaveRoom fails.
Server signals room leave failure.
Available only on servers:
Accepts the following message:
{
"reason": "string"
}
Client sends a message to a recipient via WebSocket. The server:
roomId and message.sendMessageAck-{roomId} back to the sender.sendMessage-{roomId} to all connections in the room.Server receives a message from the client to deliver to a recipient.
Available only on servers:
Accepts the following message:
Payload for the client-to-server sendMessage event.
{
"roomId": "string",
"message": {
"messageId": "string",
"recipient": "string",
"body": "string"
}
}
Per-room acknowledgement emitted to the sender only after the message
is stored. The event name is sendMessageAck-<roomId> where roomId
matches the value in the originating sendMessage payload.
Server acknowledges delivery of a message to the sender.
Available only on servers:
The room ID from the originating sendMessage request.
Accepts the following message:
Acknowledgement emitted by the server on sendMessageAck-{roomId} after
a successful sendMessage. Note: the event name is dynamic and includes
the room ID used in the originating request.
{
"status": "success",
"messageId": "string"
}
Broadcast emitted to all connections subscribed to roomId after a
successful sendMessage. The event name is sendMessage-<roomId>.
Server broadcasts a new message to all room subscribers.
Available only on servers:
The target room ID.
Accepts the following message:
Broadcast emitted by the server on sendMessage-{roomId} to all
connections in the room (including the sender). Note: the event name
is dynamic.
{
"sender": "string",
"messageId": "string",
"body": "string"
}
Emitted to the sender when sendMessage processing fails.
Server signals message delivery failure.
Available only on servers:
Accepts the following message:
{
"reason": "string"
}
Emitted to unauthenticated sockets that attempt to send a message (same event name reused from older payment-gate logic).
Server signals auth/payment gate rejection.
Available only on servers:
Accepts the following message:
{
"reason": "string"
}
Standard Socket.IO disconnect event. The server removes the socket from
the authenticatedSockets map and the peers map in AuthSocketServer.
Client disconnects; server cleans up in-memory state.
Available only on servers:
Accepts the following message:
The Socket.IO disconnect reason string (e.g. transport close,
server namespace disconnect).
string
Compressed secp256k1 public key, 66 hex characters.
BRC-103 auth envelope as defined in @bsv/sdk. Carried on the
low-level authMessage Socket.IO event. Not an application-level event.
Application-level wrapper JSON-encoded inside the BRC-103 general
message payload. The SocketServerTransport encodes/decodes this
transparently; application code only sees eventName and data.
Sent by the client on the authenticated event when the identity key
was not available at connection time (fallback path). The server validates
the key and responds with authenticationSuccess or authenticationFailed.
The room ID string sent by the client on the joinRoom event.
Room IDs use the convention <recipientKey>-<messageBoxType>.
Example: 028d37b9...-payment_inbox.
The room ID string sent by the client on the leaveRoom event.
Payload for the client-to-server sendMessage event.
Acknowledgement emitted by the server on sendMessageAck-{roomId} after
a successful sendMessage. Note: the event name is dynamic and includes
the room ID used in the originating request.
Broadcast emitted by the server on sendMessage-{roomId} to all
connections in the room (including the sender). Note: the event name
is dynamic.
The Socket.IO disconnect reason string (e.g. transport close,
server namespace disconnect).