Mutually Authenticated Web Socket (Server-side)
npm install @bsv/authsocketThis repository provides a drop-in server-side solution for Socket.IO that enforces BRC-103 mutual authentication on all connected clients.
- Each client message is signed using BRC-103 message format.
- The server verifies each message upon receipt.
- The server also signs its outbound messages, so clients can verify authenticity.
It pairs seamlessly with the authsocket-client library, which handles the client side of this handshake. However, if you are building your own client logic, you only need to ensure it also speaks BRC-103 and can sign/verify messages accordingly.
1. Install the package (and its dependencies):
``bash`
npm install
2. Ensure you have a BRC-103-compatible implementation (for instance from @bsv/sdk or your own custom code) that can sign and verify messages.
Below is a minimal Express + HTTP + Socket.IO + authsocket server. You can adapt it to your own setup (e.g. Fastify, Koa, etc.) since only the raw http.Server is needed for Socket.IO.
`ts
import express from 'express'
import http from 'http'
import { AuthSocketServer } from '@bsv/authsocket'
import { ProtoWallet } from '@bsv/sdk' // your BRC-103 compatible wallet
const app = express()
const server = http.createServer(app)
const port = 3000
// Example: create or load your BRC-103 wallet
const serverWallet = new ProtoWallet('my-private-key-hex')
// Wrap your HTTP server with AuthSocketServer
// which internally wraps the Socket.IO server.
const io = new AuthSocketServer(server, {
wallet: serverWallet,
cors: {
origin: '*'
}
})
// Use it like standard Socket.IO
io.on('connection', (socket) => {
console.log('New Authenticated Connection -> socket ID:', socket.id)
// Listen for chat messages
socket.on('chatMessage', (msg) => {
console.log('Received message from client:', msg)
// Reply to the client
socket.emit('chatMessage', { from: socket.id, text: 'Hello from server!' })
})
socket.on('disconnect', () => {
console.log(Socket ${socket.id} disconnected)
})
})
server.listen(port, () => {
console.log(Server listening on port ${port})`
})
1. Create an AuthSocketServer with the wallet option. 'connection'
2. On , you receive an AuthSocket instance that works like a normal Socket.IO socket: socket.on(...), socket.emit(...), etc.
3. All messages are automatically signed and verified under the hood.
- On each new connection, AuthSocketServer sets up a BRC-103 Peer with a corresponding transport (SocketServerTransport).'authMessage'
- Incoming messages on a special channel are processed for authenticity and re-dispatched as your normal 'chatMessage' (or any other event name).
- Outgoing messages from your code pass through the same Peer to be signed before being sent to the client.
- AuthSocketServer:
- Internally wraps a normal Socket.IO server.
- On each new client connection, it:
1. Instantiates a SocketServerTransport.Peer
2. Creates a new BRC-103 for that connection.AuthSocket
3. Wraps the Socket.IO socket in an for your convenience.socket.id
- Maintains a mapping of connected sockets by with their associated Peer.
- AuthSocket:
- A thin wrapper that provides on(eventName, callback) and emit(eventName, data) (just like a normal Socket.IO socket).Peer
- Internally, it uses the BRC-103 to sign outbound messages and verify inbound ones.
interface for server-side usage.
- Receives messages via socket.on('authMessage', ...) from the Socket.IO layer.
- Passes them to the Peer for handshake steps (signature verification, certificate exchange, etc.).
- Sends BRC-103 messages back to the client via socket.emit('authMessage', ...)`.See LICENSE.txt.