diff --git a/docs/about/contributing.md b/docs/about/contributing.md index bb29d394a..25a931237 100644 --- a/docs/about/contributing.md +++ b/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] diff --git a/docs/about/doc-agent.md b/docs/about/doc-agent.md index ab2312b72..92d5e578c 100644 --- a/docs/about/doc-agent.md +++ b/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] diff --git a/docs/infrastructure/service-edge-security.md b/docs/infrastructure/service-edge-security.md index fb5b333da..a79bdc54b 100644 --- a/docs/infrastructure/service-edge-security.md +++ b/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] diff --git a/docs/packages/messaging/message-box-client.md b/docs/packages/messaging/message-box-client.md index 592e07c9c..d0cd9e3b4 100644 --- a/docs/packages/messaging/message-box-client.md +++ b/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 diff --git a/docs/reference/ci-performance.md b/docs/reference/ci-performance.md index 676258af2..373f87ade 100644 --- a/docs/reference/ci-performance.md +++ b/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] diff --git a/docs/reference/dependency-policy.md b/docs/reference/dependency-policy.md index 8c6453b7d..e1ae585e5 100644 --- a/docs/reference/dependency-policy.md +++ b/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] diff --git a/docs/reference/index.md b/docs/reference/index.md index 5afdbd330..5cff88055 100644 --- a/docs/reference/index.md +++ b/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] diff --git a/docs/reference/package-api-migrations.md b/docs/reference/package-api-migrations.md index cebeddc95..9ee9e1ab5 100644 --- a/docs/reference/package-api-migrations.md +++ b/docs/reference/package-api-migrations.md @@ -23,40 +23,40 @@ and clean-consumer tests remain the executable type authority. ## Current release boundary -| Package | npm baseline | Source | Candidate | API | Migration | -| --------------------------------- | ------------ | -------- | --------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `@bsv/402-pay` | `0.2.1` | `0.2.5` | patch | [API and usage](../packages/middleware/402-pay.md) | No consumer migration is required; client and server exports, payment protocol behavior, and runtime defaults are unchanged. Distributors must retain THIRD_PARTY_NOTICES.md and LICENSES/ with the package. | -| `@bsv/air-gap` | `0.0.0` | `0.1.2` | minor | [API and usage](../packages/helpers/air-gap.md) | No consumer migration is required; this is the first published release of a new package with no prior public API. The experimental pre-release framing that circulated on the unmerged feature branch is not accepted by the v1 decoder. | -| `@bsv/amountinator` | `2.1.1` | `2.1.5` | patch | [API and usage](../packages/helpers/amountinator.md) | No consumer migration is required; this is a backward-compatible patch candidate. | -| `@bsv/auth` | `0.1.1` | `0.1.4` | patch | [API and usage](../packages/middleware/auth.md) | No consumer migration is required; authentication APIs, wire behavior, and runtime defaults are unchanged. | -| `@bsv/auth-express-middleware` | `2.2.0` | `2.2.3` | patch | [API and usage](../packages/middleware/auth-express-middleware.md) | No API migration is required. Upgrade to @bsv/sdk 2.4.1 or later for the shared byte-boundary contract. Generic signed application-body canonicalization remains unchanged so old and new peers verify identical bytes. Distributors must retain THIRD_PARTY_NOTICES.md and LICENSES/ with the package. | -| `@bsv/authsocket` | `2.1.1` | `2.1.7` | patch | [API and usage](../packages/messaging/authsocket.md) | No API migration is required. Existing event data, including numeric-key objects under byte-like names, is unchanged; typed payment protocols recover historical byte objects at their explicit fields. Distributors must retain THIRD_PARTY_NOTICES.md and LICENSES/ with the package. | -| `@bsv/authsocket-client` | `2.1.1` | `2.1.6` | patch | [API and usage](../packages/messaging/authsocket-client.md) | No API migration is required. Existing event data, including numeric-key objects under byte-like names, is unchanged; typed payment protocols recover historical byte objects at their explicit fields. Distributors who copy the UMD file must keep THIRD_PARTY_NOTICES.md and LICENSES/ with it. | -| `@bsv/btms` | `1.1.1` | `1.2.2` | minor | [API and usage](../packages/wallet/btms.md) | Existing local, mainnet, testnet, and number-array behavior is unchanged. TTN consumers select networkPreset teratestnet; all consumers should upgrade to @bsv/sdk 2.4.1 or later for byte-boundary compatibility. | -| `@bsv/btms-permission-module` | `1.1.1` | `1.1.4` | patch | [API and usage](../packages/wallet/btms-permission-module.md) | No consumer migration is required; permission-module APIs and token semantics are unchanged. | -| `@bsv/chirp` | `0.0.0` | `0.1.1` | minor | [API and usage](../packages/network/chirp.md) | No consumer migration is required; this is the first release of a new additive package. Existing @bsv/sdk StorageUploader, StorageDownloader, StorageUtils, UHRP identifiers, overlays, and server routes remain unchanged. BRC-167 remains authoritative if the implementation and standard differ. | -| `@bsv/did` | `0.2.1` | `0.2.5` | patch | [API and usage](../packages/helpers/did.md) | No consumer migration is required; DID APIs, encodings, credential behavior, and supported import forms are unchanged. | -| `@bsv/did-client` | `1.2.1` | `1.3.1` | minor | [API and usage](../packages/helpers/did-client.md) | Existing local, mainnet, and testnet behavior is unchanged. TTN consumers select networkPreset teratestnet and use @bsv/sdk 2.4 or later. Distributors who copy the UMD file must keep THIRD_PARTY_NOTICES.md and LICENSES/ with it. | -| `@bsv/fund-wallet` | `1.4.1` | `1.4.4` | patch | [API and usage](../packages/helpers/fund-wallet.md) | No consumer migration is required; wallet funding APIs and transaction behavior are unchanged. Distributors must retain THIRD_PARTY_NOTICES.md and LICENSES/ with the package. | -| `@bsv/gasp` | `1.3.1` | `1.3.6` | patch | [API and usage](../packages/overlays/gasp.md) | No consumer migration is required; existing constructor calls, imports, synchronization behavior, and wire semantics are unchanged. Distributors must retain THIRD_PARTY_NOTICES.md and LICENSES/ with the package. | -| `@bsv/message-box-client` | `2.4.0` | `2.4.2` | patch | [API and usage](../packages/messaging/message-box-client.md) | 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. | -| `@bsv/overlay` | `2.2.1` | `2.3.1` | minor | [API and usage](../packages/overlays/overlay.md) | Existing Engine and TopicManager implementations remain valid. Lookup results default to 1,000 formulas; pass -1 only when an equivalent deployment bound exists. Topic managers whose validation creates provisional external state should implement abortAdmissibleOutputs, while read-only managers require no change. Distributors must retain THIRD_PARTY_NOTICES.md and LICENSES/ with the package. | -| `@bsv/overlay-discovery-services` | `2.1.1` | `2.2.1` | minor | [API and usage](../packages/overlays/overlay-discovery-services.md) | Existing mainnet and testnet advertisers are unchanged. TTN operators pass chain ttn and provision the staging storage and overlay endpoints before advertising. Distributors must retain THIRD_PARTY_NOTICES.md and LICENSES/ with the package. | -| `@bsv/overlay-express` | `2.5.0` | `2.6.1` | minor | [API and usage](../packages/overlays/overlay-express.md) | Existing mainnet and testnet servers are unchanged. TTN servers call configureNetwork('ttn'), configureArcade with the TTN endpoint, and configureChaintracks or configureChainTracker before engine initialization. Distributors must retain THIRD_PARTY_NOTICES.md and LICENSES/ with the package. | -| `@bsv/overlay-topics` | `1.6.10` | `1.7.1` | minor | [API and usage](../packages/overlays/overlay-topics.md) | Existing topic and lookup identifiers remain unchanged. Production UMP overlays must give UMPTopicManager and the UMP lookup service Mongo-backed stores that use the same database, then roll out before updated wallet clients; the no-argument manager is bounded but intended only for isolated single-process use. The reservation and bootstrap-marker collections are additive and initialize from currently indexed UMP UTXOs; take a MongoDB backup before rollout. Legacy ambiguous rows remain visible and can be resolved with WAB pinning rather than deleted. | -| `@bsv/paymail` | `2.4.2` | `2.4.7` | patch | [API and usage](../packages/messaging/paymail.md) | Existing Paymail client APIs and protocol semantics are retained. Consumers provide one Express 4.18 or 5 runtime and matching type graph; browser bundles continue to exclude the server router implementation. Consumers of the former bundled Money Button or Tokenized specification documents must follow the authoritative links in docs/specs/README.md. Distributors must retain THIRD_PARTY_NOTICES.md and LICENSES/ with the package. | -| `@bsv/payment-express-middleware` | `2.1.1` | `2.1.6` | patch | [API and usage](../packages/middleware/payment-express-middleware.md) | No consumer migration is required; legacy x-bsv-payment JSON behavior remains supported, and Express 4 and 5 applications use their own peer-provided Express installation. Distributors must retain THIRD_PARTY_NOTICES.md and LICENSES/ with the package. | -| `@bsv/sdk` | `2.4.0` | `2.4.2` | patch | [API and usage](../packages/sdk/bsv-sdk.md) | No API migration is required. Historical number-array fast paths and React Native behavior remain compatible. Documentation users should load docs/swagger/swagger.yaml into their preferred viewer instead of using the removed static Swagger UI scaffold. Distributors must keep THIRD_PARTY_NOTICES.md and LICENSES/ with source and browser bundles. | -| `@bsv/simple` | `0.4.1` | `0.5.2` | minor | [API and usage](../packages/helpers/simple.md) | Existing overlay configurations and number-array behavior are unchanged. TTN consumers select network teratestnet; all consumers should upgrade to @bsv/sdk 2.4.2 or later. Distributors must retain THIRD_PARTY_NOTICES.md and LICENSES/. | -| `@bsv/templates` | `1.9.1` | `1.10.1` | minor | [API and usage](../packages/helpers/templates.md) | No existing consumer migration is required; existing template APIs and generated scripts are unchanged. New R1K1Wallet consumers await lock(), retain each private 32-byte salt, and provide a PIV signer that signs the supplied digest directly without hashing it again. Distributors must retain THIRD_PARTY_NOTICES.md and LICENSES/ with the package. | -| `@bsv/teranode-listener` | `1.1.1` | `1.1.5` | patch | [API and usage](../packages/network/teranode-listener.md) | No consumer migration is required; listener APIs, topics, and network configuration are unchanged. Distributors must retain THIRD_PARTY_NOTICES.md and LICENSES/ with the package. | -| `@bsv/verifast` | `0.3.0` | `0.3.5` | patch | [API and usage](../packages/sdk/verifast.md) | No consumer migration is required; exports, verification behavior, worker protocols, package paths, and runtime defaults are unchanged. Keep THIRD_PARTY_NOTICES.md and LICENSES/ with every JavaScript and WebAssembly distribution. | -| `@bsv/wallet-helper` | `0.1.1` | `0.1.7` | patch | [API and usage](../packages/helpers/wallet-helper.md) | No consumer migration is required; fluent builder APIs and transaction semantics are unchanged. Distributors must retain THIRD_PARTY_NOTICES.md and LICENSES/ with the package. | -| `@bsv/wallet-relay` | `0.2.2` | `0.3.6` | minor | [API and usage](../packages/wallet/wallet-relay.md) | No wallet RPC migration is required; upgrade to @bsv/sdk 2.4.1 or later. Existing relay sessions and number arrays remain valid, and host applications continue to provide their matching Express runtime and type graph. | -| `@bsv/wallet-toolbox` | `2.10.0` | `2.10.4` | patch | [API and usage](../packages/wallet/wallet-toolbox.md) | No runtime consumer migration is required. Canonical AtomicBEEF, number-array behavior, and pagination contracts are unchanged; upgrade to @bsv/sdk 2.4.2 or later. Documentation users should use docs/storage.md instead of the removed JSight export. Distributors must retain THIRD_PARTY_NOTICES.md and LICENSES/. | -| `@bsv/wallet-toolbox-client` | `2.10.0` | `2.10.4` | patch | [API and usage](../packages/wallet/wallet-toolbox-client.md) | No consumer migration is required. Browser exports, wire types, canonical AtomicBEEF behavior, and pagination contracts are unchanged; use @bsv/sdk 2.4.2 or later. Distributors must retain THIRD_PARTY_NOTICES.md and LICENSES/. | -| `@bsv/wallet-toolbox-mobile` | `2.10.0` | `2.10.4` | patch | [API and usage](../packages/wallet/wallet-toolbox-mobile.md) | No consumer migration is required. React Native exports, wire types, and canonical AtomicBEEF behavior are unchanged; use @bsv/sdk 2.4.2 or later. Distributors must retain THIRD_PARTY_NOTICES.md and LICENSES/. | -| `create-bsv-app` | `1.0.2` | `1.1.1` | minor | [API and usage](../packages/helpers/create-bsv-app.md) | Existing mainnet and testnet scaffolds are unchanged. New TTN projects pass --network ttn or select TerraTestNet in the configurator. Distributors must retain THIRD_PARTY_NOTICES.md and LICENSES/ with the package. | +| Package | npm baseline | Source | Candidate | API | Migration | +| --------------------------------- | ------------ | -------- | --------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `@bsv/402-pay` | `0.2.1` | `0.2.5` | patch | [API and usage](../packages/middleware/402-pay.md) | No consumer migration is required; client and server exports, payment protocol behavior, and runtime defaults are unchanged. Distributors must retain THIRD_PARTY_NOTICES.md and LICENSES/ with the package. | +| `@bsv/air-gap` | `0.0.0` | `0.1.2` | minor | [API and usage](../packages/helpers/air-gap.md) | No consumer migration is required; this is the first published release of a new package with no prior public API. The experimental pre-release framing that circulated on the unmerged feature branch is not accepted by the v1 decoder. | +| `@bsv/amountinator` | `2.1.1` | `2.1.5` | patch | [API and usage](../packages/helpers/amountinator.md) | No consumer migration is required; this is a backward-compatible patch candidate. | +| `@bsv/auth` | `0.1.1` | `0.1.4` | patch | [API and usage](../packages/middleware/auth.md) | No consumer migration is required; authentication APIs, wire behavior, and runtime defaults are unchanged. | +| `@bsv/auth-express-middleware` | `2.2.0` | `2.2.3` | patch | [API and usage](../packages/middleware/auth-express-middleware.md) | No API migration is required. Upgrade to @bsv/sdk 2.4.1 or later for the shared byte-boundary contract. Generic signed application-body canonicalization remains unchanged so old and new peers verify identical bytes. Distributors must retain THIRD_PARTY_NOTICES.md and LICENSES/ with the package. | +| `@bsv/authsocket` | `2.1.1` | `2.1.7` | patch | [API and usage](../packages/messaging/authsocket.md) | No API migration is required. Existing event data, including numeric-key objects under byte-like names, is unchanged; typed payment protocols recover historical byte objects at their explicit fields. Distributors must retain THIRD_PARTY_NOTICES.md and LICENSES/ with the package. | +| `@bsv/authsocket-client` | `2.1.1` | `2.1.6` | patch | [API and usage](../packages/messaging/authsocket-client.md) | No API migration is required. Existing event data, including numeric-key objects under byte-like names, is unchanged; typed payment protocols recover historical byte objects at their explicit fields. Distributors who copy the UMD file must keep THIRD_PARTY_NOTICES.md and LICENSES/ with it. | +| `@bsv/btms` | `1.1.1` | `1.2.2` | minor | [API and usage](../packages/wallet/btms.md) | Existing local, mainnet, testnet, and number-array behavior is unchanged. TTN consumers select networkPreset teratestnet; all consumers should upgrade to @bsv/sdk 2.4.1 or later for byte-boundary compatibility. | +| `@bsv/btms-permission-module` | `1.1.1` | `1.1.4` | patch | [API and usage](../packages/wallet/btms-permission-module.md) | No consumer migration is required; permission-module APIs and token semantics are unchanged. | +| `@bsv/chirp` | `0.0.0` | `0.1.1` | minor | [API and usage](../packages/network/chirp.md) | No consumer migration is required; this is the first release of a new additive package. Existing @bsv/sdk StorageUploader, StorageDownloader, StorageUtils, UHRP identifiers, overlays, and server routes remain unchanged. BRC-167 remains authoritative if the implementation and standard differ. | +| `@bsv/did` | `0.2.1` | `0.2.5` | patch | [API and usage](../packages/helpers/did.md) | No consumer migration is required; DID APIs, encodings, credential behavior, and supported import forms are unchanged. | +| `@bsv/did-client` | `1.2.1` | `1.3.1` | minor | [API and usage](../packages/helpers/did-client.md) | Existing local, mainnet, and testnet behavior is unchanged. TTN consumers select networkPreset teratestnet and use @bsv/sdk 2.4 or later. Distributors who copy the UMD file must keep THIRD_PARTY_NOTICES.md and LICENSES/ with it. | +| `@bsv/fund-wallet` | `1.4.1` | `1.4.4` | patch | [API and usage](../packages/helpers/fund-wallet.md) | No consumer migration is required; wallet funding APIs and transaction behavior are unchanged. Distributors must retain THIRD_PARTY_NOTICES.md and LICENSES/ with the package. | +| `@bsv/gasp` | `1.3.1` | `1.3.6` | patch | [API and usage](../packages/overlays/gasp.md) | No consumer migration is required; existing constructor calls, imports, synchronization behavior, and wire semantics are unchanged. Distributors must retain THIRD_PARTY_NOTICES.md and LICENSES/ with the package. | +| `@bsv/message-box-client` | `2.4.0` | `2.5.0` | minor | [API and usage](../packages/messaging/message-box-client.md) | 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. | +| `@bsv/overlay` | `2.2.1` | `2.3.1` | minor | [API and usage](../packages/overlays/overlay.md) | Existing Engine and TopicManager implementations remain valid. Lookup results default to 1,000 formulas; pass -1 only when an equivalent deployment bound exists. Topic managers whose validation creates provisional external state should implement abortAdmissibleOutputs, while read-only managers require no change. Distributors must retain THIRD_PARTY_NOTICES.md and LICENSES/ with the package. | +| `@bsv/overlay-discovery-services` | `2.1.1` | `2.2.1` | minor | [API and usage](../packages/overlays/overlay-discovery-services.md) | Existing mainnet and testnet advertisers are unchanged. TTN operators pass chain ttn and provision the staging storage and overlay endpoints before advertising. Distributors must retain THIRD_PARTY_NOTICES.md and LICENSES/ with the package. | +| `@bsv/overlay-express` | `2.5.0` | `2.6.1` | minor | [API and usage](../packages/overlays/overlay-express.md) | Existing mainnet and testnet servers are unchanged. TTN servers call configureNetwork('ttn'), configureArcade with the TTN endpoint, and configureChaintracks or configureChainTracker before engine initialization. Distributors must retain THIRD_PARTY_NOTICES.md and LICENSES/ with the package. | +| `@bsv/overlay-topics` | `1.6.10` | `1.7.1` | minor | [API and usage](../packages/overlays/overlay-topics.md) | Existing topic and lookup identifiers remain unchanged. Production UMP overlays must give UMPTopicManager and the UMP lookup service Mongo-backed stores that use the same database, then roll out before updated wallet clients; the no-argument manager is bounded but intended only for isolated single-process use. The reservation and bootstrap-marker collections are additive and initialize from currently indexed UMP UTXOs; take a MongoDB backup before rollout. Legacy ambiguous rows remain visible and can be resolved with WAB pinning rather than deleted. | +| `@bsv/paymail` | `2.4.2` | `2.4.7` | patch | [API and usage](../packages/messaging/paymail.md) | Existing Paymail client APIs and protocol semantics are retained. Consumers provide one Express 4.18 or 5 runtime and matching type graph; browser bundles continue to exclude the server router implementation. Consumers of the former bundled Money Button or Tokenized specification documents must follow the authoritative links in docs/specs/README.md. Distributors must retain THIRD_PARTY_NOTICES.md and LICENSES/ with the package. | +| `@bsv/payment-express-middleware` | `2.1.1` | `2.1.6` | patch | [API and usage](../packages/middleware/payment-express-middleware.md) | No consumer migration is required; legacy x-bsv-payment JSON behavior remains supported, and Express 4 and 5 applications use their own peer-provided Express installation. Distributors must retain THIRD_PARTY_NOTICES.md and LICENSES/ with the package. | +| `@bsv/sdk` | `2.4.0` | `2.4.2` | patch | [API and usage](../packages/sdk/bsv-sdk.md) | No API migration is required. Historical number-array fast paths and React Native behavior remain compatible. Documentation users should load docs/swagger/swagger.yaml into their preferred viewer instead of using the removed static Swagger UI scaffold. Distributors must keep THIRD_PARTY_NOTICES.md and LICENSES/ with source and browser bundles. | +| `@bsv/simple` | `0.4.1` | `0.5.2` | minor | [API and usage](../packages/helpers/simple.md) | Existing overlay configurations and number-array behavior are unchanged. TTN consumers select network teratestnet; all consumers should upgrade to @bsv/sdk 2.4.2 or later. Distributors must retain THIRD_PARTY_NOTICES.md and LICENSES/. | +| `@bsv/templates` | `1.9.1` | `1.10.1` | minor | [API and usage](../packages/helpers/templates.md) | No existing consumer migration is required; existing template APIs and generated scripts are unchanged. New R1K1Wallet consumers await lock(), retain each private 32-byte salt, and provide a PIV signer that signs the supplied digest directly without hashing it again. Distributors must retain THIRD_PARTY_NOTICES.md and LICENSES/ with the package. | +| `@bsv/teranode-listener` | `1.1.1` | `1.1.5` | patch | [API and usage](../packages/network/teranode-listener.md) | No consumer migration is required; listener APIs, topics, and network configuration are unchanged. Distributors must retain THIRD_PARTY_NOTICES.md and LICENSES/ with the package. | +| `@bsv/verifast` | `0.3.0` | `0.3.5` | patch | [API and usage](../packages/sdk/verifast.md) | No consumer migration is required; exports, verification behavior, worker protocols, package paths, and runtime defaults are unchanged. Keep THIRD_PARTY_NOTICES.md and LICENSES/ with every JavaScript and WebAssembly distribution. | +| `@bsv/wallet-helper` | `0.1.1` | `0.1.7` | patch | [API and usage](../packages/helpers/wallet-helper.md) | No consumer migration is required; fluent builder APIs and transaction semantics are unchanged. Distributors must retain THIRD_PARTY_NOTICES.md and LICENSES/ with the package. | +| `@bsv/wallet-relay` | `0.2.2` | `0.3.6` | minor | [API and usage](../packages/wallet/wallet-relay.md) | No wallet RPC migration is required; upgrade to @bsv/sdk 2.4.1 or later. Existing relay sessions and number arrays remain valid, and host applications continue to provide their matching Express runtime and type graph. | +| `@bsv/wallet-toolbox` | `2.10.0` | `2.10.4` | patch | [API and usage](../packages/wallet/wallet-toolbox.md) | No runtime consumer migration is required. Canonical AtomicBEEF, number-array behavior, and pagination contracts are unchanged; upgrade to @bsv/sdk 2.4.2 or later. Documentation users should use docs/storage.md instead of the removed JSight export. Distributors must retain THIRD_PARTY_NOTICES.md and LICENSES/. | +| `@bsv/wallet-toolbox-client` | `2.10.0` | `2.10.4` | patch | [API and usage](../packages/wallet/wallet-toolbox-client.md) | No consumer migration is required. Browser exports, wire types, canonical AtomicBEEF behavior, and pagination contracts are unchanged; use @bsv/sdk 2.4.2 or later. Distributors must retain THIRD_PARTY_NOTICES.md and LICENSES/. | +| `@bsv/wallet-toolbox-mobile` | `2.10.0` | `2.10.4` | patch | [API and usage](../packages/wallet/wallet-toolbox-mobile.md) | No consumer migration is required. React Native exports, wire types, and canonical AtomicBEEF behavior are unchanged; use @bsv/sdk 2.4.2 or later. Distributors must retain THIRD_PARTY_NOTICES.md and LICENSES/. | +| `create-bsv-app` | `1.0.2` | `1.1.1` | minor | [API and usage](../packages/helpers/create-bsv-app.md) | Existing mainnet and testnet scaffolds are unchanged. New TTN projects pass --network ttn or select TerraTestNet in the configurator. Distributors must retain THIRD_PARTY_NOTICES.md and LICENSES/ with the package. | `none` means the source manifest matches the recorded npm baseline. Any other value is an unpublished candidate. Publication, tags, releases, registry @@ -238,8 +238,8 @@ CLI entry points: `{"fund-metanet":"./dist/index.mjs"}`. - Package documentation: [docs/packages/messaging/message-box-client.md](../packages/messaging/message-box-client.md) - Source: [packages/messaging/message-box-client](https://github.com/bsv-blockchain/ts-stack/tree/main/packages/messaging/message-box-client) -- Release note: 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. +- Release note: 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. | Public subpath | Runtime target(s) | Declaration target(s) | | ---------------- | ----------------------------------- | --------------------------------------- | diff --git a/docs/reference/release-operations.md b/docs/reference/release-operations.md index 824cef45e..eb81385ed 100644 --- a/docs/reference/release-operations.md +++ b/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] diff --git a/docs/reference/stack-facts.md b/docs/reference/stack-facts.md index 9d917980f..395d3c22f 100644 --- a/docs/reference/stack-facts.md +++ b/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) | diff --git a/docs/reference/typescript-toolchain.md b/docs/reference/typescript-toolchain.md index 957d90cef..099b0a399 100644 --- a/docs/reference/typescript-toolchain.md +++ b/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] diff --git a/docs/specs/air-gap-optical.md b/docs/specs/air-gap-optical.md index f7daa1dc4..0033199f4 100644 --- a/docs/specs/air-gap-optical.md +++ b/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'] diff --git a/governance/dependency-release-policy.json b/governance/dependency-release-policy.json index a42663784..7dbec8e6a 100644 --- a/governance/dependency-release-policy.json +++ b/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": [ diff --git a/governance/documentation-policy.json b/governance/documentation-policy.json index 5b3f711ae..05914ffd2 100644 --- a/governance/documentation-policy.json +++ b/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": { diff --git a/governance/package-release-notes.json b/governance/package-release-notes.json index 3aa969433..02a7f4929 100644 --- a/governance/package-release-notes.json +++ b/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", diff --git a/governance/repository-health/baselines.json b/governance/repository-health/baselines.json index f972de86c..fccaf9525 100644 --- a/governance/repository-health/baselines.json +++ b/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", diff --git a/governance/repository-health/exceptions.json b/governance/repository-health/exceptions.json index a2b552e1e..558ae3405 100644 --- a/governance/repository-health/exceptions.json +++ b/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." }, { diff --git a/governance/test-quality/wallet-toolbox-manual-suites.json b/governance/test-quality/wallet-toolbox-manual-suites.json index 37f57bcf3..529e85867 100644 --- a/governance/test-quality/wallet-toolbox-manual-suites.json +++ b/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", diff --git a/packages/messaging/message-box-client/CHANGELOG.md b/packages/messaging/message-box-client/CHANGELOG.md index ddf8763fb..9ddfabf5f 100644 --- a/packages/messaging/message-box-client/CHANGELOG.md +++ b/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. diff --git a/packages/messaging/message-box-client/README.md b/packages/messaging/message-box-client/README.md index fcc477f08..f6f5dbc9d 100644 --- a/packages/messaging/message-box-client/README.md +++ b/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 diff --git a/packages/messaging/message-box-client/package.json b/packages/messaging/message-box-client/package.json index 26a436c15..3252f715a 100644 --- a/packages/messaging/message-box-client/package.json +++ b/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" diff --git a/packages/messaging/message-box-client/src/MessageBoxClient.ts b/packages/messaging/message-box-client/src/MessageBoxClient.ts index 33afd764d..9544e1604 100644 --- a/packages/messaging/message-box-client/src/MessageBoxClient.ts +++ b/packages/messaging/message-box-client/src/MessageBoxClient.ts @@ -211,6 +211,7 @@ export class MessageBoxClient { private socketAuthenticated = false private connectionInitPromise?: Promise protected originator?: OriginatorDomainNameStringUnder250Bytes + private readonly socketOptions: MessageBoxClientOptions['socketOptions'] /** * @constructor * @param {Object} options - Initialization options for the MessageBoxClient. @@ -218,6 +219,7 @@ export class MessageBoxClient { * @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} [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 }) diff --git a/packages/messaging/message-box-client/src/__tests/MessageBoxClient.test.ts b/packages/messaging/message-box-client/src/__tests/MessageBoxClient.test.ts index f1d7dd5b4..8434485c8 100644 --- a/packages/messaging/message-box-client/src/__tests/MessageBoxClient.test.ts +++ b/packages/messaging/message-box-client/src/__tests/MessageBoxClient.test.ts @@ -29,6 +29,9 @@ jest.unstable_mockModule('@bsv/authsocket-client', () => ({ const { MessageBoxClient } = await import('../MessageBoxClient.js') +const { AuthSocketClient } = await import('@bsv/authsocket-client') +const authSocketClientMock = AuthSocketClient as unknown as jest.Mock + // MOCK: WalletClient methods globally jest.spyOn(WalletClient.prototype, 'createHmac').mockResolvedValue({ hmac: Array.from(new Uint8Array([1, 2, 3])) @@ -166,6 +169,101 @@ describe('MessageBoxClient', () => { await expect(connection).resolves.toBeUndefined() }, 10000) + it('Forwards socketOptions to AuthSocketClient when configured', async () => { + const messageBoxClient = new MessageBoxClient({ + walletClient: mockWalletClient, + host: 'https://message-box-us-1.bsvb.tech', + socketOptions: { + managerOptions: { transports: ['websocket'] }, + maxPendingAuthMessages: 8 + } + }) + + await messageBoxClient.init() + + const connection = messageBoxClient.initializeConnection() + setTimeout(() => { + socketOnMap.authenticationSuccess?.({ status: 'ok' }) + }, 100) + await connection + + expect(authSocketClientMock).toHaveBeenCalledWith( + 'https://message-box-us-1.bsvb.tech', + expect.objectContaining({ + managerOptions: { transports: ['websocket'] }, + maxPendingAuthMessages: 8 + }) + ) + }, 10000) + + it('Passes only client-owned options to AuthSocketClient when socketOptions is omitted', async () => { + const messageBoxClient = new MessageBoxClient({ + walletClient: mockWalletClient, + host: 'https://message-box-us-1.bsvb.tech' + }) + + await messageBoxClient.init() + + const connection = messageBoxClient.initializeConnection() + setTimeout(() => { + socketOnMap.authenticationSuccess?.({ status: 'ok' }) + }, 100) + await connection + + const options = authSocketClientMock.mock.calls[0][1] as Record + expect(Object.keys(options).sort()).toEqual(['originator', 'wallet']) + }, 10000) + + it('Rejects managerOptions.autoConnect false, which would never connect', () => { + // AuthSocketClient exposes no connect(), and MessageBoxClient never starts the + // socket itself, so autoConnect: false would sit until the 5s auth timeout. + expect( + () => + new MessageBoxClient({ + walletClient: mockWalletClient, + host: 'https://message-box-us-1.bsvb.tech', + socketOptions: { managerOptions: { autoConnect: false } } as any + }) + ).toThrow(/autoConnect/) + }) + + it('Allows managerOptions.autoConnect true, which matches the default', () => { + expect( + () => + new MessageBoxClient({ + walletClient: mockWalletClient, + host: 'https://message-box-us-1.bsvb.tech', + socketOptions: { managerOptions: { autoConnect: true } } as any + }) + ).not.toThrow() + }) + + it('Keeps client-owned wallet and originator ahead of socketOptions', async () => { + const foreignWallet = { id: 'foreign-wallet' } + const messageBoxClient = new MessageBoxClient({ + walletClient: mockWalletClient, + host: 'https://message-box-us-1.bsvb.tech', + originator: 'client.example', + // A JS caller can still smuggle these past the Omit<> type. + socketOptions: { + wallet: foreignWallet, + originator: 'socket.example' + } as any + }) + + await messageBoxClient.init() + + const connection = messageBoxClient.initializeConnection() + setTimeout(() => { + socketOnMap.authenticationSuccess?.({ status: 'ok' }) + }, 100) + await connection + + const options = authSocketClientMock.mock.calls[0][1] as Record + expect(options.originator).toBe('client.example') + expect(options.wallet).not.toBe(foreignWallet) + }, 10000) + it('Falls back to HTTP when WebSocket is not initialized', async () => { const messageBoxClient = new MessageBoxClient({ walletClient: mockWalletClient, diff --git a/packages/messaging/message-box-client/src/types.ts b/packages/messaging/message-box-client/src/types.ts index f29565b97..9d13f8538 100644 --- a/packages/messaging/message-box-client/src/types.ts +++ b/packages/messaging/message-box-client/src/types.ts @@ -14,6 +14,27 @@ import { WalletInterface, type LookupNetworkPreset } from '@bsv/sdk' +import type { AuthSocketClientOptions } from '@bsv/authsocket-client' + +/** + * Socket.IO manager/socket options forwarded to AuthSocketClient. + * `autoConnect` is excluded: AuthSocketClient exposes no connect method and the + * client never starts the socket itself, so disabling auto-connect would leave + * `initializeConnection` waiting for an authentication that cannot arrive. + */ +export type MessageBoxForwardedManagerOptions = Omit< + NonNullable, + 'autoConnect' +> + +/** + * AuthSocketClient options a MessageBoxClient caller may supply. + * `wallet` and `originator` are owned by the client and always win. + */ +export type MessageBoxSocketOptions = Omit< + AuthSocketClientOptions, + 'wallet' | 'originator' | 'managerOptions' +> & { managerOptions?: MessageBoxForwardedManagerOptions } /** * Configuration options for initializing a MessageBoxClient. @@ -48,6 +69,19 @@ export interface MessageBoxClientOptions { * Originator of the message box client. */ originator?: string + + /** + * Options forwarded to the underlying AuthSocketClient when the live socket is + * created. Covers socket.io transport selection via `managerOptions` (e.g. + * `{ managerOptions: { transports: ['websocket'] } }` for a deployment that does + * not carry Engine.IO HTTP polling), plus certificate requests, session + * management, auth-message concurrency, and error reporting. + * + * `wallet` and `originator` are excluded because the client owns both; the + * client's own values always win. Only affects the socket path; HTTP requests + * are unchanged. + */ + socketOptions?: MessageBoxSocketOptions } /**