@bsv/sdk
Version:
BSV Blockchain Software Development Kit
200 lines • 10.1 kB
TypeScript
import { SessionManager } from './SessionManager.js';
import { PeerSession, RequestedCertificateSet, Transport } from './types.js';
import { VerifiableCertificate } from './certificates/VerifiableCertificate.js';
import { OriginatorDomainNameStringUnder250Bytes, WalletInterface } from '../wallet/Wallet.interfaces.js';
/**
* Represents a peer capable of performing mutual authentication.
* Manages sessions, handles authentication handshakes, certificate requests and responses,
* and sending and receiving general messages over a transport layer.
*
* This version supports multiple concurrent sessions per peer identityKey.
*/
export declare class Peer {
sessionManager: SessionManager;
private readonly transport;
private readonly wallet;
certificatesToRequest: RequestedCertificateSet;
private readonly onGeneralMessageReceivedCallbacks;
private readonly onCertificatesReceivedCallbacks;
private readonly onCertificateRequestReceivedCallbacks;
private readonly onInitialResponseReceivedCallbacks;
private callbackIdCounter;
private readonly autoPersistLastSession;
private lastInteractedWithPeer;
private readonly originator?;
private identityPublicKey?;
/**
* Creates a new Peer instance
*
* @param {WalletInterface} wallet - The wallet instance used for cryptographic operations.
* @param {Transport} transport - The transport mechanism used for sending and receiving messages.
* @param {RequestedCertificateSet} [certificatesToRequest] - Optional set of certificates to request from a peer during the initial handshake.
* @param {SessionManager} [sessionManager] - Optional SessionManager to be used for managing peer sessions.
* @param {boolean} [autoPersistLastSession] - Whether to auto-persist the session with the last-interacted-with peer. Defaults to true.
*/
constructor(wallet: WalletInterface, transport: Transport, certificatesToRequest?: RequestedCertificateSet, sessionManager?: SessionManager, autoPersistLastSession?: boolean, originator?: OriginatorDomainNameStringUnder250Bytes);
/**
* Sends a general message to a peer, and initiates a handshake if necessary.
*
* @param {number[]} message - The message payload to send.
* @param {string} [identityKey] - The identity public key of the peer. If not provided, uses lastInteractedWithPeer (if any).
* @param {number} [maxWaitTime] - optional max wait time in ms
* @returns {Promise<void>}
* @throws Will throw an error if the message fails to send.
*/
toPeer(message: number[], identityKey?: string, maxWaitTime?: number): Promise<void>;
/**
* Sends a request for certificates to a peer.
* This method allows a peer to dynamically request specific certificates after
* an initial handshake or message has been exchanged.
*
* @param {RequestedCertificateSet} certificatesToRequest - Specifies the certifiers and types of certificates required from the peer.
* @param {string} [identityKey] - The identity public key of the peer. If not provided, the current or last session identity is used.
* @param {number} [maxWaitTime=10000] - Maximum time in milliseconds to wait for the peer session to be authenticated.
* @returns {Promise<void>} Resolves if the certificate request message is successfully sent.
* @throws Will throw an error if the peer session is not authenticated or if sending the request fails.
*/
requestCertificates(certificatesToRequest: RequestedCertificateSet, identityKey?: string, maxWaitTime?: number): Promise<void>;
/**
* Retrieves an authenticated session for a given peer identity. If no session exists
* or the session is not authenticated, initiates a handshake to create or authenticate the session.
*
* - If `identityKey` is provided, we look up any existing session for that identity key.
* - If none is found or not authenticated, we do a new handshake.
* - If `identityKey` is not provided, but we have a `lastInteractedWithPeer`, we try that key.
*
* @param {string} [identityKey] - The identity public key of the peer.
* @param {number} [maxWaitTime] - The maximum time in milliseconds to wait for the handshake.
* @returns {Promise<PeerSession>} - A promise that resolves with an authenticated `PeerSession`.
*/
getAuthenticatedSession(identityKey?: string, maxWaitTime?: number): Promise<PeerSession>;
/**
* Registers a callback to listen for general messages from peers.
*
* @param {(senderPublicKey: string, payload: number[]) => void} callback - The function to call when a general message is received.
* @returns {number} The ID of the callback listener.
*/
listenForGeneralMessages(callback: (senderPublicKey: string, payload: number[]) => void): number;
/**
* Removes a general message listener.
*
* @param {number} callbackID - The ID of the callback to remove.
*/
stopListeningForGeneralMessages(callbackID: number): void;
/**
* Registers a callback to listen for certificates received from peers.
*
* @param {(senderPublicKey: string, certs: VerifiableCertificate[]) => void} callback - The function to call when certificates are received.
* @returns {number} The ID of the callback listener.
*/
listenForCertificatesReceived(callback: (senderPublicKey: string, certs: VerifiableCertificate[]) => void): number;
/**
* Cancels and unsubscribes a certificatesReceived listener.
*
* @param {number} callbackID - The ID of the certificates received callback to cancel.
*/
stopListeningForCertificatesReceived(callbackID: number): void;
/**
* Registers a callback to listen for certificates requested from peers.
*
* @param {(requestedCertificates: RequestedCertificateSet) => void} callback - The function to call when a certificate request is received
* @returns {number} The ID of the callback listener.
*/
listenForCertificatesRequested(callback: (senderPublicKey: string, requestedCertificates: RequestedCertificateSet) => void): number;
/**
* Cancels and unsubscribes a certificatesRequested listener.
*
* @param {number} callbackID - The ID of the requested certificates callback to cancel.
*/
stopListeningForCertificatesRequested(callbackID: number): void;
/**
* Initiates the mutual authentication handshake with a peer.
*
* @private
* @param {string} [identityKey] - The identity public key of the peer.
* @param {number} [maxWaitTime=10000] - how long to wait for handshake
* @returns {Promise<string>} A promise that resolves to the session nonce.
*/
private initiateHandshake;
/**
* Waits for the initial response from the peer after sending an initial handshake request message.
*
* @param {string} sessionNonce - The session nonce created in the initial request.
* @returns {Promise<string>} A promise that resolves with the session nonce when the initial response is received.
*/
private waitForInitialResponse;
/**
* Adds a listener for an initial response message matching a specific initial nonce.
*
* @private
* @param {string} sessionNonce - The session nonce to match.
* @param {(sessionNonce: string) => void} callback - The callback to invoke when the initial response is received.
* @returns {number} The ID of the callback listener.
*/
private listenForInitialResponse;
/**
* Removes a listener for initial responses.
*
* @private
* @param {number} callbackID - The ID of the callback to remove.
*/
private stopListeningForInitialResponses;
private propagateTransportError;
/**
* Handles incoming messages from the transport.
*
* @param {AuthMessage} message - The incoming message to process.
* @returns {Promise<void>}
*/
private handleIncomingMessage;
/**
* Processes an initial request message from a peer.
*
* @param {AuthMessage} message - The incoming initial request message.
*/
private processInitialRequest;
/**
* Processes an initial response message from a peer.
*
* @private
* @param {AuthMessage} message - The incoming initial response message.
* @throws Will throw an error if nonce or signature verification fails.
*/
private processInitialResponse;
/**
* Processes an incoming certificate request message from a peer.
* Verifies nonce/signature and then possibly sends a certificateResponse.
*
* @param {AuthMessage} message - The certificate request message received from the peer.
* @throws {Error} if nonce or signature is invalid.
*/
private processCertificateRequest;
/**
* Sends a certificate response message containing the specified certificates to a peer.
*
* @param {string} verifierIdentityKey - The identity key of the peer requesting the certificates.
* @param {VerifiableCertificate[]} certificates - The list of certificates to include in the response.
* @throws Will throw an error if the transport fails to send the message.
*/
sendCertificateResponse(verifierIdentityKey: string, certificates: VerifiableCertificate[]): Promise<void>;
/**
* Processes a certificate response message from a peer.
*
* @private
* @param {AuthMessage} message - The incoming certificate response message.
* @throws Will throw an error if nonce verification or signature verification fails.
*/
private processCertificateResponse;
/**
* Processes a general message from a peer.
*
* @private
* @param {AuthMessage} message - The incoming general message.
* @throws Will throw an error if nonce or signature verification fails.
*/
private processGeneralMessage;
private getIdentityPublicKey;
private static utf8ToBytes;
private static base64ToBytes;
}
//# sourceMappingURL=Peer.d.ts.map