AuthSocket WebSocket Protocol

AuthSocket wraps Socket.IO with BRC-103 mutual authentication. Every WebSocket connection undergoes a cryptographic handshake, then all application-level messages are automatically signed by the server and verified by the client (and vice versa). No shared secrets required—only identity public keys.

Interactive spec

At a glance

What problem this solves

Authenticated real-time messaging over WebSocket. WebSockets lack built-in authentication; clients typically send bearer tokens which are single-factor and session-based. AuthSocket brings BRC-103 mutual authentication to WebSocket: both client and server prove identity via cryptographic signatures, and every message is signed, preventing impersonation and tampering.

Live message push without polling. MessageBox's HTTP interface requires polling. AuthSocket enables server-side push: when a new message arrives, the server emits it immediately to the connected client without waiting for the next poll.

Stateful replay resistance. Each raw WebSocket connection has its own Peer, while a bounded server-wide session manager retains nonce and replay state across reconnects. An initial request is unsigned; identity is proven by the signed handshake follow-up/general flow, and every application message is individually signed and replay-checked.

Protocol overview

Two-phase connection:

Phase 1 — BRC-103 Handshake (over low-level authMessage Socket.IO event)

1. Client → Server socket.emit('authMessage', initialRequest)

   • Client's claimed public key and initial nonce
   • The v0.1 initial request is unsigned

2. Server → Client socket.emit('authMessage', initialResponse)

   • Server's public key
   • Server's nonce (covering client's nonce)
   • Server signature

Phase 2 — Authenticated Application Events

After handshake, client and server exchange high-level events. All messages are wrapped in BRC-103 general type envelope and signed automatically:

• Server → Client: socket.emit('messageReceived', { from, body, timestamp })
• Client → Server: socket.emit('sendMessage', { to, body })
• Any JSON-serializable event; signature transparent to application code

On the server, all concurrently received first-session events wait for the same authenticated-connection activation callback. No event is dispatched and no peer becomes eligible for broadcast/identity routing until it succeeds. On the client, Socket.IO's connect event reports transport state only; server identity is established by the BRC-103 handshake/verified application traffic.

Key types / channels

Standard application events:

• messageReceived(message) — Server pushes message to client
• sendMessage(payload) — Client sends message to server
• joinRoom(roomName) — Client joins subscription room
• leaveRoom(roomName) — Client leaves subscription room
• Any custom event name

Example: Server setup

import http from 'http'
import { AuthSocketServer } from '@bsv/authsocket'
import { ServerWallet } from '@bsv/simple/server'

const server = http.createServer()
const wallet = await ServerWallet.create({
  privateKey: process.env.SERVER_PRIVATE_KEY!,
  network: 'main',
  storageUrl: 'https://store-us-1.bsvb.tech'
})

// 1. Wrap HTTP server with BRC-103 authentication
const io = new AuthSocketServer(server, {
  wallet,
  cors: { origin: '*' }
})

// 2. Listen for authenticated connections
io.on('connection', socket => {
  console.log('Authenticated socket:', socket.id)

  // 3. Handle application events (signature verified automatically)
  socket.on('sendMessage', msg => {
    console.log('Received from:', socket.id, msg)

    // 4. Emit to other clients (server signs automatically)
    io.emit('messageReceived', {
      from: socket.id,
      body: msg.body,
      timestamp: new Date().toISOString()
    })
  })
})

server.listen(3000)

Example: Client subscription

import { MessageBoxClient } from '@bsv/message-box-client'
import { WalletClient } from '@bsv/sdk'

const wallet = new WalletClient('auto', 'example.com')
const msgBox = new MessageBoxClient({ walletClient: wallet })
const recipient = '025706528f0f6894b2ba505007267ccff1133e004452a1f6b72ac716f246216366'

// Automatically handles BRC-103 handshake
await msgBox.listenForLiveMessages({
  messageBox: 'general_inbox',
  onMessage: msg => {
    console.log('Live message:', msg.body)
    // Message signature already verified server-side
  }
})

// Send message (client signs automatically)
await msgBox.sendLiveMessage({
  recipient,
  messageBox: 'general_inbox',
  body: 'Hello, live world!',
  skipEncryption: true
})

Conformance vectors

There is no standalone AuthSocket vector directory in the current conformance corpus. Related portable coverage lives in conformance/vectors/messaging/brc31/authrite-signature.json; AuthSocket-specific behavior is covered by the package tests and the AsyncAPI artifact linked below.

Implementations in ts-stack

Related specs

• BRC-31 Auth — HTTP variant of the same mutual auth protocol
• Message Box HTTP — Polling alternative (HTTP POST)
• BRC-103 — Underlying peer authentication primitives

Spec artifact

authsocket-asyncapi.yaml