@bsv/authsocket

Server-side BRC-103 mutual authentication wrapper for Socket.IO. Enforces cryptographic signing and verification on all WebSocket messages, enabling peer-to-peer identity verification and certificate exchange.

Install

npm install @bsv/authsocket

Quick start

import { AuthSocketServer } from '@bsv/authsocket'
import { PrivateKey, ProtoWallet } from '@bsv/sdk'
import http from 'http'

const server = http.createServer()
const serverWallet = new ProtoWallet(
  PrivateKey.fromHex('0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef')
)
const io = new AuthSocketServer(server, { wallet: serverWallet, cors: { origin: '*' } })

io.on('connection', async socket => {
  console.log('Authenticated socket:', socket.id)

  socket.on('chatMessage', msg => {
    console.log('Verified message:', msg)
  })

  await socket.emit('chatMessage', { from: socket.id, text: 'Hello client' })
})

server.listen(3000)

What it provides

• AuthSocketServer — Wraps HTTP server to add BRC-103 authentication to Socket.IO
• AuthSocket — Socket wrapper with auto-signing and verification on all messages
• BRC-103 handshake — Nonce-based challenge-response mutual authentication
• Session management — Tracks nonces and authentication state per socket
• Certificate exchange — Support for requesting and verifying certificates during handshake
• Message signing — Every message auto-signed with server wallet; every inbound message verified
• Automatic re-dispatch — Special 'authMessage' channel for BRC-103 frames; user code sees normal Socket.IO events
• Graceful lifecycle — Idempotent close() disconnects clients and closes the attached HTTP server
• Failure isolation — Authentication and callback failures disconnect only the offending socket
• Bounded ingress — Per-socket authentication concurrency defaults to 32 and is configurable

Common patterns

Server setup with certificate requests

import { AuthSocketServer } from '@bsv/authsocket'
import { PrivateKey, ProtoWallet } from '@bsv/sdk'

const wallet = new ProtoWallet(PrivateKey.fromHex(privateKeyHex))
const io = new AuthSocketServer(server, {
  wallet,
  cors: { origin: '*' },
  requestedCertificates: {
    certifiers: ['<33-byte-pubkey-hex>'],
    types: {
      'age-verification': ['dateOfBirth', 'country']
    }
  }
})

io.on('connection', async socket => {
  socket.on('message', data => {
    // All messages already verified
  })
  await socket.emit('response', { authenticated: true })
})

Graceful shutdown

process.once('SIGTERM', () => {
  void io.close()
})

close() is idempotent. Socket.IO disconnects active clients before closing the HTTP server supplied to AuthSocketServer.

Failure reporting and authentication bounds

const io = new AuthSocketServer(server, {
  wallet,
  maxPendingAuthMessages: 32,
  onError: (error, context) => {
    console.error(context.phase, context.socketId, error)
  }
})

Authentication, connection, and application callback failures are contained and disconnect only the affected socket. The error context identifies the phase and socket without including remote payloads or wallet material. An onError handler that throws or rejects is also contained.

Receiving authenticated messages

io.on('connection', async socket => {
  // Messages are automatically verified before reaching here
  socket.on('userAction', action => {
    console.log('Verified action from', socket.id, ':', action)
  })

  // Send authenticated response
  await socket.emit('status', { result: 'success' })
})

Key concepts

• BRC-103 mutual authentication — Nonce-based challenge-response with signatures
• Ephemeral sockets — Each Socket.IO connection creates new BRC-103 Peer
• Session management — Tracks nonces and auth state per socket via SessionManager
• Certificate exchange — Optional verifiable certificates during handshake
• Message signing — Outbound messages signed; inbound messages verified automatically
• Special auth channel — 'authMessage' channel for BRC-103 frames; user code sees normal Socket.IO events

When to use this

• Real-time applications requiring cryptographic identity verification
• Peer-to-peer communication with mutual authentication needs
• Applications where you need to verify sender identity without certificates
• Message-oriented services with signature-based security

When NOT to use this

• Simple WebSocket communication without authentication — use Socket.IO directly
• If you need TLS certificate-based security — configure server TLS instead
• REST APIs with request/response auth — use @bsv/auth-express-middleware
• One-way broadcast channels — Server-Sent Events may be simpler

Spec conformance

• BRC-103 (Peer-to-Peer Mutual Authentication): Full handshake, nonce exchange, signature verification
• Uses BRC-103 Peer and Transport abstractions from SDK
• Session manager implements nonce replay protection

Common pitfalls

1. Wallet must be BRC-100 compatible — needs sign() and verify() methods
2. Certificate requests are optional — if you don't request them, handshake is faster
3. No auto-reconnect on server side — client-side library handles reconnection logic
4. Each socket is separate peer — nonce state is per-socket; don't mix them
5. CORS must be set explicitly — Socket.IO requires cors config for browser clients

Related packages

• @bsv/authsocket-client — Client-side counterpart; send messages to this server
• @bsv/auth-express-middleware — HTTP authentication for REST endpoints
• @bsv/message-box-client — Store-and-forward messaging using AuthSocketClient internally

Reference

• API reference (TypeDoc)
• Source on GitHub
• npm