Skip to content

API.md

Latest commit

 

History

History
409 lines (279 loc) · 11.9 KB

API.md

File metadata and controls

409 lines (279 loc) · 11.9 KB
Raw

API

Links: API, Interfaces, Classes, Functions, Types, Variables

Interfaces
AuthSocketErrorContext
AuthSocketServerOptions
SocketServerTransportOptions

Links: API, Interfaces, Classes, Functions, Types, Variables

Interface: AuthSocketErrorContext

export interface AuthSocketErrorContext {
    phase: AuthSocketErrorPhase;
    socketId?: string;
    eventName?: string;
}

See also: AuthSocketErrorPhase

Links: API, Interfaces, Classes, Functions, Types, Variables

Interface: AuthSocketServerOptions

export interface AuthSocketServerOptions extends Partial<ServerOptions> {
    wallet: WalletInterface;
    requestedCertificates?: RequestedCertificateSet;
    sessionManager?: SessionManager | AsyncSessionManager;
    maxPendingAuthMessages?: number;
    maxEventPayloadBytes?: number;
    onError?: AuthSocketErrorHandler;
}

See also: AuthSocketErrorHandler

Interface AuthSocketServerOptions Details

Property maxEventPayloadBytes

Maximum encoded bytes in one authenticated application event. Defaults to 1 MiB.

maxEventPayloadBytes?: number

Property maxPendingAuthMessages

Maximum authentication messages processed concurrently by each socket. Defaults to 32.

maxPendingAuthMessages?: number

Property onError

Receives contained transport and application errors without exposing remote payloads.

onError?: AuthSocketErrorHandler

See also: AuthSocketErrorHandler

Property requestedCertificates

SDK v0.1 certificate allowlist; not an application authorization verdict.

requestedCertificates?: RequestedCertificateSet

Property sessionManager

Optional shared BRC-103 session store. Use an AsyncSessionManager backed by a shared database when more than one server replica handles connections.

sessionManager?: SessionManager | AsyncSessionManager

Links: API, Interfaces, Classes, Functions, Types, Variables

Interface: SocketServerTransportOptions

export interface SocketServerTransportOptions {
    maxPendingMessages?: number;
    onError?: (error: unknown) => void | Promise<void>;
}
Interface SocketServerTransportOptions Details

Property maxPendingMessages

Maximum authentication messages that may be processed concurrently per socket.

maxPendingMessages?: number

Property onError

Receives contained authentication failures. The hook is never allowed to throw outward.

onError?: (error: unknown) => void | Promise<void>

Links: API, Interfaces, Classes, Functions, Types, Variables

Classes
AuthSocket
AuthSocketServer
SocketServerTransport

Links: API, Interfaces, Classes, Functions, Types, Variables

Class: AuthSocket

A wrapper around a real IoSocket used by a server that performs BRC-103 signing and verification via the Peer class.

export class AuthSocket {
    constructor(public readonly ioSocket: IoSocket, private readonly peer: Peer, private readonly onIdentityKeyDiscovered: (socketId: string, identityKey: string) => boolean | void | Promise<boolean | void>, private readonly onError: AuthSocketErrorHandler = () => { }, private readonly maxEventPayloadBytes: number = DEFAULT_MAX_EVENT_PAYLOAD_BYTES)
    public on(eventName: string, callback: (data: any) => void | Promise<void>)
    public async emit(eventName: string, data: any): Promise<void>
    get id(): string
    get identityKey(): string | undefined
}

See also: AuthSocketErrorHandler, DEFAULT_MAX_EVENT_PAYLOAD_BYTES

Class AuthSocket Details

Method emit

Emulate socket.emit(eventName, data). We'll sign a BRC-103 general message via Peer, embedding the event name & data in the payload.

If we do not yet have the peer's identity key (handshake not done?), the Peer will attempt the handshake. Once known, subsequent calls will pass identityKey to skip the initial handshake.

public async emit(eventName: string, data: any): Promise<void>

Method on

Register a callback for an event name, just like socket.on(...).

public on(eventName: string, callback: (data: any) => void | Promise<void>)

Links: API, Interfaces, Classes, Functions, Types, Variables

Class: AuthSocketServer

A server-side wrapper for Socket.IO that integrates BRC-103 mutual authentication to ensure secure, identity-aware communication between clients and the server.

This class functions as a drop-in replacement for the Server class from Socket.IO, with added support for:

  • Automatic BRC-103 handshake for secure client authentication.
  • Management of authenticated client sessions, avoiding redundant handshakes.
  • Event-based communication through signed and verified BRC-103 messages.

Features:

  • Tracks client connections and their associated Peer and AuthSocket instances.
  • Allows broadcasting messages to all authenticated clients.
  • Provides a seamless API for developers by wrapping Socket.IO functionality.
export class AuthSocketServer {
    constructor(httpServer: HttpServer, private readonly options: AuthSocketServerOptions)
    public on(eventName: "connection", callback: (socket: AuthSocket) => void | Promise<void>): void;
    public on(eventName: string, callback: (data: any) => void | Promise<void>): void;
    public on(eventName: string, callback: (data: any) => void | Promise<void>): void
    public emit(eventName: string, data: any)
    public emitToIdentity(identityKey: string, eventName: string, data: any): number
    public close(): Promise<void>
}

See also: AuthSocket, AuthSocketServerOptions

Class AuthSocketServer Details

Constructor

constructor(httpServer: HttpServer, private readonly options: AuthSocketServerOptions)

See also: AuthSocketServerOptions

Argument Details

  • httpServer
    • The underlying HTTP server
  • options
    • Contains both standard Socket.IO server config and BRC-103 config.

Method close

Stops accepting connections, disconnects active sockets, and closes the attached HTTP server. Repeated calls share the same shutdown operation.

public close(): Promise<void>

Method emit

Provide a classic pass-through to io.emit(...).

Under the hood, we sign a separate BRC-103 AuthMessage for each authenticated peer. We'll embed eventName + data in the payload.

public emit(eventName: string, data: any)

Method emitToIdentity

Emit only to connections whose cryptographically authenticated peer identity matches the requested identity key.

This is safer than application-level "room" names for private delivery: a client cannot subscribe itself to another identity because the routing decision uses the key discovered by the BRC-103 handshake.

public emitToIdentity(identityKey: string, eventName: string, data: any): number

Returns

the number of authenticated connections selected for delivery

Method on

Register authenticated-connection setup. All callbacks complete before the first or concurrently received application event is dispatched and before the peer becomes eligible for server routing.

public on(eventName: "connection", callback: (socket: AuthSocket) => void | Promise<void>): void

See also: AuthSocket

Links: API, Interfaces, Classes, Functions, Types, Variables

Class: SocketServerTransport

Implements the Transport interface for a specific client socket.

This transport simply relays AuthMessages over 'authMessage' in the underlying Socket.IO connection.

export class SocketServerTransport implements Transport {
    constructor(private readonly socket: IoSocket, options: SocketServerTransportOptions = {})
    async send(message: AuthMessage): Promise<void>
    async onData(callback: (message: AuthMessage) => Promise<void>): Promise<void>
}

See also: SocketServerTransportOptions

Links: API, Interfaces, Classes, Functions, Types, Variables

Functions
decodeAuthSocketEventPayload
encodeAuthSocketEventPayload
parseAuthSocketEventPayload
resolveMaxEventPayloadBytes

Links: API, Interfaces, Classes, Functions, Types, Variables

Function: decodeAuthSocketEventPayload

export function decodeAuthSocketEventPayload(payload: number[]): {
    eventName: string;
    data: any;
}

Links: API, Interfaces, Classes, Functions, Types, Variables

Function: encodeAuthSocketEventPayload

export function encodeAuthSocketEventPayload(eventName: string, data: unknown, maxBytes: number): number[]

Links: API, Interfaces, Classes, Functions, Types, Variables

Function: parseAuthSocketEventPayload

export function parseAuthSocketEventPayload(payload: unknown, maxBytes: number): {
    eventName: string;
    data: unknown;
}

Links: API, Interfaces, Classes, Functions, Types, Variables

Function: resolveMaxEventPayloadBytes

export function resolveMaxEventPayloadBytes(value: number | undefined): number

Links: API, Interfaces, Classes, Functions, Types, Variables

Types
AuthSocketErrorHandler
AuthSocketErrorPhase

Links: API, Interfaces, Classes, Functions, Types, Variables

Type: AuthSocketErrorHandler

export type AuthSocketErrorHandler = (error: unknown, context: AuthSocketErrorContext) => void | Promise<void>

See also: AuthSocketErrorContext

Links: API, Interfaces, Classes, Functions, Types, Variables

Type: AuthSocketErrorPhase

export type AuthSocketErrorPhase = "authentication" | "application" | "connection" | "send"

Links: API, Interfaces, Classes, Functions, Types, Variables

Variables

Variable: DEFAULT_MAX_EVENT_PAYLOAD_BYTES

DEFAULT_MAX_EVENT_PAYLOAD_BYTES = 1024 * 1024

Links: API, Interfaces, Classes, Functions, Types, Variables