AuthSocket (client-side)

Overview

This package provides a drop-in client-side solution for Socket.IO that signs outbound messages and verifies inbound messages using BRC-103.

• Works with @bsv/authsocket or any BRC-103-compatible server.
• Minimal changes compared to normal socket.io-client usage.

Installation

Install the client and its required SDK peer:

npm install @bsv/authsocket-client @bsv/sdk

Provide a BRC-103-compatible Wallet, such as one from @bsv/sdk.

Usage

Below is a minimal client code that wraps socket.io-client:

import { AuthSocketClient } from '@bsv/authsocket-client'
import { ProtoWallet } from '@bsv/sdk' // your BRC-103-compatible wallet

// Create or load your local BRC-103 wallet
const clientWallet = new ProtoWallet('client-private-key-hex')

// Wrap the normal Socket.IO client with AuthSocketClient
const socket = AuthSocketClient('http://localhost:3000', {
  wallet: clientWallet,
  onError: (error, context) => {
    // Context identifies the phase and event without copying the remote payload.
    console.error(context.phase, context.eventName, error)
  }
})

// Standard Socket.IO usage
socket.on('connect', () => {
  console.log('Connected to server. Socket ID:', socket.id)

  // Emit a sample message
  socket.emit('chatMessage', {
    text: 'Hello from client!'
  })
})

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

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

1. Use AuthSocketClient(serverUrl, options) to create a BRC-103-secured socket client.
2. Interact with .on(...), .emit(...) as normal.
3. Behind the scenes, each message is signed with your client wallet key and verified by the server. Inbound messages are also verified.

Authenticated event data preserves arbitrary JSON exactly, including plain numeric-key objects under names such as data, payload, transaction, and tx. Real Uint8Array values are serialized as portable number arrays. Code that owns a typed payment or wallet protocol may recover a historical numeric-key byte object at that protocol's explicit byte field after receipt.

Failure isolation and resource limits

Authentication frames and application callbacks are contained inside the client connection. If a server sends a frame that fails BRC-103 processing, or an event callback throws or rejects, the client disconnects without creating an unhandled promise rejection. The optional onError(error, context) hook is also isolated if it throws or rejects, and its context does not include remote payloads or wallet material.

The client processes at most 32 authentication messages concurrently by default. Set maxPendingAuthMessages to a positive safe integer to choose a different bound; a server that exceeds it is disconnected.

How It Works (Briefly)

• AuthSocketClient creates an internal BRC-103 Peer that handles:
  • Generating ephemeral nonces and signatures for each outbound message.
  • Verifying inbound messages from the server using the server’s public key.
• A special 'authMessage' channel is used for the underlying BRC-103 handshake. You only interact with standard Socket.IO event names (like 'chatMessage'), as AuthSocketClient automatically re-dispatches them.

Detailed Explanations

SocketClientTransport

• Implements the BRC-103 Transport interface on the client side.
• Relies on the underlying socket.io-client for raw message passing via the 'authMessage' channel.
• The BRC-103 Peer calls this transport to send and receive raw BRC-103 frames.
• Rejected or synchronous authentication failures are contained before they can become unhandled rejections.

AuthSocketClient

• A function that returns a proxy-like client socket.
• Inside, it:
  1. Creates a real io(url, managerOptions) from socket.io-client.
  2. Attaches a SocketClientTransport.
  3. Creates a Peer with your wallet.
  4. Provides the final object with .on(eventName, callback) and .emit(eventName, data) methods.

Note: If you want to see a full end-to-end example, combine the server code from the authsocket README with the client code from the authsocket-client README, then run both. You should see messages securely exchanged and logs showing mutual authentication in action.

License

See LICENSE.txt.

Development and distribution

The npm tarball contains browser-targeted ESM and CommonJS entry points, source maps, declarations for both module systems, and a UMD build. Pull requests and releases should run:

pnpm format:check
pnpm lint
pnpm typecheck
pnpm test:coverage
pnpm build
pnpm pack:check
pnpm test:browser

pack:check validates the exact npm tarball with publint, strict ESM and CommonJS type resolution, and clean consumer installations. test:browser verifies the packed package with Vite, esbuild, and the UMD artifact and enforces the repository's compressed-size budgets. The package uses the Open BSV License Version 6; the repository license controls ensure the manifest, included license, and packed artifact remain in sync.