@bsv/authsocket-client

AuthSocket (client-side)

Overview

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

• Works seamlessly with a BRC-103-compatible server (e.g. authsocket) or any custom server that can verify BRC-103 messages.
• Minimal changes compared to normal socket.io-client usage.

Installation

• Install the package (and dependencies):

  npm install
  

• Have a BRC-103-compatible Wallet (e.g., from @bsv/sdk or your own).

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
})

// 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')
})

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

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.

AuthSocketClient

• A function that returns a proxy-like client socket.
• Inside, it:
  • Creates a real io(url, managerOptions) from socket.io-client.
  • Attaches a SocketClientTransport.
  • Creates a Peer with your wallet.
  • 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.