@bsv/authsocket-client

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

Client-side BRC-103 mutual authentication wrapper for socket.io-client. Signs all outbound messages and verifies inbound messages using a wallet, enabling authenticated peer-to-peer WebSocket communication.

Install

npm install @bsv/authsocket-client

Quick start

import { AuthSocketClient } from '@bsv/authsocket-client'
import { PrivateKey, ProtoWallet } from '@bsv/sdk'

const clientWallet = new ProtoWallet(
  PrivateKey.fromHex('0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef')
)
const socket = AuthSocketClient('http://localhost:3000', { wallet: clientWallet })

socket.on('connect', () => {
  console.log('Socket.IO transport connected. Socket ID:', socket.id)
  socket.emit('chatMessage', { text: 'Hello from client!' })
})

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

socket.on('disconnect', () => {
  console.log('Disconnected')
})

connect and connected describe the raw Socket.IO transport, not a completed BRC-103 identity proof. Outbound application events complete the handshake before their signed payload is sent, and inbound application callbacks receive only verified general messages. When local behavior requires a known server, set expectedServerIdentityKey and wait for a verified application event.

What it provides

• AuthSocketClient — Wraps socket.io-client with BRC-103 authentication
• Automatic message signing — All outbound messages signed with client wallet key
• Automatic message verification — Inbound messages verified against server's public key
• BRC-103 handshake — Nonce-based challenge-response protocol
• Transparent proxying — User code sees normal Socket.IO API; BRC-103 hidden
• Certificate exchange — Supports verifiable certificates during handshake (optional)
• Standard Socket.IO interface — .on(), .emit(), .id, .connect(), .disconnect()
• Failure isolation — Authentication and callback failures disconnect the affected connection
• Bounded ingress — Authentication concurrency defaults to 32 and is configurable

Common patterns

Basic transport connection and authenticated events

import { AuthSocketClient } from '@bsv/authsocket-client'
import { PrivateKey, ProtoWallet } from '@bsv/sdk'

const wallet = new ProtoWallet(
  PrivateKey.fromHex('0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef')
)
const socket = AuthSocketClient('http://localhost:3000', { wallet })

socket.on('connect', () => {
  console.log('Transport connected; the first emit performs BRC-103 authentication')
  socket.emit('joinRoom', 'general')
})

socket.on('message', data => {
  console.log('Received:', data)
})

With custom manager options

const socket = AuthSocketClient('http://localhost:3000', {
  wallet: myWallet,
  managerOptions: {
    reconnection: true,
    reconnectionDelay: 1000,
    reconnectionDelayMax: 5000,
    reconnectionAttempts: 5
  }
})

Failure reporting and authentication bounds

const socket = AuthSocketClient('http://localhost:3000', {
  wallet,
  maxPendingAuthMessages: 32,
  onError: (error, context) => {
    console.error(context.phase, context.eventName, error)
  }
})

Malformed server authentication traffic and application callback failures are contained before they can become unhandled rejections. The error context does not include remote payloads or wallet material, and an onError handler that throws or rejects is also contained.

Key concepts

• BRC-103 mutual authentication — Nonce-based challenge-response protocol
• Ephemeral nonces — Each outbound message includes fresh nonce + signature
• Signature verification — Inbound messages verified against server's public key
• Session binding — Server nonce proves server identity; client nonce proves client identity
• Certificate exchange — Optional verifiable certificates during handshake
• Transparent proxying — User code interacts with normal Socket.IO API

When to use this

• Connecting to BRC-103 authenticated servers (e.g., @bsv/authsocket)
• Real-time applications requiring cryptographic identity
• Building collaborative tools with verified user authentication
• Live messaging systems with signature-based security
• Games or interactive apps needing peer identity verification

When NOT to use this

• Simple WebSocket clients without authentication — use Socket.IO directly
• REST APIs with request/response auth — use @bsv/auth-express-middleware
• Batch or store-and-forward messaging — use @bsv/message-box-client instead
• One-way data feeds — Server-Sent Events may be simpler

Spec conformance

• BRC-103 (Peer-to-Peer Mutual Authentication): Full handshake, nonce exchange, signature verification, optional certificate exchange
• Uses BRC-103 Peer and Transport abstractions from SDK
• Client transport implements ephemeral nonce generation + signing

Common pitfalls

1. Wallet must be BRC-100 compatible — needs sign() and verify() methods
2. Server must support BRC-103 — use @bsv/authsocket or implement BRC-103 Peer yourself
3. Nonce tracking handled automatically — library auto-generates nonces; don't manually set them
4. Signature verification automatic — inbound messages verified; if verification fails, message is dropped
5. Handshake must complete first — BRC-103 handshake completes before general messages; library handles this
6. connect is transport state — wait for a verified application event before treating an unpinned server as authenticated

Related packages

• @bsv/authsocket — Server-side counterpart; host authenticated WebSocket server
• @bsv/message-box-client — Uses AuthSocketClient for live message delivery
• @bsv/auth-express-middleware — HTTP authentication for REST endpoints

Reference

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