@bsv/sdk/dist/types/src/auth/Peer.d.ts

BSV Blockchain Software Development Kit

import { SessionManager } from './SessionManager.js';
import { PeerSession, RequestedCertificateSet, Transport } from './types.js';
import { VerifiableCertificate } from './certificates/VerifiableCertificate.js';
import { 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;
    /**
     * 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);
    /**
     * 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;
    /**
     * 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;
}
//# sourceMappingURL=Peer.d.ts.map