@bsv/sdk 2.1.1 → 2.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsv/sdk",
-  "version": "2.1.1",
+  "version": "2.1.3",
   "type": "module",
   "description": "BSV Blockchain Software Development Kit",
   "main": "dist/cjs/mod.js",

package/src/auth/Peer.ts

@@ -1,4 +1,4 @@
-import { SessionManager } from './SessionManager.js'
+import { SessionManager, AsyncSessionManager } from './SessionManager.js'
 import {
   createNonce,
   verifyNonce,
@@ -28,6 +28,13 @@ const BufferCtor =
  * This version supports multiple concurrent sessions per peer identityKey.
  */
 export class Peer {
+  // Declared as the synchronous {@link SessionManager} for back-compat with
+  // pre-existing consumers that read `peer.sessionManager.getSession(...)`
+  // and friends as synchronous calls. The constructor also accepts an
+  // {@link AsyncSessionManager}; in that case the runtime value's methods
+  // return Promises. Peer always awaits internal calls so both work, but
+  // external code that reaches in directly should match the implementation
+  // it injected. See `AsyncSessionManager` for the opt-in async contract.
   public sessionManager: SessionManager
   private readonly transport: Transport
   private readonly wallet: WalletInterface
@@ -97,7 +104,7 @@ export class Peer {
    * @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 {SessionManager | AsyncSessionManager} [sessionManager] - Optional session store. Pass an {@link AsyncSessionManager} for shared/durable storage in load-balanced deployments; otherwise the default in-process {@link SessionManager} is used.
    * @param {boolean} [autoPersistLastSession] - Whether to auto-persist the session with the last-interacted-with peer. Defaults to true.
    * @param {OriginatorDomainNameStringUnder250Bytes} [originator] - Optional originator domain name.
    */
@@ -105,7 +112,7 @@ export class Peer {
     wallet: WalletInterface,
     transport: Transport,
     certificatesToRequest?: RequestedCertificateSet,
-    sessionManager?: SessionManager,
+    sessionManager?: SessionManager | AsyncSessionManager,
     autoPersistLastSession?: boolean,
     originator?: OriginatorDomainNameStringUnder250Bytes
   ) {
@@ -117,8 +124,11 @@ export class Peer {
       types: {}
     }
     this.ready = this.transport.onData(this.handleIncomingMessage.bind(this)) // NOSONAR(typescript:S7059): listener must register synchronously — see ready field comment
+    // Cast keeps the public field typed as the synchronous `SessionManager`
+    // for back-compat. When an `AsyncSessionManager` is injected, the actual
+    // runtime methods return Promises — Peer awaits them internally below.
     this.sessionManager =
-      sessionManager ?? new SessionManager()
+      (sessionManager ?? new SessionManager()) as SessionManager
     if (autoPersistLastSession === false) {
       this.autoPersistLastSession = false
     } else {
@@ -178,7 +188,7 @@ export class Peer {
     }
 
     peerSession.lastUpdate = Date.now()
-    this.sessionManager.updateSession(peerSession)
+    await this.sessionManager.updateSession(peerSession)
 
     try {
       await this.transport.send(generalMessage)
@@ -233,7 +243,7 @@ export class Peer {
 
     // Update last-used timestamp
     peerSession.lastUpdate = Date.now()
-    this.sessionManager.updateSession(peerSession)
+    await this.sessionManager.updateSession(peerSession)
 
     try {
       await this.transport.send(certRequestMessage)
@@ -262,7 +272,7 @@ export class Peer {
 
     let peerSession: PeerSession | undefined
     if (typeof identityKey === 'string') {
-      peerSession = this.sessionManager.getSession(identityKey)
+      peerSession = await this.sessionManager.getSession(identityKey)
     }
 
     // If that session doesn't exist or isn't authenticated, initiate handshake
@@ -270,7 +280,7 @@ export class Peer {
       // This will create a brand-new session
       const sessionNonce = await this.initiateHandshake(identityKey)
       // Now retrieve it by the sessionNonce
-      peerSession = this.sessionManager.getSession(sessionNonce)
+      peerSession = await this.sessionManager.getSession(sessionNonce)
       if (peerSession?.isAuthenticated !== true) {
         throw new Error('Unable to establish mutual authentication with peer!')
       }
@@ -367,7 +377,7 @@ export class Peer {
     const certificatesRequired =
       this.certificatesToRequest.certifiers.length > 0
 
-    this.sessionManager.addSession({
+    await this.sessionManager.addSession({
       isAuthenticated: false,
       sessionNonce,
       peerIdentityKey: identityKey,
@@ -511,7 +521,7 @@ export class Peer {
       Array.isArray(this.certificatesToRequest?.certifiers) &&
       this.certificatesToRequest.certifiers.length > 0
 
-    this.sessionManager.addSession({
+    await this.sessionManager.addSession({
       isAuthenticated: true,
       sessionNonce,
       peerNonce: message.initialNonce,
@@ -588,7 +598,7 @@ export class Peer {
       )
     }
 
-    const peerSession = this.sessionManager.getSession(message.yourNonce as string)
+    const peerSession = await this.sessionManager.getSession(message.yourNonce as string)
     if (peerSession == null) {
       throw new Error(`Peer session not found for peer: ${message.identityKey}`)
     }
@@ -624,7 +634,7 @@ export class Peer {
     peerSession.certificatesValidated = !peerSession.certificatesRequired
 
     peerSession.lastUpdate = Date.now()
-    this.sessionManager.updateSession(peerSession)
+    await this.sessionManager.updateSession(peerSession)
 
     // --- Validate certificates if provided ---
     if (
@@ -641,7 +651,7 @@ export class Peer {
 
       peerSession.certificatesValidated = true
       peerSession.lastUpdate = Date.now()
-      this.sessionManager.updateSession(peerSession)
+      await this.sessionManager.updateSession(peerSession)
 
       // Resolve any promises waiting for certificate validation
       if (peerSession.sessionNonce != null) {
@@ -711,7 +721,7 @@ export class Peer {
         `Unable to verify nonce for certificate request message from: ${message.identityKey}`
       )
     }
-    const peerSession = this.sessionManager.getSession(message.yourNonce as string)
+    const peerSession = await this.sessionManager.getSession(message.yourNonce as string)
     if (peerSession == null) {
       throw new Error(`Session not found for nonce: ${message.yourNonce as string}`)
     }
@@ -731,7 +741,7 @@ export class Peer {
 
     // Update usage
     peerSession.lastUpdate = Date.now()
-    this.sessionManager.updateSession(peerSession)
+    await this.sessionManager.updateSession(peerSession)
 
     if (
       (message.requestedCertificates != null) &&
@@ -789,7 +799,7 @@ export class Peer {
 
     // Update usage
     peerSession.lastUpdate = Date.now()
-    this.sessionManager.updateSession(peerSession)
+    await this.sessionManager.updateSession(peerSession)
 
     try {
       await this.transport.send(certificateResponse)
@@ -813,7 +823,7 @@ export class Peer {
       )
     }
 
-    const peerSession = this.sessionManager.getSession(message.yourNonce as string)
+    const peerSession = await this.sessionManager.getSession(message.yourNonce as string)
     if (peerSession == null) {
       throw new Error(`Session not found for nonce: ${message.yourNonce as string}`)
     }
@@ -843,7 +853,7 @@ export class Peer {
 
       peerSession.certificatesValidated = true
       peerSession.lastUpdate = Date.now()
-      this.sessionManager.updateSession(peerSession)
+      await this.sessionManager.updateSession(peerSession)
 
       // Resolve any promises waiting for certificate validation
       if (peerSession.sessionNonce != null) {
@@ -878,7 +888,7 @@ export class Peer {
       )
     }
 
-    const peerSession = this.sessionManager.getSession(message.yourNonce as string)
+    const peerSession = await this.sessionManager.getSession(message.yourNonce as string)
     if (peerSession == null) {
       throw new Error(`Session not found for nonce: ${message.yourNonce as string}`)
     }
@@ -942,7 +952,7 @@ export class Peer {
 
     // Mark last usage
     peerSession.lastUpdate = Date.now()
-    this.sessionManager.updateSession(peerSession)
+    await this.sessionManager.updateSession(peerSession)
 
     // Update lastInteractedWithPeer
     this.lastInteractedWithPeer = message.identityKey

package/src/auth/SessionManager.ts

@@ -1,5 +1,27 @@
 import { PeerSession } from './types.js'
 
+/**
+ * Opt-in async session-manager contract for horizontally scaled deployments.
+ *
+ * The default in-process {@link SessionManager} stores BRC-103 nonce/session
+ * state in memory and is synchronous. Multi-instance HTTP servers that need
+ * every instance to resolve the same handshake state — e.g. behind a load
+ * balancer without sticky routing — can implement `AsyncSessionManager`
+ * against a shared store such as Redis or SQL and pass it to {@link Peer}
+ * or `createAuthMiddleware` instead.
+ *
+ * {@link Peer} accepts `SessionManager | AsyncSessionManager` and awaits every
+ * call internally, so sync stores incur no extra latency while async stores
+ * work transparently.
+ */
+export interface AsyncSessionManager {
+  addSession: (session: PeerSession) => Promise<void>
+  updateSession: (session: PeerSession) => Promise<void>
+  getSession: (identifier: string) => Promise<PeerSession | undefined>
+  removeSession: (session: PeerSession) => Promise<void>
+  hasSession: (identifier: string) => Promise<boolean>
+}
+
 /**
  * Manages sessions for peers, allowing multiple concurrent sessions
  * per identity key. Primary lookup is always by `sessionNonce`.

package/src/auth/__tests/Peer.test.ts

@@ -1,5 +1,5 @@
 import { Peer } from '../../auth/Peer.js'
-import { AuthMessage, Transport } from '../../auth/types.js'
+import { AuthMessage, PeerSession, Transport } from '../../auth/types.js'
 import { jest } from '@jest/globals'
 import { WalletInterface } from '../../wallet/Wallet.interfaces.js'
 import { Utils, PrivateKey } from '../../primitives/index.js'
@@ -8,6 +8,7 @@ import { MasterCertificate } from '../../auth/certificates/MasterCertificate.js'
 import { getVerifiableCertificates } from '../../auth/utils/getVerifiableCertificates.js'
 import { CompletedProtoWallet } from '../certificates/__tests/CompletedProtoWallet.js'
 import { SimplifiedFetchTransport } from '../../auth/transports/SimplifiedFetchTransport.js'
+import { SessionManager, AsyncSessionManager } from '../../auth/SessionManager.js'
 
 const certifierPrivKey = new PrivateKey(21)
 const alicePrivKey = new PrivateKey(22)
@@ -51,6 +52,35 @@ class LocalTransport implements Transport {
   }
 }
 
+class AsyncSessionStore implements AsyncSessionManager {
+  private readonly sessions = new SessionManager()
+
+  async addSession(session: PeerSession): Promise<void> {
+    await Promise.resolve()
+    this.sessions.addSession(session)
+  }
+
+  async updateSession(session: PeerSession): Promise<void> {
+    await Promise.resolve()
+    this.sessions.updateSession(session)
+  }
+
+  async getSession(identifier: string): Promise<PeerSession | undefined> {
+    await Promise.resolve()
+    return this.sessions.getSession(identifier)
+  }
+
+  async removeSession(session: PeerSession): Promise<void> {
+    await Promise.resolve()
+    this.sessions.removeSession(session)
+  }
+
+  async hasSession(identifier: string): Promise<boolean> {
+    await Promise.resolve()
+    return this.sessions.hasSession(identifier)
+  }
+}
+
 function waitForNextGeneralMessage(
   peer: Peer,
   handler?: (senderPublicKey: string, payload: number[]) => void
@@ -290,6 +320,22 @@ describe('Peer class mutual authentication and certificate exchange', () => {
     expect(certificatesReceivedByBob).toEqual([])
   }, 15000)
 
+  it('supports asynchronous shared session managers', async () => {
+    alice = new Peer(walletA, transportA, undefined, new AsyncSessionStore())
+    bob = new Peer(walletB, transportB, undefined, new AsyncSessionStore())
+
+    const bobReceivedGeneralMessage = waitForNextGeneralMessage(bob)
+    const aliceReceivedGeneralMessage = waitForNextGeneralMessage(alice)
+
+    bob.listenForGeneralMessages((senderPublicKey) => {
+      void bob.toPeer(Utils.toArray('Hello Alice!'), senderPublicKey)
+    })
+
+    await alice.toPeer(Utils.toArray('Hello Bob!'))
+    await bobReceivedGeneralMessage
+    await aliceReceivedGeneralMessage
+  }, 15000)
+
   it('Alice talks to Bob across two devices, Bob can respond across both sessions', async () => {
     const transportA1 = new LocalTransport()
     const transportA2 = new LocalTransport()

package/src/auth/clients/AuthFetch.ts

@@ -7,7 +7,7 @@ import { OriginatorDomainNameStringUnder250Bytes, WalletInterface } from '../../
 import { createNonce } from '../utils/createNonce.js'
 import { Peer } from '../Peer.js'
 import { SimplifiedFetchTransport } from '../transports/SimplifiedFetchTransport.js'
-import { SessionManager } from '../SessionManager.js'
+import { SessionManager, AsyncSessionManager } from '../SessionManager.js'
 import { RequestedCertificateSet } from '../types.js'
 import { VerifiableCertificate } from '../certificates/VerifiableCertificate.js'
 import { Writer } from '../../primitives/utils.js'
@@ -79,10 +79,13 @@ export class AuthFetch {
   * @param wallet - The wallet instance for signing and authentication.
   * @param requestedCertificates - Optional set of certificates to request from peers.
   */
-  constructor(wallet: WalletInterface, requestedCertificates?: RequestedCertificateSet, sessionManager?: SessionManager, originator?: OriginatorDomainNameStringUnder250Bytes) {
+  constructor(wallet: WalletInterface, requestedCertificates?: RequestedCertificateSet, sessionManager?: SessionManager | AsyncSessionManager, originator?: OriginatorDomainNameStringUnder250Bytes) {
     this.wallet = wallet
     this.requestedCertificates = requestedCertificates
-    this.sessionManager = sessionManager ?? new SessionManager()
+    // See `Peer.sessionManager`: field stays typed as the synchronous
+    // `SessionManager` for back-compat; if an `AsyncSessionManager` is
+    // injected, the underlying Peer awaits all calls internally.
+    this.sessionManager = (sessionManager ?? new SessionManager()) as SessionManager
     this.originator = originator
   }
 

package/src/identity/ContactsManager.ts

@@ -34,38 +34,74 @@ export class ContactsManager {
   private readonly CONTACTS_CACHE_KEY = 'metanet-contacts'
   private readonly originator?: string
 
+  // Performance state — prevents thundering herd of concurrent contact loads and
+  // short-circuits the overlay path entirely when we've previously observed an
+  // empty contacts basket. Both are invalidated by saveContact/removeContact and
+  // by an explicit forceRefresh.
+  private inFlightLoad: Promise<Contact[]> | null = null
+  private knownEmpty = false
+
   constructor (wallet?: WalletInterface, originator?: string) {
     this.wallet = wallet ?? new WalletClient()
     this.originator = originator
   }
 
   /**
-   * Load all records from the contacts basket
+   * Load all records from the contacts basket.
+   *
+   * Concurrent calls share a single in-flight load (no thundering herd). After
+   * the basket has been observed empty once, subsequent calls return `[]`
+   * synchronously without hitting the wallet — until `forceRefresh` is passed
+   * or a contact is saved/removed.
+   *
    * @param identityKey Optional specific identity key to fetch
    * @param forceRefresh Whether to force a check for new contact data
    * @param limit Maximum number of contacts to return
-   * @returns A promise that resolves with an array of contacts
    */
   async getContacts (identityKey?: PubKeyHex, forceRefresh = false, limit = 1000): Promise<Contact[]> {
+    if (forceRefresh) this.invalidate()
+
+    if (this.knownEmpty) return []
+
     if (!forceRefresh) {
       const fromCache = this.loadCachedContacts(identityKey)
       if (fromCache !== null) return fromCache
     }
 
-    const tags = await this.buildIdentityKeyTags(identityKey)
+    // Coalesce concurrent loads onto a single Promise so a fan-out of N
+    // identity calls produces ONE listOutputs + decrypt batch, not N.
+    this.inFlightLoad ??= this.loadContactsFromWallet(limit).finally(() => {
+      this.inFlightLoad = null
+    })
+    const all = await this.inFlightLoad
+    return identityKey == null ? all : all.filter(c => c.identityKey === identityKey)
+  }
+
+  /** Reset cached state. Call after writes. */
+  private invalidate (): void {
+    this.cache.removeItem(this.CONTACTS_CACHE_KEY)
+    this.knownEmpty = false
+    this.inFlightLoad = null
+  }
+
+  /** Underlying wallet load — invoked at most once concurrently via `inFlightLoad`. */
+  private async loadContactsFromWallet (limit: number): Promise<Contact[]> {
+    // Always load the full basket so subsequent filters (by identityKey) hit cache.
+    // Tag filtering is reserved for explicit per-key write paths.
     const outputs = await this.wallet.listOutputs(
-      { basket: 'contacts', include: 'locking scripts', includeCustomInstructions: true, tags, limit },
+      { basket: 'contacts', include: 'locking scripts', includeCustomInstructions: true, tags: [], limit },
       this.originator
     )
 
     if (outputs.outputs == null || outputs.outputs.length === 0) {
       this.cache.setItem(this.CONTACTS_CACHE_KEY, JSON.stringify([]))
+      this.knownEmpty = true
       return []
     }
 
     const contacts = await this.decryptContactOutputs(outputs.outputs)
     this.cache.setItem(this.CONTACTS_CACHE_KEY, JSON.stringify(contacts))
-    return identityKey != null ? contacts.filter(c => c.identityKey === identityKey) : contacts
+    return contacts
   }
 
   /** Returns cached contacts (optionally filtered) or null if cache is missing/invalid. */
@@ -158,6 +194,8 @@ export class ContactsManager {
       await this.createContactOutput(lockingScript, keyID, hashedIdentityKey, contact)
     }
     this.cache.setItem(this.CONTACTS_CACHE_KEY, JSON.stringify(contacts))
+    this.knownEmpty = false
+    this.inFlightLoad = null
   }
 
   /** Computes the HMAC-based hash of an identity key for tag indexing. */
@@ -265,11 +303,14 @@ export class ContactsManager {
     if (cached != null && cached !== '') {
       try {
         const contacts: Contact[] = JSON.parse(cached)
-        this.cache.setItem(this.CONTACTS_CACHE_KEY, JSON.stringify(contacts.filter(c => c.identityKey !== identityKey)))
+        const remaining = contacts.filter(c => c.identityKey !== identityKey)
+        this.cache.setItem(this.CONTACTS_CACHE_KEY, JSON.stringify(remaining))
+        this.knownEmpty = remaining.length === 0
       } catch (e) {
         console.warn('Failed to update cache after contact removal:', e)
       }
     }
+    this.inFlightLoad = null
 
     const tags = await this.buildIdentityKeyTags(identityKey)
     const outputs = await this.wallet.listOutputs(