@bsv/wallet-toolbox 2.4.2 → 2.4.4

package/CHANGELOG.md

@@ -6,6 +6,43 @@ attention to changes that materially alter behavior or extend functionality.
 
 ## wallet-toolbox (unreleased)
 
+- Harden CWI/WAB account continuity so overlay failures, malformed or ambiguous
+  UMP results, and snapshot-load failures cannot silently enter new-user
+  onboarding. Add an expiring WAB auth session, legacy-compatible WAB account
+  status inference, canonical E.164 phone identity, bounded KDF/snapshot
+  parsing, and fail-closed UMP renewal/broadcast behavior.
+- Replace WAB's endpoint-by-endpoint raw `fetch` calls with one typed transport
+  enforcing HTTPS (localhost excepted), timeouts, request/response limits,
+  redirect and ambient-credential protection, correlation IDs, and privacy-safe errors.
+  Wallet authentication, UMP, WAB, and snapshot events now support the SDK's
+  opt-in generic telemetry sink without reporting keys, snapshots, payloads,
+  OTPs, or Shamir shares.
+- Add automatically negotiated, in-memory planning for dependent `noSend` workloads. Capable
+  storage providers reserve funding once, perform middle action planning and signing without
+  persistence round trips, and atomically commit the complete workspace on `sendWith`. Existing
+  BRC-100 arguments and results are unchanged, and providers without `actionBatch: 1` retain the
+  legacy path. SQLite, MySQL/Knex, IndexedDB, authenticated remote clients, browser, and mobile
+  builds share the same capability contract.
+- Add leased per-output batch reservations, expiry cleanup, adaptive pool extension, idempotent
+  manifest commits, inline content-addressed blobs up to 4 MiB, and authenticated binary uploads
+  in provider-sized chunks with four-way bounded concurrency for larger batches. Broadcast remains
+  outside the atomic persistence transaction.
+- Make batch funding converge on fragmented wallets at production fee rates. Reservation targets
+  include the fee and viable-change overhead of an added input, reactive extensions request only
+  the remaining shortfall, and EWMA runway extensions subtract unconsumed reserved funding without
+  compounding after empty or partial responses. The regression runs 16 independent actions through
+  both the in-process and authenticated remote-storage paths and commits the complete batch.
+- Bind remote batch authorization exclusively to the BRC-103 authenticated identity and its active
+  storage provider, ignoring caller-supplied user IDs and active-state claims. Restrict JSON-RPC
+  dispatch to the public remote-storage protocol so authenticated callers cannot invoke low-level
+  provider methods, and rate-limit authenticated RPCs per identity key without limiting workspace
+  length. Unauthenticated and cross-user batch-management regressions cover the boundary.
+- Replace the cumulative 64-output reservation ceiling with repeatable extensions bounded to 64
+  outputs per storage call. Workspaces and spend chains no longer have an action-count or confirmed
+  funding-input ceiling; an 80-action independent batch crosses the old boundary and commits.
+- Add a retained workload benchmark covering 1, 10, 50, and 250 actions across dependent,
+  independent, mixed-input, and two-step signing models, four script sizes, and 25/100/250 ms
+  storage latency. Run it with `pnpm --filter @bsv/wallet-toolbox bench:action-batch`.
 - Release prep for `2.4.2`: transaction-pipeline, BEEF fetching, and binary transport
   performance improvements described below, published in lockstep for Node, browser, and mobile.
 - Transaction pipeline performance: reuse parsed BEEF through `createAction`/`signAction`, retain
@@ -34,7 +71,7 @@ attention to changes that materially alter behavior or extend functionality.
   `auth-express-middleware@2.1.1` likewise declares its `mime-types` runtime
   import so strict package managers do not fail when loading the built packages.
 
-- Release prep for `2.4.2`: proof completion now discovers every local
+ - Release prep for `2.4.2`: proof completion now discovers every local
    transaction row sharing the proven txid, repairs notification-set drift from
    concurrent multi-user `internalizeAction` calls, and idempotently completes
    any local copy omitted by a last-writer-wins notification update.

package/docs/README.md

@@ -9,7 +9,9 @@ The documentation is split into various pages, each covering a set of related fu
 - [Storage](./storage.md) — Wallet data persistent storage classes and related APIs.
 - [Services](./services.md) — Support for abstracted external network services.
 - [Monitor](./monitor.md) — Background task manager for wallet action validation and processing.
+- [Action batch planning](./action-batch-planning.md) — Session-local `noSend` planning and atomic storage commit.
 - [WAB Shamir](./wab-shamir.md) — Shamir 2-of-3 key recovery system with entropy collection and WAB server integration.
+- [Authentication observability](./authentication-observability.md) — Privacy-safe telemetry, WAB transport hardening, and account-continuity handling.
 
 ## Open API
 
@@ -83,4 +85,4 @@ const rw = await wallet.internalizeAction(args)
 console.log(rw.accepted)
 ```
 
-[Return to Top](#bsv-wallet-toolbox-api-documentation)
+[Return to Top](#bsv-wallet-toolbox-api-documentation)

package/docs/action-batch-planning.md

@@ -0,0 +1,117 @@
+# In-memory action batch planning
+
+Wallet Toolbox can plan a sequence of `noSend` actions in memory and commit it
+atomically when the application uses `sendWith`. This removes per-action storage
+round trips without changing the BRC-100 wallet interface, action arguments, or
+result shapes. Applications continue to create, sign, and send actions exactly as
+before.
+
+## Negotiation and compatibility
+
+`WalletArgs.actionBatchMode` accepts `auto` (the default) or `legacy`. In `auto`
+mode, the wallet asks its active storage provider for capabilities once. A provider
+advertising `actionBatch: { version: 1, ...limits }` enables local planning. A
+provider without that capability uses the existing persistence flow before any
+workspace begins. A workspace never mixes storage modes or changes active provider.
+
+The capability and its methods are Wallet Toolbox storage extensions. They do not
+extend `WalletInterface`, `CreateActionArgs`, `SignActionArgs`, `noSend`,
+`noSendChange`, `sendWith`, or their results.
+
+## Lifecycle
+
+1. The first `noSend` action begins a workspace, reserves the canonical funding
+   inputs needed for that action plus limited headroom, and returns their proof
+   data in one storage call.
+2. The wallet plans, signs, validates, and indexes subsequent actions locally. A
+   shared BEEF graph and content-addressed locking-script blobs avoid retaining
+   repeated ancestry and script copies.
+3. If confirmed funding runs low, the wallet extends its reservation pool using
+   an EWMA estimate and geometrically increasing runway. Forwarded staged change
+   needs no reservation or extension.
+4. `sendWith`, or a normal action created while the workspace is open, validates
+   and atomically persists every staged action. Only the requested transactions
+   are sent; earlier actions retain their `nosend` status.
+5. Broadcast occurs after the storage transaction. Delayed mode returns after the
+   batch is durably queued; immediate mode uses the existing aggregate broadcaster
+   and review results.
+
+Intermediate state is deliberately session-scoped. If the wallet process exits,
+the uncommitted transaction workspace is lost and its durable reservations expire
+or are released by cleanup. The final commit is the remote durability boundary.
+
+## Reservations and cleanup
+
+Reservations belong to individual outputs, not the wallet. Other wallet activity
+can use unreserved outputs normally. A uniqueness constraint prevents one output
+from belonging to two active batches.
+
+The initial reservation includes at most three extra candidates and never more
+than eight outputs. Its canonical funding target includes the marginal P2PKH
+input fee and enough value to recover an economically viable first change output,
+so a low basket minimum cannot repeatedly select inputs that satisfy the nominal
+deficit but cost too much to use.
+
+Extensions add at most 64 outputs per storage call, but there is no cumulative
+reservation, workspace-size, action-count, or spend-chain limit. Additional
+bounded calls continue for as long as the workspace needs confirmed funding.
+They use the same exact, least-over, then largest-under selection policy as
+normal funding. Retry targets are incremental shortfalls: the planner credits
+the value and count of every unconsumed reserved output before asking for more.
+Confirmed inputs already used by staged transactions remain reserved until
+commit but are not credited as available funding. Proactive EWMA requests
+likewise subtract the unconsumed pool, initialize from the first complete
+sample, and increase geometric runway only when the provider fulfills both the
+requested count and value. Empty or partial extensions therefore cannot
+compound a target against unchanged wallet state.
+Leases last 15 minutes with a 60-minute hard lifetime. Long-running workspaces
+renew near 80% of the lease; commit may atomically reacquire an expired reservation
+when no conflicting spend or reservation occurred. Commit, abort, wallet
+destruction, expiry cleanup, and the one-minute monitor task release unused state.
+
+## Atomic commit and payload transport
+
+The provider checks graph order, duplicate spends, scripts, TXIDs, signatures,
+fees, commissions, leases, and output metadata before persistence. Transactions,
+outputs, labels, tags, maps, and proof requests are written under one database
+transaction together with reservation consumption and release. Batch ID plus a
+semantic manifest digest makes persistence retries idempotent.
+
+Content-addressed raw transactions, dependency BEEF, and locking scripts travel
+inline for batches up to the provider's inline limit (4 MiB by default). Larger
+workloads prepare a manifest, upload only missing blobs through authenticated raw
+binary requests, and commit by digest. Logical blobs are split at the provider's
+advertised limit (8 MiB by default), deduplicated by digest, and uploaded with at
+most four concurrent requests. Incomplete uploads expire with their batch.
+
+The remote server derives the batch user ID and active-storage state from the
+BRC-103 authenticated identity for every management call and binary upload.
+Caller-supplied user IDs or active-state claims are never authoritative, and the
+JSON-RPC dispatcher exposes only the public remote-storage protocol rather than
+low-level provider methods. Authenticated RPC and blob requests are rate-limited
+by identity key without limiting the number of actions, transactions, or blobs
+in a workspace; operators can configure the rate and a shared multi-replica
+store through `WalletStorageServerOptions.rateLimit`.
+
+## Rollout and measurement roadmap
+
+The compatibility boundary permits a server-first rollout: deploy schema and
+provider support, then deploy clients in `auto` mode. Old clients ignore the
+capability; new clients fall back against old providers. Operators can use
+`actionBatchMode: 'legacy'` for controlled comparisons.
+
+The retained benchmark is the performance regression gate:
+
+```bash
+pnpm --filter @bsv/wallet-toolbox bench:action-batch
+```
+
+It records planning, signing and validation, storage RPCs, database transactions,
+request bytes, commit and broadcast time, CPU, and incremental peak heap. Physical
+SQLite runs compare 1, 10, 50, and 250 action chains at 1 KiB and exercise each
+larger script size with a real action, including the 4 MiB upload path. Its complete
+model covers dependent, independent, explicit-input, and two-step signing workloads
+at every action count; 1 KiB, 64 KiB, 1 MiB, and 4 MiB scripts; and 25, 100, and
+250 ms storage RTT. Production rollout should additionally track reservation
+conflicts, extensions, expiries, commit retries, upload deduplication, commit
+duration, and broadcaster review outcomes by provider type.

package/docs/authentication-observability.md

@@ -0,0 +1,94 @@
+# Authentication observability and account continuity
+
+Wallet Toolbox authentication uses the SDK's generic `TelemetryConfig`. The
+same sink can correlate SDK overlay resolution, UMP account lookup, WAB HTTP,
+wallet snapshot, and authentication state-transition events.
+
+```ts
+import {
+  LookupResolver,
+  TelemetryConfig
+} from '@bsv/sdk'
+import {
+  OverlayUMPTokenInteractor,
+  WABClient
+} from '@bsv/wallet-toolbox'
+
+const telemetry: TelemetryConfig = {
+  minimumSeverity: 'info',
+  sink: {
+    capture: event => supportReporter.capture(event)
+  },
+  beforeSend: event => ({
+    ...event,
+    attributes: {
+      ...event.attributes,
+      applicationVersion: '4.7.0',
+      operatingSystem: 'ubuntu'
+    }
+  })
+}
+
+const resolver = new LookupResolver({ telemetry })
+const ump = new OverlayUMPTokenInteractor(resolver, undefined, telemetry)
+const wab = new WABClient('https://wab.example.com', { telemetry })
+```
+
+Pass the same `telemetry` configuration in
+`WalletAuthenticationManagerOptions` when constructing the manager. Correlation
+IDs then connect the WAB start/complete requests to account-continuity events
+without exposing authentication payloads.
+
+## Privacy boundary
+
+Telemetry is opt-in and no-op by default. Wallet Toolbox reports operation
+names, result categories, host counts, HTTP status, durations, format versions,
+and correlation IDs. It never reports:
+
+- private, presentation, recovery, or password-derived keys;
+- passwords, phone numbers, OTPs, auth tokens, or request payloads;
+- UMP token fields, Shamir shares, ciphertext, or transaction material;
+- wallet snapshots or decrypted profile data.
+
+The SDK sanitizes events before and after consumer enrichment. Sink failures do
+not affect authentication or wallet behavior.
+
+## Account-state rules
+
+`authenticationFlow` starts as `unknown`. A password cannot create a wallet
+until account lookup has completed.
+
+An empty UMP answer means `new-user` only when every selected overlay host
+settled successfully and returned an empty output list. Timeout, host failure,
+malformed response, semantic rejection, or a malformed UMP token raises
+`UMPTokenLookupError`. Multiple distinct valid UMP tokens are also treated as
+ambiguous instead of choosing one by response order. Applications should
+present retry and account-recovery options for these errors, never a
+new-password prompt.
+
+WAB completion uses an explicit `accountStatus` or `existingUser` response when
+available. For older WAB servers it derives the status from the established
+protocol: a new account returns the temporary presentation key, while an
+existing account returns its stored key. If WAB identifies an existing account
+but UMP authoritatively appears absent, `WABAccountContinuityError` prevents
+new-wallet creation.
+
+Temporary WAB authentication state expires after ten minutes by default and is
+cleared when authentication is cancelled, completed, or destroyed.
+
+Snapshot initialization is also fail-closed. Awaiting `manager.ready` rejects
+when a supplied snapshot cannot be loaded instead of silently resetting the
+manager into onboarding.
+
+## WAB transport
+
+Every WAB endpoint uses one transport with:
+
+- HTTPS enforcement, with plain HTTP limited to localhost development;
+- a hard wall-clock timeout;
+- bounded JSON request and response sizes;
+- rejected redirects and omitted ambient credentials;
+- typed, privacy-safe failures and correlated telemetry.
+
+Configure `timeoutMs`, `maxRequestBytes`, and `maxResponseBytes` in `WABClient`
+options when the defaults of 10 seconds and 1 MiB are not appropriate.