feat(sdk): add new socketOptions optional param on MessageBoxClient

docs/about/contributing.md

@@ -4,7 +4,7 @@ title: 'Contributing'
 kind: meta
 version: '2.0.0'
 last_updated: '2026-07-30'
-last_verified: '2026-07-30'
+last_verified: '2026-08-30'
 review_cadence_days: 30
 status: stable
 tags: [about, contributing, development, community]

docs/about/doc-agent.md

@@ -4,7 +4,7 @@ title: 'Documentation Maintenance'
 kind: meta
 version: '2.1.0'
 last_updated: '2026-07-30'
-last_verified: '2026-07-30'
+last_verified: '2026-08-30'
 review_cadence_days: 30
 status: stable
 tags: [about, documentation, maintenance, automation]

docs/infrastructure/service-edge-security.md

@@ -4,7 +4,7 @@ title: 'Public Service Edge Security'
 kind: reference
 version: '1.0.0'
 last_updated: '2026-07-30'
-last_verified: '2026-07-30'
+last_verified: '2026-08-30'
 review_cadence_days: 30
 status: stable
 tags: [infrastructure, security, cors, rate-limits, authentication, operations]

docs/packages/messaging/message-box-client.md

@@ -3,10 +3,10 @@ id: pkg-message-box-client
 title: '@bsv/message-box-client'
 kind: package
 domain: messaging
-version: '2.4.2'
+version: '2.5.0'
 source_repo: 'bsv-blockchain/ts-stack'
-last_updated: '2026-08-26'
-last_verified: '2026-08-26'
+last_updated: '2026-08-31'
+last_verified: '2026-08-31'
 review_cadence_days: 30
 npm: 'https://www.npmjs.com/package/@bsv/message-box-client'
 repo: 'https://github.com/bsv-blockchain/ts-stack/tree/main/packages/messaging/message-box-client'
@@ -61,7 +61,8 @@ is useful.
 
 ## What it provides
 
-- `MessageBoxClient` — authenticated HTTP polling and live WebSocket delivery
+- `MessageBoxClient` — authenticated HTTP polling and live WebSocket delivery,
+  with selectable socket transports
 - encryption through the BRC-100 wallet protocol, enabled by default
 - overlay host advertisement and public-HTTPS discovery
 - sender-specific and box-wide permissions with fee quotes

docs/reference/ci-performance.md

@@ -4,7 +4,7 @@ title: 'CI Performance Governance'
 kind: reference
 version: '1.1.0'
 last_updated: '2026-07-31'
-last_verified: '2026-07-31'
+last_verified: '2026-08-30'
 review_cadence_days: 30
 status: stable
 tags: [reference, ci, performance, github-actions]

docs/reference/dependency-policy.md

@@ -3,8 +3,8 @@ id: dependency-release-policy
 title: 'Dependency and Release Policy'
 kind: reference
 version: '1.3.0'
-last_updated: '2026-08-04'
-last_verified: '2026-08-04'
+last_updated: '2026-08-30'
+last_verified: '2026-08-30'
 review_cadence_days: 30
 status: stable
 tags: [reference, dependencies, security, releases]

docs/reference/index.md

@@ -4,7 +4,7 @@ title: 'Reference'
 kind: meta
 version: 'n/a'
 last_updated: '2026-07-29'
-last_verified: '2026-07-29'
+last_verified: '2026-08-30'
 review_cadence_days: 30
 status: stable
 tags: [reference, api, index]

docs/reference/release-operations.md

@@ -4,7 +4,7 @@ title: 'Release and Operations Guide'
 kind: reference
 version: '1.1.2'
 last_updated: '2026-07-30'
-last_verified: '2026-07-30'
+last_verified: '2026-08-30'
 review_cadence_days: 30
 status: stable
 tags: [reference, releases, operations, rollback, npm, containers]

docs/reference/stack-facts.md

@@ -3,8 +3,8 @@ id: stack-facts
 title: 'Generated Stack Facts'
 kind: reference
 version: '1.0.0'
-last_updated: '2026-07-30'
-last_verified: '2026-07-30'
+last_updated: '2026-08-30'
+last_verified: '2026-08-30'
 review_cadence_days: 30
 status: stable
 tags: [reference, packages, versions, runtimes, conformance, generated]
@@ -48,7 +48,7 @@ authorized release action.
 | helpers | `create-bsv-app` | `1.1.1` | cli | cli | node | `>=22` | [packages/helpers/create-bsv-app](https://github.com/bsv-blockchain/ts-stack/tree/main/packages/helpers/create-bsv-app) |
 | messaging | `@bsv/authsocket` | `2.1.7` | node-library | node-cjs, node-esm | node | `>=22` | [packages/messaging/authsocket](https://github.com/bsv-blockchain/ts-stack/tree/main/packages/messaging/authsocket) |
 | messaging | `@bsv/authsocket-client` | `2.1.6` | browser-library | browser-bundler, browser-esm, node-cjs, node-esm, umd-global | browser, node, umd | `>=22` | [packages/messaging/authsocket-client](https://github.com/bsv-blockchain/ts-stack/tree/main/packages/messaging/authsocket-client) |
-| messaging | `@bsv/message-box-client` | `2.4.2` | browser-library | browser-bundler, browser-esm, node-cjs, node-esm, umd-global | browser, node, umd | `>=22` | [packages/messaging/message-box-client](https://github.com/bsv-blockchain/ts-stack/tree/main/packages/messaging/message-box-client) |
+| messaging | `@bsv/message-box-client` | `2.5.0` | browser-library | browser-bundler, browser-esm, node-cjs, node-esm, umd-global | browser, node, umd | `>=22` | [packages/messaging/message-box-client](https://github.com/bsv-blockchain/ts-stack/tree/main/packages/messaging/message-box-client) |
 | messaging | `@bsv/paymail` | `2.4.7` | browser-library | browser-bundler, browser-esm, node-cjs, node-esm | browser, node | `>=22` | [packages/messaging/ts-paymail](https://github.com/bsv-blockchain/ts-stack/tree/main/packages/messaging/ts-paymail) |
 | middleware | `@bsv/402-pay` | `0.2.5` | browser-library | browser-bundler, browser-esm, node-cjs, node-esm | browser, node | `>=22` | [packages/middleware/402-pay](https://github.com/bsv-blockchain/ts-stack/tree/main/packages/middleware/402-pay) |
 | middleware | `@bsv/auth` | `0.1.4` | node-library | node-cjs, node-esm | node | `>=22` | [packages/middleware/auth](https://github.com/bsv-blockchain/ts-stack/tree/main/packages/middleware/auth) |

docs/reference/typescript-toolchain.md

@@ -4,7 +4,7 @@ title: 'TypeScript Compiler and Tooling Boundary'
 kind: reference
 version: '1.1.0'
 last_updated: '2026-07-29'
-last_verified: '2026-07-29'
+last_verified: '2026-08-30'
 review_cadence_days: 30
 status: stable
 tags: [reference, typescript, compiler, testing, toolchain]

docs/specs/air-gap-optical.md

@@ -4,7 +4,7 @@ title: Air-Gap Optical Transport (BRC-141)
 kind: spec
 version: '1.0.0'
 last_updated: '2026-07-30'
-last_verified: '2026-07-30'
+last_verified: '2026-08-30'
 review_cadence_days: 30
 status: experimental
 tags: ['spec', 'transport', 'air-gap', 'qr', 'optical']

governance/dependency-release-policy.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "lastReviewed": "2026-08-13",
+  "lastReviewed": "2026-08-30",
   "owner": "ts-stack-maintainers",
   "routineUpdates": {
     "dependabotConfig": ".github/dependabot.yml",
@@ -49,7 +49,7 @@
         "classification": "toolchain-bridge",
         "rationale": "TypeScript 7 owns every native CLI build while compiler-API consumers use the official TypeScript 6 compatibility package until a stable TypeScript 7 API exists.",
         "owner": "ts-stack-maintainers",
-        "reviewBy": "2026-08-27",
+        "reviewBy": "2026-09-30",
         "removeWhen": "All compiler-API consumers support the native TypeScript 7 API and the complete declaration, Jest, conformance, browser, mobile, infrastructure, and packed-consumer matrix passes without the alias."
       },
       {
@@ -128,7 +128,7 @@
         "classification": "coordinated-major-hold",
         "rationale": "The isolated OpenAPI code generator is pinned to its tested compiler API and generated-output reproducibility boundary.",
         "owner": "ts-stack-maintainers",
-        "reviewBy": "2026-08-25",
+        "reviewBy": "2026-09-30",
         "removeWhen": "The generator and Redocly closure support the new compiler and deterministic codegen remains byte-for-byte clean."
       }
     ]
@@ -144,10 +144,10 @@
     "closeImplementationWaveAfterPublication": false
   },
   "overrideRemovalReview": {
-    "reviewedAt": "2026-08-13",
-    "method": "Rechecked all retained root and standalone overrides against their current natural dependency graphs, refreshed the root lock against the current advisory database, and reproduced the updated nanoid and image-size findings before selecting the narrowest compatible override and committed parser patch.",
+    "reviewedAt": "2026-08-30",
+    "method": "Rechecked all 20 registered root, standalone, and isolated-codegen selectors against the frozen dependency graphs, current upstream package manifests, and the current advisory audit. The exact gcp-metadata 8.1.4 dependency still selects gaxios 7.1.3, teeny-request 9.0.0 still admits uuid 9, and typed-rest-client 2.3.1 still pins qs 6.15.1.",
     "retainedCount": 20,
-    "result": "Every remaining override still prevents a reproduced vulnerable transitive version or preserves the isolated reproducible codegen closure. The nanoid override selects 3.3.18, the first 3.x release patched after GHSA-2v37-7h3g-55p8 was expanded on 2026-08-13. No override can be removed safely in this wave.",
+    "result": "Every remaining override still prevents a vulnerable natural resolution or preserves the isolated reproducible codegen closure. Current upstream majors can remove some legacy paths only through coordinated Stryker or Google Cloud migrations, not by deleting an override from the supported graph. No selector can be removed safely in this review.",
     "nextReview": "Rehearse removal monthly and immediately after upstream Google client, Jest/minimatch, typed-rest-client, Redocly, AJV, express-rate-limit, Socket.IO, Vite/PostCSS, Metro, or image-size dependency changes."
   },
   "overrideRegistry": [

governance/documentation-policy.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "owner": "ts-stack-maintainers",
-  "lastReviewed": "2026-07-30",
+  "lastReviewed": "2026-08-30",
   "programHistory": "https://github.com/bsv-blockchain/ts-stack/issues/324",
   "contributionAuthority": "CONTRIBUTING.md",
   "activeFollowUps": {

governance/package-release-notes.json

@@ -104,9 +104,9 @@
     {
       "name": "@bsv/message-box-client",
       "publishedVersion": "2.4.0",
-      "releaseType": "patch",
-      "summary": "Preserves BRC-29 payments, paid messages, remittances, and peer tokens across binary Wallet Wire results and historical numeric-key JSON payloads, rejects sparse or invalid byte records, and ships the complete SDK incorporated-material notice archive with a retained UMD notice banner. Standardizes first-party author metadata on the current BSV Association name.",
-      "migration": "No API migration is required. Upgrade @bsv/sdk and @bsv/message-box-client together; historical number-array wallets, current Uint8Array substrates, and already-pending numeric-key messages interoperate through the same portable transaction form. Distributors who copy the UMD file must keep THIRD_PARTY_NOTICES.md and LICENSES/ with it."
+      "releaseType": "minor",
+      "summary": "Adds an optional socketOptions client option that forwards the AuthSocketClient options other than wallet and originator, letting callers select Socket.IO transports such as websocket-only against deployments that do not carry Engine.IO HTTP polling, and reach certificate requests, session management, auth-message concurrency, and error reporting. Also preserves BRC-29 payments, paid messages, remittances, and peer tokens across binary Wallet Wire results and historical numeric-key JSON payloads, rejects sparse or invalid byte records, and ships the complete SDK incorporated-material notice archive with a retained UMD notice banner. Standardizes first-party author metadata on the current BSV Association name.",
+      "migration": "No API migration is required. socketOptions is optional and nothing is forwarded by default, so socket transport negotiation and every HTTP code path are unchanged for existing callers; wallet and originator stay client-owned and cannot be overridden through it. Upgrade @bsv/sdk and @bsv/message-box-client together; historical number-array wallets, current Uint8Array substrates, and already-pending numeric-key messages interoperate through the same portable transaction form. Distributors who copy the UMD file must keep THIRD_PARTY_NOTICES.md and LICENSES/ with it."
     },
     {
       "name": "@bsv/overlay",

governance/repository-health/baselines.json

@@ -309,7 +309,7 @@
     "@bsv/templates": "1.10.1",
     "@bsv/authsocket": "2.1.7",
     "@bsv/authsocket-client": "2.1.6",
-    "@bsv/message-box-client": "2.4.2",
+    "@bsv/message-box-client": "2.5.0",
     "@bsv/paymail": "2.4.7",
     "@bsv/402-pay": "0.2.5",
     "@bsv/auth": "0.1.4",

governance/repository-health/exceptions.json

@@ -49,7 +49,7 @@
         ".github/dependabot.yml"
       ],
       "created": "2026-07-27",
-      "reviewBy": "2026-08-27",
+      "reviewBy": "2026-09-30",
       "removeWhen": "Remove after TypeScript exposes a stable native API, every compiler-API consumer supports it without an override, and the full build, typecheck, declaration, packed-consumer, Jest, conformance, browser/mobile, and infrastructure matrix passes without @typescript/typescript6."
     },
     {
@@ -105,7 +105,7 @@
         "https://github.com/bsv-blockchain/ts-stack/issues/324"
       ],
       "created": "2026-07-29",
-      "reviewBy": "2026-08-28",
+      "reviewBy": "2026-09-30",
       "removeWhen": "Remove service by service when its complete supported Google and OpenTelemetry graph natively resolves gaxios 7.3.0 or newer and frozen audit, build, test, and Linux image checks remain green without the substitution."
     },
     {
@@ -124,7 +124,7 @@
         "https://github.com/bsv-blockchain/ts-stack/issues/324"
       ],
       "created": "2026-07-29",
-      "reviewBy": "2026-08-28",
+      "reviewBy": "2026-09-30",
       "removeWhen": "Remove from each remaining service when its supported cloud client closure natively resolves uuid 11.1.1 or newer and frozen audit, build, test, and Linux image checks remain green without the substitution."
     },
     {
@@ -140,7 +140,7 @@
         "https://github.com/bsv-blockchain/ts-stack/issues/324"
       ],
       "created": "2026-07-27",
-      "reviewBy": "2026-08-27",
+      "reviewBy": "2026-09-30",
       "removeWhen": "Remove when Stryker no longer depends on typed-rest-client 2.3.1 or a supported typed-rest-client release natively depends on qs 6.15.2 or newer, then regenerate the lock and rerun the complete mutation campaign."
     },
     {

governance/test-quality/wallet-toolbox-manual-suites.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
-  "lastReviewed": "2026-07-29",
+  "lastReviewed": "2026-08-30",
   "owner": "ts-stack-maintainers",
-  "reviewBy": "2026-08-29",
+  "reviewBy": "2026-09-30",
   "suites": [
     {
       "path": "packages/wallet/wallet-toolbox/src/services/__tests/ARC.man.test.ts",

packages/messaging/message-box-client/CHANGELOG.md

@@ -15,6 +15,18 @@ All notable changes to this project will be documented in this file. The format
 
 ### Added
 
+- Added an optional `socketOptions` client option, forwarded to
+  `AuthSocketClient` when the live socket is created. It carries the
+  `AuthSocketClient` options other than `wallet` and `originator`, which the
+  client owns, so callers can select Socket.IO transports (for example
+  `{ managerOptions: { transports: ['websocket'] } }`) to reach deployments that
+  do not carry Engine.IO's HTTP polling transport, and can also supply
+  `requestedCertificates`, `sessionManager`, `maxPendingAuthMessages`, and
+  `onError`. `managerOptions.autoConnect` is excluded and rejected: the socket is
+  started when it is created, so disabling auto-connect could never connect.
+  Nothing is forwarded when unset, so default transport negotiation and all HTTP
+  code paths are unchanged.
+
 - Added the `teratestnet` overlay preset. TTN clients must provide an explicit
   Message Box host until a dedicated TTN deployment is available, preventing
   accidental use of the existing testnet staging service.

packages/messaging/message-box-client/README.md

@@ -121,6 +121,41 @@ await messages.sendLiveMessage({
 send route when the socket is unavailable or does not acknowledge delivery.
 Call `disconnectWebSocket()` when a long-lived client shuts down.
 
+### Socket options
+
+`socketOptions` is forwarded to the underlying `AuthSocketClient` when the live
+socket is created. Use it to select Socket.IO transports when a deployment's
+fronting infrastructure does not carry Engine.IO HTTP polling:
+
+```ts
+const messages = new MessageBoxClient({
+  walletClient: wallet,
+  host: 'https://messagebox.example',
+  socketOptions: { managerOptions: { transports: ['websocket'] } }
+})
+
+await messages.listenForLiveMessages({
+  messageBox: 'general_inbox',
+  onMessage: message => {
+    console.log(message.sender, message.body)
+  }
+})
+```
+
+It also carries `requestedCertificates`, `sessionManager`,
+`maxPendingAuthMessages`, and `onError`.
+
+Three fields are excluded from the type. `wallet` and `originator` are owned by
+the client, which always uses its own values. `managerOptions.autoConnect` is
+excluded because the socket connects when it is created and `AuthSocketClient`
+exposes no way to start one later, so disabling auto-connect could never
+connect; the constructor throws if it is passed as `false`.
+
+`socketOptions` applies **only to the live socket path** — `initializeConnection()`,
+`listenForLiveMessages()`, and `sendLiveMessage()`. It has no effect on
+`sendMessage()`, `listMessages()`, or `acknowledgeMessage()`, which use
+authenticated HTTP.
+
 ## Host selection and public-service access
 
 An explicitly configured host may use HTTP or HTTPS so local development and

packages/messaging/message-box-client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsv/message-box-client",
-  "version": "2.4.2",
+  "version": "2.5.0",
   "sideEffects": false,
   "engines": {
     "node": ">=22"

packages/messaging/message-box-client/src/MessageBoxClient.ts

@@ -211,13 +211,15 @@ export class MessageBoxClient {
   private socketAuthenticated = false
   private connectionInitPromise?: Promise<void>
   protected originator?: OriginatorDomainNameStringUnder250Bytes
+  private readonly socketOptions: MessageBoxClientOptions['socketOptions']
   /**
    * @constructor
    * @param {Object} options - Initialization options for the MessageBoxClient.
    * @param {string} [options.host] - The base URL of the MessageBox server. Required for TerraTestNet until a dedicated TTN deployment is available.
    * @param {WalletInterface} options.walletClient - Wallet instance used for authentication, signing, and encryption.
    * @param {boolean} [options.enableLogging=false] - Whether to enable detailed debug logging to the console.
    * @param {'local' | 'mainnet' | 'testnet' | 'teratestnet'} [options.networkPreset='mainnet'] - Overlay network preset used for routing and advertisement lookup.
+   * @param {Omit<AuthSocketClientOptions, 'wallet' | 'originator'>} [options.socketOptions] - Options forwarded to the underlying AuthSocketClient, e.g. `{ managerOptions: { transports: ['websocket'] } }`. The client's own wallet and originator always win.
    *
    * @description
    * Constructs a new MessageBoxClient.
@@ -241,7 +243,8 @@ export class MessageBoxClient {
       walletClient,
       enableLogging = false,
       networkPreset = 'mainnet',
-      originator = undefined
+      originator = undefined,
+      socketOptions = undefined
     } = options
 
     if (networkPreset === 'teratestnet' && host == null) {
@@ -257,6 +260,17 @@ export class MessageBoxClient {
 
     this.host = normalizeMessageBoxHost(host ?? defaultHost)
     this.originator = originator
+    // autoConnect is excluded from the forwarded type, so this guard exists for
+    // JavaScript callers who reach past it.
+    const forwardedManagerOptions = socketOptions?.managerOptions as
+      { autoConnect?: boolean } | undefined
+    if (forwardedManagerOptions?.autoConnect === false) {
+      throw new Error(
+        '[MB CLIENT ERROR] socketOptions.managerOptions.autoConnect must not be false: ' +
+          'the live socket is started when it is created and cannot be connected later.'
+      )
+    }
+    this.socketOptions = socketOptions
     this.walletClient = walletClient ?? new WalletClient('auto', originator)
     this.authFetch = new AuthFetch(this.walletClient, undefined, undefined, originator)
     this.networkPreset = networkPreset
@@ -435,6 +449,7 @@ export class MessageBoxClient {
     if (this.socket == null) {
       const targetHost = normalizeMessageBoxHost(overrideHost ?? this.host)
       this.socket = AuthSocketClient(targetHost, {
+        ...this.socketOptions,
         wallet: this.walletClient,
         originator: this.originator
       })