From fbff7da1853302905f599d358feb68346ce96438 Mon Sep 17 00:00:00 2001 From: Ty J Everett Date: Wed, 23 Sep 2026 20:52:29 -0700 Subject: [PATCH] fix(messagebox): consume published SDK 2.8.3 and document proxy contracts --- docs/reference/package-api-migrations.md | 8 ++++---- governance/package-release-notes.json | 8 ++++---- infra/message-box-server/DEPLOYING.md | 15 +++++++++++++++ infra/message-box-server/package-lock.json | 9 +++++---- infra/message-box-server/package.json | 2 +- 5 files changed, 29 insertions(+), 13 deletions(-) diff --git a/docs/reference/package-api-migrations.md b/docs/reference/package-api-migrations.md index 0fa5cf68b..e75fa44a9 100644 --- a/docs/reference/package-api-migrations.md +++ b/docs/reference/package-api-migrations.md @@ -3,8 +3,8 @@ id: package-api-migrations title: 'Package API, Declarations, and Migration Ledger' kind: reference version: '1.0.0' -last_updated: '2026-09-23' -last_verified: '2026-09-23' +last_updated: '2026-09-24' +last_verified: '2026-09-24' review_cadence_days: 30 status: stable tags: [reference, packages, api, declarations, migrations, release-notes] @@ -48,7 +48,7 @@ and clean-consumer tests remain the executable type authority. | `@bsv/overlay-topics` | `1.8.4` | `1.8.4` | none | [API and usage](../packages/overlays/overlay-topics.md) | Topic and lookup identifiers and valid canonical wire encodings remain unchanged. Audit historical rows for malformed amounts, noncanonical identifiers, incomplete ownership or admin evidence, and ambiguous outpoint linkage before replay or rebuild. Custom state and screening providers must return exact booleans, compare identity keys case-insensitively where documented, conserve exact safe-integer value, and honor bounded query and result contracts. | | `@bsv/paymail` | `2.4.9` | `2.4.10` | patch | [API and usage](../packages/messaging/paymail.md) | None. ESM consumers are unaffected. | | `@bsv/payment-express-middleware` | `2.1.7` | `2.1.7` | none | [API and usage](../packages/middleware/payment-express-middleware.md) | No wire or public API migration is required; legacy x-bsv-payment JSON behavior remains supported, and Express 4 and 5 applications use their own peer-provided Express installation. Wallet adapters must return accepted and optional isMerge as own data properties; inherited/accessor-backed verdicts now fail closed. Overinclusive Atomic BEEF receipts are normalized to the declared subject closure. Production replicas must share one durable atomic replay store, and operators must reconcile a replay-store failure after wallet acceptance before asking a payer to spend again. Distributors must retain THIRD_PARTY_NOTICES.md and LICENSES/ with the package. | -| `@bsv/sdk` | `2.8.2` | `2.8.3` | patch | [API and usage](../packages/sdk/bsv-sdk.md) | No application API, wire, account-data or wallet protocol migration is required. Applications affected by explicit-originator HTTP discovery or the browser JSON fallback can update their bundled SDK to 2.8.3 without changing calls. Wallets and affected 2.8.x binary clients should include this patch to restore signed action history. Existing older clients retain their original calls and wire bytes. This repairs SDK client and wire compatibility defects; wallet upgrades must continue supporting existing applications and do not require an ecosystem-wide SDK migration. Source 2.8.3 remains a candidate until the protected release workflow publishes it. | +| `@bsv/sdk` | `2.8.3` | `2.8.3` | none | [API and usage](../packages/sdk/bsv-sdk.md) | No application API, wire, account-data or wallet protocol migration is required. Applications affected by explicit-originator HTTP discovery or the browser JSON fallback can update their bundled SDK to 2.8.3 without changing calls. Wallets and affected 2.8.x binary clients should include this patch to restore signed action history. Existing older clients retain their original calls and wire bytes. This repairs SDK client and wire compatibility defects; wallet upgrades must continue supporting existing applications and do not require an ecosystem-wide SDK migration. Version 2.8.3 was published by the protected SDK-only release workflow with verified registry integrity and provenance. | | `@bsv/simple` | `0.6.0` | `0.6.0` | none | [API and usage](../packages/helpers/simple.md) | Replace createServerWalletHandler() deployments with createServerWalletHandler({ authorize: async ({ action, headers }) => authenticatedSessionCanUseAction(headers, action) }). The callback must return literal true for each status, create, request, receive, balance, outputs, or reset action; omission now returns HTTP 403 for every action. Roll out the authentication layer and callback with the package, update anonymous probes or automation, and apply the same policy to every replica. Do not emulate the old public behavior with an unconditional authorize: () => true callback. Valid recipient derivations and authenticated Message Box peers remain supported; malformed, wrong-owner, or transaction-mutated flows now fail closed. New DID, CredentialSchema, and Certifier records use canonical 32-byte types. Current SDK wallet methods reject historical short types, so do not put migration aliases in wallet list, acquire, prove, or relinquish calls. Export affected records through the storage version that created them, authenticate them offline against the exact locally configured identifier, and reissue/import canonical replacements; no legacy certificate is rewritten automatically. Distributors must retain THIRD_PARTY_NOTICES.md and LICENSES/. The internal comparator consolidation requires no migration and is included in the existing unpublished 0.6.0 candidate. | | `@bsv/templates` | `1.10.2` | `1.10.3` | patch | [API and usage](../packages/helpers/templates.md) | None. CommonJS consumers that patched 1.10.2 locally can drop the patch after upgrading to 1.10.3; ESM consumers are unaffected. | | `@bsv/teranode-listener` | `1.1.6` | `1.1.6` | none | [API and usage](../packages/network/teranode-listener.md) | No API migration is required for valid consumers: raw callbacks remain the default and decoding is opt-in with decodeMessages: true. Configuration arrays and callbacks are snapshotted at construction, boolean controls must be literal booleans, and malformed or duplicate topics, addresses, keys, and unsupported properties now fail closed. usePrivateDHT: false now actually omits the DHT service. The published mainnet PNET value is transport compatibility data, not a publisher credential; decoded sender and payload fields remain untrusted and security-critical claims require independent validation. Distributors must retain THIRD_PARTY_NOTICES.md and LICENSES/ with the package. | @@ -360,7 +360,7 @@ CLI entry points: `{"lch":"./dist/cli.js"}`. - Package documentation: [docs/packages/sdk/bsv-sdk.md](../packages/sdk/bsv-sdk.md) - Source: [packages/sdk](https://github.com/bsv-blockchain/ts-stack/tree/main/packages/sdk) - Release note: Preserves the configured BRC100 caller originator during automatic wallet discovery, so the HTTP WalletWire probe satisfies the existing transport caller binding. Binds the default HTTP JSON fetch receiver for browsers while retaining custom HTTP clients. Keeps transport preference, bounded discovery, operation timeout behavior, validation and origin checks unchanged. Restores signed listActions net amounts using their historical int64 wire encoding, matching existing JSON validation, while retaining canonical unsigned counts/lengths and nonnegative individual output values. -- Migration: No application API, wire, account-data or wallet protocol migration is required. Applications affected by explicit-originator HTTP discovery or the browser JSON fallback can update their bundled SDK to 2.8.3 without changing calls. Wallets and affected 2.8.x binary clients should include this patch to restore signed action history. Existing older clients retain their original calls and wire bytes. This repairs SDK client and wire compatibility defects; wallet upgrades must continue supporting existing applications and do not require an ecosystem-wide SDK migration. Source 2.8.3 remains a candidate until the protected release workflow publishes it. +- Migration: No application API, wire, account-data or wallet protocol migration is required. Applications affected by explicit-originator HTTP discovery or the browser JSON fallback can update their bundled SDK to 2.8.3 without changing calls. Wallets and affected 2.8.x binary clients should include this patch to restore signed action history. Existing older clients retain their original calls and wire bytes. This repairs SDK client and wire compatibility defects; wallet upgrades must continue supporting existing applications and do not require an ecosystem-wide SDK migration. Version 2.8.3 was published by the protected SDK-only release workflow with verified registry integrity and provenance. | Public subpath | Runtime target(s) | Declaration target(s) | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | diff --git a/governance/package-release-notes.json b/governance/package-release-notes.json index cf48889f8..3aaeb3f63 100644 --- a/governance/package-release-notes.json +++ b/governance/package-release-notes.json @@ -1,6 +1,6 @@ { "schemaVersion": 1, - "lastReviewed": "2026-09-23", + "lastReviewed": "2026-09-24", "owner": "ts-stack-maintainers", "entries": [ { @@ -166,10 +166,10 @@ }, { "name": "@bsv/sdk", - "publishedVersion": "2.8.2", - "releaseType": "patch", + "publishedVersion": "2.8.3", + "releaseType": "none", "summary": "Preserves the configured BRC100 caller originator during automatic wallet discovery, so the HTTP WalletWire probe satisfies the existing transport caller binding. Binds the default HTTP JSON fetch receiver for browsers while retaining custom HTTP clients. Keeps transport preference, bounded discovery, operation timeout behavior, validation and origin checks unchanged. Restores signed listActions net amounts using their historical int64 wire encoding, matching existing JSON validation, while retaining canonical unsigned counts/lengths and nonnegative individual output values.", - "migration": "No application API, wire, account-data or wallet protocol migration is required. Applications affected by explicit-originator HTTP discovery or the browser JSON fallback can update their bundled SDK to 2.8.3 without changing calls. Wallets and affected 2.8.x binary clients should include this patch to restore signed action history. Existing older clients retain their original calls and wire bytes. This repairs SDK client and wire compatibility defects; wallet upgrades must continue supporting existing applications and do not require an ecosystem-wide SDK migration. Source 2.8.3 remains a candidate until the protected release workflow publishes it." + "migration": "No application API, wire, account-data or wallet protocol migration is required. Applications affected by explicit-originator HTTP discovery or the browser JSON fallback can update their bundled SDK to 2.8.3 without changing calls. Wallets and affected 2.8.x binary clients should include this patch to restore signed action history. Existing older clients retain their original calls and wire bytes. This repairs SDK client and wire compatibility defects; wallet upgrades must continue supporting existing applications and do not require an ecosystem-wide SDK migration. Version 2.8.3 was published by the protected SDK-only release workflow with verified registry integrity and provenance." }, { "name": "@bsv/simple", diff --git a/infra/message-box-server/DEPLOYING.md b/infra/message-box-server/DEPLOYING.md index e346abb50..3ea2d1c86 100644 --- a/infra/message-box-server/DEPLOYING.md +++ b/infra/message-box-server/DEPLOYING.md @@ -172,6 +172,21 @@ separate session manager and cannot substitute for the durable HTTP check. ## Ingress and timeouts +For multiple replicas, preserve Engine.IO polling session affinity: every +request for one transport session must reach its originating process. Use a +load-balancer policy that works with existing credential-free cross-domain +clients, such as source-IP affinity; requiring a new third-party routing cookie +would force a client migration. Test authenticated polling and WebSocket +connections separately. Affinity is transport routing, not authentication or +durable session failover; clients reconnect after endpoint withdrawal. + +Configure the proxy's idle upstream HTTP connection lifetime below the server's +five-second keep-alive timeout (for example, four seconds). Otherwise a proxy +can reuse a connection at the server's close boundary and return an intermittent +503 before an application response. Keep active-request and WebSocket stream +timeouts separate and sufficiently long. Do not add automatic payment-request +retries as a substitute for correct connection lifecycle settings. + The image serves HTTP and WebSocket traffic directly on `PORT` (8080 by default). Put the platform ingress or load balancer in front of the container and keep its ceilings aligned with the application: diff --git a/infra/message-box-server/package-lock.json b/infra/message-box-server/package-lock.json index 1888b6006..4e447ff5f 100644 --- a/infra/message-box-server/package-lock.json +++ b/infra/message-box-server/package-lock.json @@ -12,7 +12,7 @@ "@bsv/auth-express-middleware": "^2.2.5", "@bsv/authsocket": "^2.1.8", "@bsv/payment-express-middleware": "^2.1.7", - "@bsv/sdk": "^2.8.2", + "@bsv/sdk": "^2.8.3", "@bsv/wallet-toolbox": "^2.14.0", "@opentelemetry/api": "^1.9.1", "@opentelemetry/api-logs": "^0.221.0", @@ -756,9 +756,9 @@ } }, "node_modules/@bsv/sdk": { - "version": "2.8.2", - "resolved": "https://registry.npmjs.org/@bsv/sdk/-/sdk-2.8.2.tgz", - "integrity": "sha512-3C4YOYccXDgtgyw0f4V0IZgzs4H8EutzMMbk230/KAzZ2dpbXqang5tCmhoYmtAtuA7BTYK4tMrM3YH8dDwH0A==", + "version": "2.8.3", + "resolved": "https://registry.npmjs.org/@bsv/sdk/-/sdk-2.8.3.tgz", + "integrity": "sha512-zpxPThcecDkuVqHwo5oUrLx9B0Z5CyHhL+Rq0BH35UU7sBcwGo3lYGEzl5NGR43tqBYER7L7aE2xF/CJPBrYDQ==", "license": "SEE LICENSE IN LICENSE.txt", "engines": { "node": ">=22" @@ -5553,6 +5553,7 @@ "version": "13.0.2", "resolved": "https://registry.npmjs.org/better-sqlite3/-/better-sqlite3-13.0.2.tgz", "integrity": "sha512-jW6oufeDhXZaiX9Lw5A+oerVClx4iFrI6uDj1zu7SqUAjak9vbJvA0NEcKLNxHiQHb6kYCoFzzXYV0YOauhV3g==", + "hasInstallScript": true, "license": "MIT", "dependencies": { "node-addon-api": "^8.0.0" diff --git a/infra/message-box-server/package.json b/infra/message-box-server/package.json index 263a189bc..73aac2220 100644 --- a/infra/message-box-server/package.json +++ b/infra/message-box-server/package.json @@ -69,7 +69,7 @@ "@bsv/auth-express-middleware": "^2.2.5", "@bsv/authsocket": "^2.1.8", "@bsv/payment-express-middleware": "^2.1.7", - "@bsv/sdk": "^2.8.2", + "@bsv/sdk": "^2.8.3", "@bsv/wallet-toolbox": "^2.14.0", "@opentelemetry/api": "^1.9.1", "@opentelemetry/api-logs": "^0.221.0",