authsocket.md

id	pkg-authsocket
title	@bsv/authsocket
kind	package
domain	messaging
version	2.1.11
source_repo	bsv-blockchain/ts-stack
last_updated	2026-08-27
last_verified	2026-08-27
review_cadence_days	30
npm	https://www.npmjs.com/package/@bsv/authsocket
repo	https://github.com/bsv-blockchain/ts-stack/tree/main/packages/messaging/authsocket
status	stable
tags	messaging websocket brc-31 auth

@bsv/authsocket

This source candidate declares SDK peer ^2.4.1 || ^3.0.0 || ^4.0.1. SDK3 remains a coordinated proposal; see the qualification and migration limits before adopting it.

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)

The connection callback runs only after identity proof and completes before any first or concurrently received application event is dispatched. Until every connection callback finishes, the peer is excluded from broadcasts and identity-targeted delivery. A failed callback therefore cannot leave queued messages authorized.

requestedCertificates is only the legacy v0.1 SDK allowlist. It cannot express complete application fulfillment semantics, and this wrapper does not expose the evidence to the connection callback. Do not infer certificate-based authorization from configuring the option; authorize the verified identity independently or use an integration with an explicit evidence callback.

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 — SDK allowlist validation during handshake; not an application authorization verdict
• 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
6. Event bodies are strict JSON — ambiguous values and serialization hooks are rejected before signing

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

The SDK4 peer alternative now requires @bsv/sdk ^4.0.1 for the numeric wallet result and legacy wire hotfix. Existing SDK2/3 alternatives and lower bounds remain unchanged. No wire or data migration is required.