@bsv/sdk 2.1.2 → 2.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsv/sdk",
-  "version": "2.1.2",
+  "version": "2.1.4",
   "type": "module",
   "description": "BSV Blockchain Software Development Kit",
   "main": "dist/cjs/mod.js",
@@ -237,23 +237,23 @@
   },
   "homepage": "https://github.com/bsv-blockchain/ts-stack/tree/main/packages/sdk#readme",
   "devDependencies": {
-    "@eslint/js": "^9.39.1",
-    "@jest/globals": "^30.3.0",
-    "@rspack/cli": "^2.0.0",
-    "@rspack/core": "^1.6.1",
+    "@eslint/js": "^10.0.1",
+    "@jest/globals": "^30.4.1",
+    "@rspack/cli": "^2.0.4",
+    "@rspack/core": "^2.0.4",
     "@types/jest": "^30.0.0",
-    "@types/node": "^24.10.1",
-    "eslint": "^9.39.1",
-    "globals": "^16.5.0",
-    "jest": "^30.3.0",
-    "jest-environment-jsdom": "^30.3.0",
-    "ts-jest": "^29.4.9",
+    "@types/node": "^25.9.1",
+    "eslint": "^10.4.0",
+    "globals": "^17.6.0",
+    "jest": "^30.4.2",
+    "jest-environment-jsdom": "^30.4.1",
+    "ts-jest": "^29.4.11",
     "ts-loader": "^9.5.4",
     "ts-standard": "^12.0.2",
     "ts2md": "^0.2.8",
     "tsconfig-to-dual-package": "^1.2.0",
-    "typescript": "^5.9.3",
-    "typescript-eslint": "^8.46.4"
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.60.0"
   },
   "ts-standard": {
     "project": "tsconfig.eslint.json",

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/compat/Mnemonic.ts

@@ -125,9 +125,22 @@ export default class Mnemonic {
    * Sets the mnemonic for the instance from a string.
    * @param {string} mnemonic - The mnemonic phrase as a string.
    * @returns {this} The Mnemonic instance with the set mnemonic.
+   * @throws {Error} If the mnemonic does not pass BIP-39 validation
+   * (unknown words, invalid length, or bad checksum).
    */
   public fromString (mnemonic: string): this {
     this.mnemonic = mnemonic
+    let valid = false
+    try {
+      valid = this.check()
+    } catch {
+      valid = false
+    }
+    if (!valid) {
+      throw new Error(
+        'Mnemonic does not pass the check - was the mnemonic typed incorrectly? Are there extra spaces?'
+      )
+    }
     return this
   }
 

package/src/compat/__tests/Mnemonic.test.ts

@@ -49,15 +49,21 @@ describe('Mnemonic', function () {
     mnemonic = m.mnemonic
 
     // mnemonics with extra whitespace do not pass the check
-    m = new Mnemonic().fromString(mnemonic + ' ')
-    expect(m.check()).toEqual(false)
+    const trailingSpace = mnemonic + ' '
+    const trailing = new Mnemonic()
+    trailing.mnemonic = trailingSpace
+    expect(trailing.check()).toEqual(false)
+    expect(() => new Mnemonic().fromString(trailingSpace)).toThrow()
 
     // mnemonics with a word replaced do not pass the check
     const words = mnemonic.split(' ')
     expect(words[words.length - 1]).not.toEqual('zoo')
     words[words.length - 1] = 'zoo'
-    mnemonic = words.join(' ')
-    expect(new Mnemonic().fromString(mnemonic).check()).toEqual(false)
+    const badWord = words.join(' ')
+    const replaced = new Mnemonic()
+    replaced.mnemonic = badWord
+    expect(replaced.check()).toEqual(false)
+    expect(() => new Mnemonic().fromString(badWord)).toThrow()
   })
 
   describe('#toBinary', () => {
@@ -132,13 +138,51 @@ describe('Mnemonic', function () {
   })
 
   describe('#fromString', () => {
-    it('should throw an error in invalid mnemonic', () => {
+    it('should throw an error on invalid mnemonic when toSeed is called', () => {
       expect(() => {
         new Mnemonic().fromString('invalid mnemonic').toSeed()
       }).toThrow(
         'Mnemonic does not pass the check - was the mnemonic typed incorrectly? Are there extra spaces?'
       )
     })
+
+    it('should throw immediately on nonsense input', () => {
+      expect(() => {
+        Mnemonic.fromString('this is not a real bip39 mnemonic phrase at all')
+      }).toThrow(
+        'Mnemonic does not pass the check - was the mnemonic typed incorrectly? Are there extra spaces?'
+      )
+    })
+
+    it('should throw on garbage string', () => {
+      expect(() => {
+        Mnemonic.fromString('asdfghjkl qwertyuiop zxcvbnm')
+      }).toThrow()
+    })
+
+    it('should throw on empty string', () => {
+      expect(() => {
+        Mnemonic.fromString('')
+      }).toThrow()
+    })
+
+    it('should throw on valid words but wrong checksum', () => {
+      // 12 valid wordlist entries but checksum will not match
+      expect(() => {
+        Mnemonic.fromString(
+          'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon'
+        )
+      }).toThrow()
+    })
+
+    it('should accept a known-valid BIP-39 phrase', () => {
+      const m = Mnemonic.fromString(
+        'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about'
+      )
+      expect(m.mnemonic).toEqual(
+        'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about'
+      )
+    })
   })
 
   describe('@isValid', () => {

package/src/overlay-tools/LookupResolver.ts

@@ -105,6 +105,73 @@ export const DEFAULT_TESTNET_SLAP_TRACKERS: string[] = [
 
 const MAX_TRACKER_WAIT_TIME = 5000
 
+/** A wall-clock deadline that rejects after `timeoutMs`, optionally aborting a controller. */
+interface Deadline {
+  /** Rejects with `Error('Request timed out')` once the timer fires. */
+  promise: Promise<never>
+  /** Clears the underlying timer. Safe to call after the timer has already fired. */
+  cancel: () => void
+  /** Returns true once the timer has fired. */
+  didTimeOut: () => boolean
+}
+
+function createDeadline (timeoutMs: number, controller?: AbortController): Deadline {
+  let expired = false
+  let timer: ReturnType<typeof setTimeout> | null = null
+  const promise = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => {
+      expired = true
+      try { controller?.abort() } catch { /* noop */ }
+      reject(new Error('Request timed out'))
+    }, timeoutMs)
+  })
+  return {
+    promise,
+    cancel: () => {
+      if (timer !== null) clearTimeout(timer)
+    },
+    didTimeOut: () => expired
+  }
+}
+
+function normalizeLookupError (err: unknown, timedOut: boolean): Error {
+  if (timedOut) return new Error('Request timed out')
+  if ((err as { name?: string })?.name === 'AbortError') return new Error('Request timed out')
+  if (err instanceof Error) return err
+  return new Error(stringifyErrorValue(err))
+}
+
+/**
+ * Coerce a non-Error thrown value to a human-readable string without falling
+ * back to the default `'[object Object]'` for plain objects.
+ */
+function stringifyErrorValue (value: unknown): string {
+  if (value === null) return 'null'
+  if (value === undefined) return 'undefined'
+  if (typeof value === 'string') return value
+  if (typeof value === 'number') return value.toString()
+  if (typeof value === 'boolean') return value ? 'true' : 'false'
+  if (typeof value === 'bigint') return value.toString()
+  const message = (value as { message?: unknown }).message
+  if (typeof message === 'string' && message.length > 0) return message
+  try {
+    return JSON.stringify(value) ?? 'Unknown error'
+  } catch {
+    return 'Unknown error'
+  }
+}
+
+/**
+ * Returns true when the given Content-Type header value represents
+ * `application/octet-stream`, ignoring case and any media-type parameters
+ * (e.g. `; charset=utf-8`).
+ */
+function isOctetStream (contentType: string | null): boolean {
+  if (typeof contentType !== 'string') return false
+  const baseType = contentType.split(';', 1)[0].trim().toLowerCase()
+  return baseType === 'application/octet-stream'
+}
+
 /** Internal cache options. Kept optional to preserve drop-in compatibility. */
 interface CacheOptions {
   /** How long (ms) a hosts entry is considered fresh. Default 5 minutes. */
@@ -181,36 +248,46 @@ export class HTTPSOverlayLookupFacilitator implements OverlayLookupFacilitator {
     }
 
     const controller = typeof AbortController === 'undefined' ? undefined : new AbortController()
-    const timer = setTimeout(() => {
-      try { controller?.abort() } catch { /* noop */ }
-    }, timeout)
+    const deadline = createDeadline(timeout, controller)
 
-    try {
-      const fco: RequestInit = {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-          'X-Aggregation': 'yes'
-        },
-        body: JSON.stringify({ service: question.service, query: question.query }),
-        signal: controller?.signal
-      }
-      const response: Response = await this.fetchClient(`${url}/lookup`, fco)
+    // Hard wall-clock deadline: in some environments (e.g. browser/Electron CORS
+    // failures) the underlying fetch can stall without ever settling, and the
+    // AbortController signal alone is insufficient to make the returned promise
+    // resolve or reject. Race the fetch against a setTimeout-backed reject so
+    // the consumer-facing promise always settles within `timeout` ms.
+    const fetchPromise = this.performLookupRequest(url, question, controller?.signal)
+    // Swallow background rejection if the deadline wins first.
+    fetchPromise.catch(() => { /* noop */ })
 
-      if (!response.ok) throw new Error(`Failed to facilitate lookup (HTTP ${response.status})`)
-      if (response.headers.get('content-type') === 'application/octet-stream') {
-        return await this.parseOctetStreamLookup(response)
-      }
-      return await response.json()
+    try {
+      return await Promise.race([fetchPromise, deadline.promise])
     } catch (e) {
-      // Normalize timeouts to a consistent error message
-      if ((e as { name?: string })?.name === 'AbortError') {
-        throw new Error('Request timed out')
-      }
-      throw e
+      throw normalizeLookupError(e, deadline.didTimeOut())
     } finally {
-      clearTimeout(timer)
+      deadline.cancel()
+    }
+  }
+
+  private async performLookupRequest (
+    url: string,
+    question: LookupQuestion,
+    signal: AbortSignal | undefined
+  ): Promise<LookupAnswer> {
+    const fco: RequestInit = {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Aggregation': 'yes'
+      },
+      body: JSON.stringify({ service: question.service, query: question.query }),
+      signal
+    }
+    const response: Response = await this.fetchClient(`${url}/lookup`, fco)
+    if (!response.ok) throw new Error(`Failed to facilitate lookup (HTTP ${response.status})`)
+    if (isOctetStream(response.headers.get('content-type'))) {
+      return await this.parseOctetStreamLookup(response)
     }
+    return await response.json()
   }
 
   /** Parse the aggregated octet-stream lookup response into an output-list LookupAnswer. */