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

1. Install the package (and dependencies):

   npm install

2. 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')
})

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.

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:
  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.