ts-sdk

API

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

Interfaces

AuthMessage
PeerSession
RequestedCertificateSet
RequestedCertificateTypeIDAndFieldList
Transport

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

---

Interface: AuthMessage

export interface AuthMessage {
    version: string;
    messageType: "initialRequest" | "initialResponse" | "certificateRequest" | "certificateResponse" | "general";
    identityKey: string;
    nonce?: string;
    initialNonce?: string;
    yourNonce?: string;
    certificates?: VerifiableCertificate[];
    requestedCertificates?: RequestedCertificateSet;
    payload?: number[];
    signature?: number[];
}

See also: RequestedCertificateSet, VerifiableCertificate

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

---

Interface: PeerSession

export interface PeerSession {
    isAuthenticated: boolean;
    sessionNonce?: string;
    peerNonce?: string;
    peerIdentityKey?: string;
}

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

---

Interface: RequestedCertificateSet

export interface RequestedCertificateSet {
    certifiers: string[];
    types: RequestedCertificateTypeIDAndFieldList;
}

See also: RequestedCertificateTypeIDAndFieldList

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

---

Interface: RequestedCertificateTypeIDAndFieldList

export interface RequestedCertificateTypeIDAndFieldList {
    [certificateTypeID: string]: string[];
}

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

---

Interface: Transport

export interface Transport {
    send: (message: AuthMessage) => Promise<void>;
    onData: (callback: (message: AuthMessage) => Promise<void>) => Promise<void>;
}

See also: AuthMessage

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

---

Classes

AuthFetch
Certificate
CompletedProtoWallet
MasterCertificate
Peer
SessionManager
SimplifiedFetchTransport
VerifiableCertificate

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

---

Class: AuthFetch

AuthFetch provides a lightweight fetch client for interacting with servers over a simplified HTTP transport mechanism. It integrates session management, peer communication, and certificate handling to enable secure and mutually-authenticated requests.

Additionally, it automatically handles 402 Payment Required responses by creating and sending BSV payment transactions when necessary.

export class AuthFetch {
    peers: Record<string, AuthPeer> = {};
    constructor(wallet: WalletInterface, requestedCertificates?: RequestedCertificateSet, sessionManager?: SessionManager) 
    async fetch(url: string, config: SimplifiedFetchRequestOptions = {}): Promise<Response> 
    async sendCertificateRequest(baseUrl: string, certificatesToRequest: RequestedCertificateSet): Promise<VerifiableCertificate[]> 
    public consumeReceivedCertificates(): VerifiableCertificate[] 
}

See also: RequestedCertificateSet, SessionManager, VerifiableCertificate, WalletInterface

Constructor

Constructs a new AuthFetch instance.

constructor(wallet: WalletInterface, requestedCertificates?: RequestedCertificateSet, sessionManager?: SessionManager) 

See also: RequestedCertificateSet, SessionManager, WalletInterface

Argument Details

• wallet
  • The wallet instance for signing and authentication.
• requestedCertificates
  • Optional set of certificates to request from peers.

Method consumeReceivedCertificates

Return any certificates we’ve collected thus far, then clear them out.

public consumeReceivedCertificates(): VerifiableCertificate[] 

See also: VerifiableCertificate

Method fetch

Mutually authenticates and sends a HTTP request to a server.

1) Attempt the request. 2) If 402 Payment Required, automatically create and send payment. 3) Return the final response.

async fetch(url: string, config: SimplifiedFetchRequestOptions = {}): Promise<Response> 

Returns

A promise that resolves with the server’s response, structured as a Response-like object.

Argument Details

• url
  • The URL to send the request to.
• config
  • Configuration options for the request, including method, headers, and body.

Throws

Will throw an error if unsupported headers are used or other validation fails.

Method sendCertificateRequest

Request Certificates from a Peer

async sendCertificateRequest(baseUrl: string, certificatesToRequest: RequestedCertificateSet): Promise<VerifiableCertificate[]> 

See also: RequestedCertificateSet, VerifiableCertificate

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

---

Class: Certificate

Represents an Identity Certificate as per the Wallet interface specifications.

This class provides methods to serialize and deserialize certificates, as well as signing and verifying the certificate’s signature.

export default class Certificate {
    type: Base64String;
    serialNumber: Base64String;
    subject: PubKeyHex;
    certifier: PubKeyHex;
    revocationOutpoint: OutpointString;
    fields: Record<CertificateFieldNameUnder50Bytes, Base64String>;
    signature?: HexString;
    constructor(type: Base64String, serialNumber: Base64String, subject: PubKeyHex, certifier: PubKeyHex, revocationOutpoint: OutpointString, fields: Record<CertificateFieldNameUnder50Bytes, string>, signature?: HexString) 
    toBinary(includeSignature: boolean = true): number[] 
    static fromBinary(bin: number[]): Certificate 
    async verify(): Promise<boolean> 
    async sign(certifierWallet: ProtoWallet): Promise<void> 
    static getCertificateFieldEncryptionDetails(fieldName: string, serialNumber?: string): {
        protocolID: WalletProtocol;
        keyID: string;
    } 
}

See also: Base64String, CertificateFieldNameUnder50Bytes, HexString, OutpointString, ProtoWallet, PubKeyHex, WalletProtocol, sign, verify

Constructor

Constructs a new Certificate.

constructor(type: Base64String, serialNumber: Base64String, subject: PubKeyHex, certifier: PubKeyHex, revocationOutpoint: OutpointString, fields: Record<CertificateFieldNameUnder50Bytes, string>, signature?: HexString) 

See also: Base64String, CertificateFieldNameUnder50Bytes, HexString, OutpointString, PubKeyHex

Argument Details

• type
  • Type identifier for the certificate, base64 encoded string, 32 bytes.
• serialNumber
  • Unique serial number of the certificate, base64 encoded string, 32 bytes.
• subject
  • The public key belonging to the certificate’s subject, compressed public key hex string.
• certifier
  • Public key of the certifier who issued the certificate, compressed public key hex string.
• revocationOutpoint
  • The outpoint used to confirm that the certificate has not been revoked (TXID.OutputIndex), as a string.
• fields
  • All the fields present in the certificate.
• signature
  • Certificate signature by the certifier’s private key, DER encoded hex string.

Property certifier

Public key of the certifier who issued the certificate, compressed public key hex string.

certifier: PubKeyHex

See also: PubKeyHex

Property fields

All the fields present in the certificate, with field names as keys and encrypted field values as Base64 strings.

fields: Record<CertificateFieldNameUnder50Bytes, Base64String>

See also: Base64String, CertificateFieldNameUnder50Bytes

Property revocationOutpoint

The outpoint used to confirm that the certificate has not been revoked (TXID.OutputIndex), as a string.

revocationOutpoint: OutpointString

See also: OutpointString

Property serialNumber

Unique serial number of the certificate, base64 encoded string, 32 bytes.

serialNumber: Base64String

See also: Base64String

Property signature

Certificate signature by the certifier’s private key, DER encoded hex string.

signature?: HexString

See also: HexString

Property subject

The public key belonging to the certificate’s subject, compressed public key hex string.

subject: PubKeyHex

See also: PubKeyHex

Property type

Type identifier for the certificate, base64 encoded string, 32 bytes.

type: Base64String

See also: Base64String

Method fromBinary

Deserializes a certificate from binary format.

static fromBinary(bin: number[]): Certificate 

See also: Certificate

Returns

• The deserialized Certificate object.

Argument Details

• bin
  • The binary data representing the certificate.

Method getCertificateFieldEncryptionDetails

Helper function which retrieves the protocol ID and key ID for certificate field encryption.

static getCertificateFieldEncryptionDetails(fieldName: string, serialNumber?: string): {
    protocolID: WalletProtocol;
    keyID: string;
} 

See also: WalletProtocol

Returns

An object containing the protocol ID and key ID:

• protocolID (WalletProtocol): The protocol ID for certificate field encryption.
• keyID (string): A unique key identifier derived from the serial number and field name.

Argument Details

• serialNumber
  • The serial number of the certificate.
• fieldName
  • The name of the field within the certificate to be encrypted.

Method sign

Signs the certificate using the provided certifier wallet.

async sign(certifierWallet: ProtoWallet): Promise<void> 

See also: ProtoWallet

Argument Details

• certifierWallet
  • The wallet representing the certifier.

Method toBinary

Serializes the certificate into binary format, with or without a signature.

toBinary(includeSignature: boolean = true): number[] 

Returns

• The serialized certificate in binary format.

Argument Details

• includeSignature
  • Whether to include the signature in the serialization.

Method verify

Verifies the certificate’s signature.

async verify(): Promise<boolean> 

Returns

• A promise that resolves to true if the signature is valid.

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

---

Class: CompletedProtoWallet

export class CompletedProtoWallet extends ProtoWallet implements WalletInterface {
    keyDeriver: KeyDeriver;
    constructor(rootKeyOrKeyDeriver: PrivateKey | "anyone" | KeyDeriverApi) 
    async isAuthenticated(): Promise<AuthenticatedResult> 
    async waitForAuthentication(): Promise<AuthenticatedResult> 
    async getNetwork(): Promise<GetNetworkResult> 
    async getVersion(): Promise<GetVersionResult> 
    async getPublicKey(args: GetPublicKeyArgs): Promise<{
        publicKey: PubKeyHex;
    }> 
    async createAction(): Promise<CreateActionResult> 
    async signAction(): Promise<SignActionResult> 
    async abortAction(): Promise<AbortActionResult> 
    async listActions(): Promise<ListActionsResult> 
    async internalizeAction(): Promise<InternalizeActionResult> 
    async listOutputs(): Promise<ListOutputsResult> 
    async relinquishOutput(): Promise<RelinquishOutputResult> 
    async acquireCertificate(): Promise<AcquireCertificateResult> 
    async listCertificates(): Promise<ListCertificatesResult> 
    async proveCertificate(): Promise<ProveCertificateResult> 
    async relinquishCertificate(): Promise<RelinquishCertificateResult> 
    async discoverByIdentityKey(): Promise<DiscoverCertificatesResult> 
    async discoverByAttributes(): Promise<DiscoverCertificatesResult> 
    async getHeight(): Promise<GetHeightResult> 
    async getHeaderForHeight(): Promise<GetHeaderResult> 
}

See also: AbortActionResult, AcquireCertificateResult, AuthenticatedResult, CreateActionResult, DiscoverCertificatesResult, GetHeaderResult, GetHeightResult, GetNetworkResult, GetPublicKeyArgs, GetVersionResult, InternalizeActionResult, KeyDeriver, KeyDeriverApi, ListActionsResult, ListCertificatesResult, ListOutputsResult, PrivateKey, ProtoWallet, ProveCertificateResult, PubKeyHex, RelinquishCertificateResult, RelinquishOutputResult, SignActionResult, WalletInterface

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

---

Class: MasterCertificate

MasterCertificate extends the base Certificate class to manage a master keyring, enabling the creation of verifiable certificates.

It allows for the selective disclosure of certificate fields by creating a VerifiableCertificate for a specific verifier. The MasterCertificate can securely decrypt each master key and re-encrypt it for a verifier, creating a customized keyring containing only the keys necessary for the verifier to access designated fields.

export class MasterCertificate extends Certificate {
    declare type: Base64String;
    declare serialNumber: Base64String;
    declare subject: PubKeyHex;
    declare certifier: PubKeyHex;
    declare revocationOutpoint: OutpointString;
    declare fields: Record<CertificateFieldNameUnder50Bytes, Base64String>;
    declare signature?: HexString;
    masterKeyring: Record<CertificateFieldNameUnder50Bytes, Base64String>;
    constructor(type: Base64String, serialNumber: Base64String, subject: PubKeyHex, certifier: PubKeyHex, revocationOutpoint: OutpointString, fields: Record<CertificateFieldNameUnder50Bytes, Base64String>, masterKeyring: Record<CertificateFieldNameUnder50Bytes, Base64String>, signature?: HexString) 
    static async createCertificateFields(creatorWallet: ProtoWallet, certifierOrSubject: WalletCounterparty, fields: Record<CertificateFieldNameUnder50Bytes, string>): Promise<CreateCertificateFieldsResult> 
    static async createKeyringForVerifier(subjectWallet: ProtoWallet, certifier: WalletCounterparty, verifier: WalletCounterparty, fields: Record<CertificateFieldNameUnder50Bytes, Base64String>, fieldsToReveal: string[], masterKeyring: Record<CertificateFieldNameUnder50Bytes, Base64String>, serialNumber: Base64String): Promise<Record<CertificateFieldNameUnder50Bytes, string>> 
    static async issueCertificateForSubject(certifierWallet: ProtoWallet, subject: WalletCounterparty, fields: Record<CertificateFieldNameUnder50Bytes, string>, certificateType: string, getRevocationOutpoint = async (_serial: string): Promise<string> => {
        void _serial;
        return "Certificate revocation not tracked.";
    }, serialNumber?: string): Promise<MasterCertificate> 
    static async decryptFields(subjectOrCertifierWallet: ProtoWallet, masterKeyring: Record<CertificateFieldNameUnder50Bytes, Base64String>, fields: Record<CertificateFieldNameUnder50Bytes, Base64String>, counterparty: WalletCounterparty): Promise<Record<CertificateFieldNameUnder50Bytes, string>> 
    static async decryptField(subjectOrCertifierWallet: ProtoWallet, masterKeyring: Record<CertificateFieldNameUnder50Bytes, Base64String>, fieldName: Base64String, fieldValue: Base64String, counterparty: WalletCounterparty): Promise<{
        fieldRevelationKey: number[];
        decryptedFieldValue: string;
    }> 
}

See also: Base64String, Certificate, CertificateFieldNameUnder50Bytes, HexString, OutpointString, ProtoWallet, PubKeyHex, WalletCounterparty

Method createCertificateFields

Encrypts certificate fields for a subject and generates a master keyring. This method returns a master keyring tied to a specific certifier or subject who will validate and sign off on the fields, along with the encrypted certificate fields.

static async createCertificateFields(creatorWallet: ProtoWallet, certifierOrSubject: WalletCounterparty, fields: Record<CertificateFieldNameUnder50Bytes, string>): Promise<CreateCertificateFieldsResult> 

See also: CertificateFieldNameUnder50Bytes, ProtoWallet, WalletCounterparty

Returns

A promise resolving to an object containing:

• certificateFields {Record<CertificateFieldNameUnder50Bytes, Base64String>}: The encrypted certificate fields.
• masterKeyring {Record<CertificateFieldNameUnder50Bytes, Base64String>}: The master keyring containing encrypted revelation keys for each field.

Argument Details

• creatorWallet
  • The wallet of the creator responsible for encrypting the fields.
• certifierOrSubject
  • The certifier or subject who will validate the certificate fields.
• fields
  • A record of certificate field names (under 50 bytes) mapped to their values.

Method createKeyringForVerifier

Creates a keyring for a verifier, enabling them to decrypt specific certificate fields. This method decrypts the master field keys for the specified fields and re-encrypts them for the verifier’s identity key. The result is a keyring containing the keys necessary for the verifier to access the designated fields.

static async createKeyringForVerifier(subjectWallet: ProtoWallet, certifier: WalletCounterparty, verifier: WalletCounterparty, fields: Record<CertificateFieldNameUnder50Bytes, Base64String>, fieldsToReveal: string[], masterKeyring: Record<CertificateFieldNameUnder50Bytes, Base64String>, serialNumber: Base64String): Promise<Record<CertificateFieldNameUnder50Bytes, string>> 

See also: Base64String, CertificateFieldNameUnder50Bytes, ProtoWallet, WalletCounterparty

Returns

• A keyring mapping field names to encrypted field revelation keys, allowing the verifier to decrypt specified fields.

Argument Details

• subjectWallet
  • The wallet instance of the subject, used to decrypt and re-encrypt field keys.
• verifier
  • The verifier who will receive access to the selectively revealed fields. Can be an identity key as hex, ‘anyone’, or ‘self’.
• fieldsToReveal
  • An array of field names to be revealed to the verifier. Must be a subset of the certificate’s fields.
• originator
  • Optional originator identifier, used if additional context is needed for decryption and encryption operations.

Throws

Throws an error if:

• fieldsToReveal is not an array of strings.
• A field in fieldsToReveal does not exist in the certificate.
• The decrypted master field key fails to decrypt the corresponding field (indicating an invalid key).

Method decryptFields

Decrypts all fields in the MasterCertificate using the subject’s or certifier’s wallet.

This method allows the subject or certifier to decrypt the masterKeyring and retrieve the encryption keys for each field, which are then used to decrypt the corresponding field values. The counterparty used for decryption depends on how the certificate fields were created:

• If the certificate is self-signed, the counterparty should be set to ‘self’.
• Otherwise, the counterparty should always be the other party involved in the certificate issuance process (the subject or certifier).

static async decryptFields(subjectOrCertifierWallet: ProtoWallet, masterKeyring: Record<CertificateFieldNameUnder50Bytes, Base64String>, fields: Record<CertificateFieldNameUnder50Bytes, Base64String>, counterparty: WalletCounterparty): Promise<Record<CertificateFieldNameUnder50Bytes, string>> 

See also: Base64String, CertificateFieldNameUnder50Bytes, ProtoWallet, WalletCounterparty

Returns

A promise resolving to a record of field names and their decrypted values in plaintext.

Argument Details

• subjectOrCertifierWallet
  • The wallet of the subject or certifier, used to decrypt the master keyring and field values.
• masterKeyring
  • A record containing encrypted keys for each field.
• fields
  • A record of encrypted field names and their values.
• counterparty
  • The counterparty responsible for creating or signing the certificate. For self-signed certificates, use ‘self’.

Throws

Throws an error if the masterKeyring is invalid or if decryption fails for any field.

Method issueCertificateForSubject

Issues a new MasterCertificate for a specified subject.

This method generates a certificate containing encrypted fields and a keyring for the subject to decrypt all fields. Each field is encrypted with a randomly generated symmetric key, which is then encrypted for the subject. The certificate can also includes a revocation outpoint to manage potential revocation.

static async issueCertificateForSubject(certifierWallet: ProtoWallet, subject: WalletCounterparty, fields: Record<CertificateFieldNameUnder50Bytes, string>, certificateType: string, getRevocationOutpoint = async (_serial: string): Promise<string> => {
    void _serial;
    return "Certificate revocation not tracked.";
}, serialNumber?: string): Promise<MasterCertificate> 

See also: CertificateFieldNameUnder50Bytes, MasterCertificate, ProtoWallet, WalletCounterparty

Returns

• A signed MasterCertificate instance containing the encrypted fields and subject specific keyring.

Argument Details

• certifierWallet
  • The wallet of the certifier, used to sign the certificate and encrypt field keys.
• subject
  • The subject for whom the certificate is issued.
• fields
  • Unencrypted certificate fields to include, with their names and values.
• certificateType
  • The type of certificate being issued.
• getRevocationOutpoint
  • - Optional function to obtain a revocation outpoint for the certificate. Defaults to a placeholder.
• updateProgress
  • Optional callback for reporting progress updates during the operation. Defaults to a no-op.

Throws

Throws an error if any operation (e.g., encryption, signing) fails during certificate issuance.

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

---

Class: Peer

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.

export class Peer {
    public sessionManager: SessionManager;
    certificatesToRequest: RequestedCertificateSet;
    constructor(wallet: WalletInterface, transport: Transport, certificatesToRequest?: RequestedCertificateSet, sessionManager?: SessionManager, autoPersistLastSession?: boolean) 
    async toPeer(message: number[], identityKey?: string, maxWaitTime?: number): Promise<void> 
    async requestCertificates(certificatesToRequest: RequestedCertificateSet, identityKey?: string, maxWaitTime = 10000): Promise<void> 
    async getAuthenticatedSession(identityKey?: string, maxWaitTime?: number): Promise<PeerSession> 
    listenForGeneralMessages(callback: (senderPublicKey: string, payload: number[]) => void): number 
    stopListeningForGeneralMessages(callbackID: number): void 
    listenForCertificatesReceived(callback: (senderPublicKey: string, certs: VerifiableCertificate[]) => void): number 
    stopListeningForCertificatesReceived(callbackID: number): void 
    listenForCertificatesRequested(callback: (senderPublicKey: string, requestedCertificates: RequestedCertificateSet) => void): number 
    stopListeningForCertificatesRequested(callbackID: number): void 
    async processInitialRequest(message: AuthMessage): Promise<void> 
    async sendCertificateResponse(verifierIdentityKey: string, certificates: VerifiableCertificate[]): Promise<void> 
}

See also: AuthMessage, PeerSession, RequestedCertificateSet, SessionManager, Transport, VerifiableCertificate, WalletInterface

Constructor

Creates a new Peer instance

constructor(wallet: WalletInterface, transport: Transport, certificatesToRequest?: RequestedCertificateSet, sessionManager?: SessionManager, autoPersistLastSession?: boolean) 

See also: RequestedCertificateSet, SessionManager, Transport, WalletInterface

Argument Details

• wallet
  • The wallet instance used for cryptographic operations.
• transport
  • The transport mechanism used for sending and receiving messages.
• certificatesToRequest
  • Optional set of certificates to request from a peer during the initial handshake.
• sessionManager
  • Optional SessionManager to be used for managing peer sessions.
• autoPersistLastSession
  • Whether to auto-persist the session with the last-interacted-with peer. Defaults to true.

Method getAuthenticatedSession

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.

async getAuthenticatedSession(identityKey?: string, maxWaitTime?: number): Promise<PeerSession> 

See also: PeerSession

Returns

• A promise that resolves with an authenticated PeerSession.

Argument Details

• identityKey
  • The identity public key of the peer. If provided, it attempts to retrieve an existing session associated with this identity.
• maxWaitTime
  • The maximum time in milliseconds to wait for the handshake to complete if a new session is required. Defaults to a pre-defined timeout if not specified.

Throws

• Throws an error if the transport is not connected or if the handshake fails.

Method listenForCertificatesReceived

Registers a callback to listen for certificates received from peers.

listenForCertificatesReceived(callback: (senderPublicKey: string, certs: VerifiableCertificate[]) => void): number 

See also: VerifiableCertificate

Returns

The ID of the callback listener.

Argument Details

• callback
  • The function to call when certificates are received.

Method listenForCertificatesRequested

Registers a callback to listen for certificates requested from peers.

listenForCertificatesRequested(callback: (senderPublicKey: string, requestedCertificates: RequestedCertificateSet) => void): number 

See also: RequestedCertificateSet

Returns

The ID of the callback listener.

Argument Details

• callback
  • The function to call when a certificate request is received

Method listenForGeneralMessages

Registers a callback to listen for general messages from peers.

listenForGeneralMessages(callback: (senderPublicKey: string, payload: number[]) => void): number 

Returns

The ID of the callback listener.

Argument Details

• callback
  • The function to call when a general message is received.

Method processInitialRequest

Processes an initial request message from a peer.

async processInitialRequest(message: AuthMessage): Promise<void> 

See also: AuthMessage

Argument Details

• message
  • The incoming initial request message.

Method requestCertificates

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.

async requestCertificates(certificatesToRequest: RequestedCertificateSet, identityKey?: string, maxWaitTime = 10000): Promise<void> 

See also: RequestedCertificateSet

Returns

Resolves if the certificate request message is successfully sent.

Argument Details

• certificatesToRequest
  • Specifies the certifiers and types of certificates required from the peer.
• identityKey
  • The identity public key of the peer. If not provided, the current session identity is used.
• maxWaitTime
  • Maximum time in milliseconds to wait for the peer session to be authenticated.

Throws

Will throw an error if the peer session is not authenticated or if sending the request fails.

Method sendCertificateResponse

Sends a certificate response message containing the specified certificates to a peer.

async sendCertificateResponse(verifierIdentityKey: string, certificates: VerifiableCertificate[]): Promise<void> 

See also: VerifiableCertificate

Returns

• A promise that resolves once the certificate response has been sent successfully.

Argument Details

• verifierIdentityKey
  • The identity key of the peer requesting the certificates.
• certificates
  • The list of certificates to be included in the response.

Throws

Throws an error if the peer session could not be authenticated or if message signing fails.

Method stopListeningForCertificatesReceived

Cancels and unsubscribes a certificatesReceived listener.

stopListeningForCertificatesReceived(callbackID: number): void 

Argument Details

• callbackID
  • The ID of the certificates received callback to cancel.

Method stopListeningForCertificatesRequested

Cancels and unsubscribes a certificatesRequested listener.

stopListeningForCertificatesRequested(callbackID: number): void 

Argument Details

• callbackID
  • The ID of the requested certificates callback to cancel.

Method stopListeningForGeneralMessages

Removes a general message listener.

stopListeningForGeneralMessages(callbackID: number): void 

Argument Details

• callbackID
  • The ID of the callback to remove.

Method toPeer

Sends a general message to a peer, and initiates a handshake if necessary.

async toPeer(message: number[], identityKey?: string, maxWaitTime?: number): Promise<void> 

Argument Details

• message
  • The message payload to send.
• identityKey
  • The identity public key of the peer. If not provided, a handshake will be initiated.

Throws

Will throw an error if the message fails to send.

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

---

Class: SessionManager

Manages sessions for peers, allowing sessions to be added, retrieved, updated, and removed by relevant identifiers (sessionNonce and peerIdentityKey).

export class SessionManager {
    constructor() 
    addSession(session: PeerSession): void 
    updateSession(session: PeerSession): void 
    getSession(identifier: string): PeerSession | undefined 
    removeSession(session: PeerSession): void 
    hasSession(identifier: string): boolean 
}

See also: PeerSession

Method addSession

Adds a session to the manager, associating it with relevant identifiers for retrieval.

addSession(session: PeerSession): void 

See also: PeerSession

Argument Details

• session
  • The peer session to add.

Method getSession

Retrieves a session based on a given identifier.

getSession(identifier: string): PeerSession | undefined 

See also: PeerSession

Returns

• The matching peer session, or undefined if not found.

Argument Details

• identifier
  • The identifier for the session (sessionNonce or peerIdentityKey).

Method hasSession

Checks if a session exists based on a given identifier.

hasSession(identifier: string): boolean 

Returns

• True if the session exists, false otherwise.

Argument Details

• identifier
  • The identifier to check.

Method removeSession

Removes a session from the manager by clearing all associated identifiers.

removeSession(session: PeerSession): void 

See also: PeerSession

Argument Details

• session
  • The peer session to remove.

Method updateSession

Updates a session in the manager, ensuring that all identifiers are correctly associated.

updateSession(session: PeerSession): void 

See also: PeerSession

Argument Details

• session
  • The peer session to update.

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

---

Class: SimplifiedFetchTransport

Implements an HTTP-specific transport for handling Peer mutual authentication messages. This class integrates with fetch to send and receive authenticated messages between peers.

export class SimplifiedFetchTransport implements Transport {
    fetchClient: typeof fetch;
    baseUrl: string;
    constructor(baseUrl: string, fetchClient = defaultFetch) 
    async send(message: AuthMessage): Promise<void> 
    async onData(callback: (message: AuthMessage) => Promise<void>): Promise<void> 
    deserializeRequestPayload(payload: number[]): {
        method: string;
        urlPostfix: string;
        headers: Record<string, string>;
        body: number[];
        requestId: string;
    } 
}

See also: AuthMessage, Transport

Constructor

Constructs a new instance of SimplifiedFetchTransport.

constructor(baseUrl: string, fetchClient = defaultFetch) 

Argument Details

• baseUrl
  • The base URL for all HTTP requests made by this transport.
• fetchClient
  • A fetch implementation to use for HTTP requests (default: global fetch).

Method deserializeRequestPayload

Deserializes a request payload from a byte array into an HTTP request-like structure.

deserializeRequestPayload(payload: number[]): {
    method: string;
    urlPostfix: string;
    headers: Record<string, string>;
    body: number[];
    requestId: string;
} 

Returns

An object representing the deserialized request, including the method, URL postfix (path and query string), headers, body, and request ID.

Argument Details

• payload
  • The serialized payload to deserialize.

Method onData

Registers a callback to handle incoming messages. This must be called before sending any messages to ensure responses can be processed.

async onData(callback: (message: AuthMessage) => Promise<void>): Promise<void> 

See also: AuthMessage

Returns

A promise that resolves once the callback is set.

Argument Details

• callback
  • A function to invoke when an incoming AuthMessage is received.

Method send

Sends a message to an HTTP server using the transport mechanism. Handles both general and authenticated message types. For general messages, the payload is deserialized and sent as an HTTP request. For other message types, the message is sent as a POST request to the /auth endpoint.

async send(message: AuthMessage): Promise<void> 

See also: AuthMessage

Returns

A promise that resolves when the message is successfully sent.

Argument Details

• message
  • The AuthMessage to send.

Throws

Will throw an error if no listener has been registered via onData.

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

---

Class: VerifiableCertificate

VerifiableCertificate extends the Certificate class, adding functionality to manage a verifier-specific keyring. This keyring allows selective decryption of certificate fields for authorized verifiers.

export class VerifiableCertificate extends Certificate {
    declare type: Base64String;
    declare serialNumber: Base64String;
    declare subject: PubKeyHex;
    declare certifier: PubKeyHex;
    declare revocationOutpoint: OutpointString;
    declare fields: Record<CertificateFieldNameUnder50Bytes, string>;
    declare signature?: HexString;
    keyring: Record<CertificateFieldNameUnder50Bytes, string>;
    decryptedFields?: Record<CertificateFieldNameUnder50Bytes, Base64String>;
    constructor(type: Base64String, serialNumber: Base64String, subject: PubKeyHex, certifier: PubKeyHex, revocationOutpoint: OutpointString, fields: Record<CertificateFieldNameUnder50Bytes, string>, keyring: Record<CertificateFieldNameUnder50Bytes, string>, signature?: HexString, decryptedFields?: Record<CertificateFieldNameUnder50Bytes, Base64String>) 
    async decryptFields(verifierWallet: ProtoWallet): Promise<Record<CertificateFieldNameUnder50Bytes, string>> 
}

See also: Base64String, Certificate, CertificateFieldNameUnder50Bytes, HexString, OutpointString, ProtoWallet, PubKeyHex

Method decryptFields

Decrypts selectively revealed certificate fields using the provided keyring and verifier wallet

async decryptFields(verifierWallet: ProtoWallet): Promise<Record<CertificateFieldNameUnder50Bytes, string>> 

See also: CertificateFieldNameUnder50Bytes, ProtoWallet

Returns

• A promise that resolves to an object where each key is a field name and each value is the decrypted field value as a string.

Argument Details

• verifierWallet
  • The wallet instance of the certificate’s verifier, used to decrypt field keys.

Throws

Throws an error if any of the decryption operations fail, with a message indicating the failure context.

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

---

Functions

createNonce
verifyNonce

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

---

Function: createNonce

Creates a nonce derived from a wallet

export async function createNonce(wallet: WalletInterface, counterparty: WalletCounterparty = "self"): Promise<string> 

See also: WalletCounterparty, WalletInterface

Returns

A random nonce derived with a wallet

Argument Details

• counterparty
  • The counterparty to the nonce creation. Defaults to ‘self’.

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

---

Function: verifyNonce

Verifies a nonce derived from a wallet

export async function verifyNonce(nonce: string, wallet: WalletInterface, counterparty: WalletCounterparty = "self"): Promise<boolean> 

See also: WalletCounterparty, WalletInterface

Returns

The status of the validation

Argument Details

• nonce
  • A nonce to verify as a base64 string.
• counterparty
  • The counterparty to the nonce creation. Defaults to ‘self’.

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

---

Types

Enums

Variables

getVerifiableCertificates
validateCertificates

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

---

Variable: getVerifiableCertificates

getVerifiableCertificates = async (wallet: WalletInterface, requestedCertificates: RequestedCertificateSet, verifierIdentityKey: string): Promise<VerifiableCertificate[]> => {
    const matchingCertificates = await wallet.listCertificates({
        certifiers: requestedCertificates.certifiers,
        types: Object.keys(requestedCertificates.types)
    });
    return await Promise.all(matchingCertificates.certificates.map(async (certificate) => {
        const { keyringForVerifier } = await wallet.proveCertificate({
            certificate,
            fieldsToReveal: requestedCertificates.types[certificate.type],
            verifier: verifierIdentityKey
        });
        return new VerifiableCertificate(certificate.type, certificate.serialNumber, certificate.subject, certificate.certifier, certificate.revocationOutpoint, certificate.fields, keyringForVerifier, certificate.signature);
    }));
}

See also: RequestedCertificateSet, VerifiableCertificate, WalletInterface

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

---

Variable: validateCertificates

validateCertificates = async (verifierWallet: WalletInterface, message: AuthMessage, certificatesRequested?: RequestedCertificateSet): Promise<void> => {
    if ((message.certificates == null) || message.certificates.length === 0) {
        throw new Error("No certificates were provided in the AuthMessage.");
    }
    await Promise.all(message.certificates.map(async (incomingCert: VerifiableCertificate) => {
        if (incomingCert.subject !== message.identityKey) {
            throw new Error(`The subject of one of your certificates ("${incomingCert.subject}") is not the same as the request sender ("${message.identityKey}").`);
        }
        const certToVerify = new VerifiableCertificate(incomingCert.type, incomingCert.serialNumber, incomingCert.subject, incomingCert.certifier, incomingCert.revocationOutpoint, incomingCert.fields, incomingCert.keyring, incomingCert.signature);
        const isValidCert = await certToVerify.verify();
        if (!isValidCert) {
            throw new Error(`The signature for the certificate with serial number ${certToVerify.serialNumber} is invalid!`);
        }
        if (certificatesRequested != null) {
            const { certifiers, types } = certificatesRequested;
            if (!certifiers.includes(certToVerify.certifier)) {
                throw new Error(`Certificate with serial number ${certToVerify.serialNumber} has an unrequested certifier: ${certToVerify.certifier}`);
            }
            const requestedFields = types[certToVerify.type];
            if (requestedFields == null) {
                throw new Error(`Certificate with type ${certToVerify.type} was not requested`);
            }
        }
        await certToVerify.decryptFields(verifierWallet);
    }));
}

See also: AuthMessage, Certificate, RequestedCertificateSet, VerifiableCertificate, WalletInterface, verify

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

---

This site is open source. Improve this page.