@bsv/wallet-toolbox 2.11.0 → 2.13.0

package/CHANGELOG.md

@@ -6,6 +6,78 @@ attention to changes that materially alter behavior or extend functionality.
 
 ## wallet-toolbox (unreleased)
 
+- Integrate upstream security corrections without dropping the sync recovery contracts.
+  Record combined browser/mobile artifact costs and limits in the sync transfer guide.
+
+- Validate replacement proofs across providers before reconciling stale RPC sync metadata; preserve raw transactions and checkpoints on failure.
+
+- Start sync copies conservatively and adapt page work after committed responses.
+  Validate at most eight remote proofs concurrently, draining failure work before
+  rejecting the page. Preserve all proof and checkpoint checks. Record-transfer
+  candidates now use 2.13.0 to distinguish them from published 2.12.0.
+
+- Require an affirmative certifier-signature verification result before
+  storing directly acquired or issuer-returned certificates. Identity overlay
+  results are verified before decryption and trust scoring, so forged
+  certificates cannot become wallet-held or trusted discovered identities. The
+  synchronized browser Vite ceilings advance to 1,695,000 raw and 401,000 gzip,
+  covering measured 1,694,211-byte and 400,048-byte bundles; Brotli is unchanged.
+  The mobile Metro raw ceiling advances to 1,750,000 for the measured
+  1,748,892-byte bundle. The browser esbuild raw ceiling advances to 1,323,000
+  for the measured 1,321,768-byte bundle, its gzip ceiling advances to 365,000
+  for the measured 364,413-byte bundle, and the optimized Hermes gzip ceiling
+  advances to 1,442,000 for the measured 1,441,531-byte bytecode; remaining
+  compressed ceilings are unchanged.
+- Never cache, coalesce, or reuse spending approvals, give each prompt a
+  distinct request identity, and paginate the complete action history before
+  calculating an authorization token's prior spending.
+- Require HTTPS for credential-bearing remote storage and Arcade SSE outside
+  explicit loopback development, disable dependency debug output, and avoid
+  serializing credential-bearing transport errors. Snapshot formats remain
+  unchanged and are documented as wallet-equivalent secrets.
+- Make new WAB account creation resumable when wallet setup, funding, KDF, UMP
+  publication, or the final acknowledgement is interrupted. The manager accepts
+  a clean missing-token result only for a server-declared pending registration,
+  finalizes after successful publication, repairs a lost acknowledgement on the
+  next login, and preserves fail-closed continuity for active and legacy WABs.
+- Add optional bounded sync transfers for oversized records, authenticated pieces,
+  durable Knex staging, full-frame SHA-256 verification, and stale-checkpoint
+  rejection before merging. Add the two staging tables through migration
+  `2026-09-09-001`; reverse only that migration before restarting older code. Frames are limited
+  to 64 MiB and ordinary pages keep their existing transport. See
+  [the transport and migration guide](./docs/sync-transfer.md).
+
+- Upgrade IndexedDB to schema version 6 with a non-unique transaction-ID/user
+  index. Use existing reference, reclaim, commission, and relation keys for
+  sync lookups, avoiding repeated scans as a local wallet grows. Preserve
+  user filtering, pagination, existing bytes, and duplicate transaction IDs.
+  Proof-batch preflight checks resolve only requested transaction IDs through
+  the existing index, preserving proof validation and primary-key ordering.
+  Older clients requesting schema version 5 cannot open the upgraded database.
+
+- Add negotiated compact sync checkpoints, reusing committed page progress while
+  retaining complete writer-side ID mappings and the legacy provider fallback.
+  Avoid per-scalar reviver callbacks when decoding binary JSON pages without
+  changing marker escaping or byte semantics. Use the already negotiated binary
+  codec for large schema-defined sync response byte arrays, reducing wire and
+  authentication payload size while preserving legacy arrays and unrelated data.
+  Retain authenticated full-copy,
+  resume, malformed-input, and transport CPU/payload regression coverage.
+  Local packed measurements are 1,701,711 raw / 401,038 gzip / 314,272 Brotli
+  bytes (Vite), 1,327,368 / 364,550 / 293,224 (esbuild),
+  1,753,648 / 445,136 / 345,369 (Metro), and
+  3,557,663 / 1,426,740 / 1,121,821 (Hermes). The raw ceilings become
+  1,702,000, 1,327,500, 1,755,000, and 3,558,500 respectively.
+  Vite and esbuild gzip ceilings increase to 402,000 and 366,000 bytes.
+  Hosted Linux measures 365,818 esbuild gzip bytes and 1,445,624 Hermes gzip
+  bytes; the Hermes gzip ceiling becomes 1,446,500.
+  The esbuild Brotli ceiling is 293,750 bytes. Asynchronous platform hashing
+  for large SDK signature payloads brings the Vite Brotli ceiling to 314,500
+  bytes, the Hermes raw ceiling to 3,560,000 bytes, and its Brotli ceiling to
+  1,125,000 bytes (measured 1,124,446); other compressed ceilings remain unchanged.
+  The added portable sync/progress and decoding paths account for
+  the increase; no Node-only backend is introduced into portable bundles.
+
 - Keep Argon2id-backed UMP v3 wallets available in React Native and other
   runtimes without WebAssembly by falling back to an asynchronously yielding,
   standards-compatible JavaScript implementation. The same KDF parameters and
@@ -22,10 +94,15 @@ attention to changes that materially alter behavior or extend functionality.
   bytes with Vite, 1,319,059 raw / 362,220 gzip / 291,206 Brotli bytes with
   esbuild, 1,746,067 raw / 442,648 gzip / 343,342 Brotli bytes with Metro, and
   3,542,034 raw / 1,419,515 gzip / 1,117,531 Brotli bytes as optimized Hermes
-  bytecode; hosted Linux measures 1,439,166 gzip bytes. The reviewed ceilings
-  advance to 1,693,000 / 400,000 / 314,000 Vite bytes, 1,321,000 / 364,000 /
-  293,000 esbuild bytes, 1,748,000 raw Metro bytes with the compressed ceilings
-  unchanged, and 3,547,000 / 1,441,000 / 1,123,000 Hermes bytes.
+  bytecode; hosted Linux measures 1,439,166 gzip bytes. Combined with the
+  interrupted-registration recovery path above, current measurements are
+  1,694,823 raw / 399,940 gzip / 312,528 Brotli bytes with Vite, 1,322,223 raw
+  / 364,260 gzip / 291,914 Brotli bytes with esbuild, 1,749,694 raw / 443,665
+  gzip / 344,059 Brotli bytes with Metro, and 3,549,495 raw / 1,441,622 gzip /
+  1,119,600 Brotli bytes as optimized Hermes bytecode. The reviewed ceilings
+  advance to 1,697,000 raw / 400,000 gzip Vite bytes, 1,324,000 raw / 365,000
+  gzip esbuild bytes, 1,752,000 raw Metro bytes, and 3,552,000 raw / 1,442,000
+  gzip Hermes bytes; Brotli ceilings remain unchanged.
 
 - Extend the BRC-98/99/111 permission-module interface with an optional semantic
   `handleRequest` hook. A module can now return a conforming BRC-100 result
@@ -107,6 +184,25 @@ attention to changes that materially alter behavior or extend functionality.
   transaction startup/commit cycles, failed pages roll back without advancing
   the checkpoint, and abort cleanup preserves the original storage error.
 
+- Fill wallet-storage sync pages with adaptive, size-aware source queries and
+  add composite SQL indexes for user-scoped proof lookups. Sync clients may
+  request optional source record totals for exact progress and ETA displays;
+  older clients and providers remain wire-compatible and do not incur count
+  queries unless totals are requested. Remote clients also recover from a
+  provider's HTTP 413 response ceiling by retrying the read-only sync request
+  with a smaller chunk budget and reusing the working limit for later pages.
+  Runtime validation rejects malformed remote totals, and MySQL rollback
+  restores the foreign-key support index before removing the new composites.
+  The retained authenticated candidate-provider benchmark fills a 250-record
+  proof page with three source reads (`10, 80, 160`) on SQLite and MySQL.
+  Clean macOS fixtures measure Vite at 1,609,916 raw, 379,552 gzip, and 297,188
+  Brotli bytes; esbuild at 1,254,827 raw, 344,883 gzip, and 277,729 Brotli
+  bytes; Metro at 1,662,714 raw, 419,740 gzip, and 326,785 Brotli bytes; and
+  Hermes at 3,371,236 raw, 1,347,950 gzip, and 1,061,946 Brotli bytes. The
+  reviewed ceilings advance to 1,611,000/380,000/297,500 for Vite,
+  1,256,000/346,000/278,200 for esbuild, and 3,373,000/1,368,000 raw/gzip for
+  Hermes. Metro and the Hermes Brotli ceiling remain unchanged.
+
 - Make verified phone changes interruption-safe by staging the replacement key
   in WAB, publishing the UMP rotation, and then finalizing WAB. Authentication
   can recover an interrupted transition from the current or pending key and

package/README.md

@@ -6,6 +6,27 @@
 
 A [BRC-100](https://github.com/bitcoin-sv/BRCs/blob/master/wallet/0100.md) conforming wallet implementation for the BSV blockchain, built on the [BSV SDK](https://bsv-blockchain.github.io/ts-stack/packages/sdk/). Provides persistent storage, protocol-based key derivation, transaction monitoring, chain tracking, and signing — everything needed to build wallet-powered applications on BSV.
 
+## Backup and sync: tested results
+
+**Live E2E testing used a large wallet in the native desktop client**, covering
+complete local copies, restart recovery, and repeat sync. Transfer size and oversized-record recovery were
+measured separately with synthetic fixtures. The latest proof-recovery follow-up
+has synthetic HTTP and read-only source-data validation; its live full-backup
+retest is pending.
+
+| Test                         | Verified result                                                                                                                                         |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Full native desktop restores | **Two complete copies; identical entity counts.** Second run: **12m 50s vs 16m 30s (22.3% less time)**.                                                 |
+| Retained local backup        | Completed after cancellation, a connectivity pause, and restart recovery; all **12 entity-store counts preserved** on another restart.                  |
+| Local reads and repeat sync  | Transaction/output reads passed; sampled transaction bytes matched; repeat sync made **0 inserts, 0 updates**.                                          |
+| Transfer size                | **62.7% smaller** encoded byte payload in a synthetic fixture.                                                                                          |
+| Oversized single record      | **7 MiB restored in real browser IndexedDB**, matching SHA-256; interrupted upload resumed, corrupt download rejected, repeat sync unchanged.           |
+| Automated integration        | Authenticated HTTP backup/restore, interrupted pages, lost acknowledgements, binary byte round-trips, user isolation, and legacy compatibility covered. |
+
+Timing compares successive candidates, not a controlled comparison against upstream
+`main`. Byte verification was sampled, not database-wide. See
+[test methods and limits](#sync-performance-and-recovery) for details.
+
 ## Overview
 
 The Wallet Toolbox is the reference implementation of the BRC-100 wallet interface. It connects the BSV SDK's cryptographic primitives to real storage backends, network services, and signing flows so that application developers don't have to wire these layers together themselves.
@@ -54,10 +75,141 @@ The toolbox publishes three npm packages from this repo:
 - **[`@bsv/wallet-toolbox-client`](https://www.npmjs.com/package/@bsv/wallet-toolbox-client)** — Browser build; excludes Node-only backends (Knex/SQLite/MySQL)
 - **[`@bsv/wallet-toolbox-mobile`](https://www.npmjs.com/package/@bsv/wallet-toolbox-mobile)** — Mobile build; remote wallet storage plus portable local ChainTracks components and adapter contracts
 
+### Sync performance and recovery
+
+Sync pages start at 64 records and adapt after successful commits toward a
+five-second page budget. Proof-bearing pages cap growth at 128 records; cheap
+metadata pages can grow to 1,000, while provider byte/item ceilings still apply.
+The server checks at most eight proofs concurrently and waits for all started
+checks to settle on failure before rejecting the page. Every proof still passes
+transaction, Merkle path, active-root and active-header validation before a merge.
+An authenticated HTTP regression covers 250 synthetic proofs and confirms that
+an invalid follow-up page cannot change the committed checkpoint. Stale proofs
+can be reconciled through another provider, but only after the replacement passes
+the same transaction, membership and active-chain checks. Transaction bytes,
+wallet references and source cursor timestamps are preserved. Corrected destination
+proofs receive a fresh local timestamp for incremental replication. Unverifiable replacements
+stop the page with a recovery message; no record is silently skipped.
+
+A read-only deployment-host sample of 250 proofs took 42.6 seconds with sequential
+validation and 5.58 seconds with bounded concurrency, with the same 250 root and
+250 header checks. This measures validation only, not full-copy throughput.
+Timeouts remain possible during dependency outages; writes are never blindly
+replayed, and resumed sync rereads durable destination progress.
+
+The adaptive page controller and optional validated-proof lookup add a small
+client bundle cost. The [artifact measurements and limits](./docs/sync-transfer.md#artifact-cost-requiring-review)
+include the combined upstream security fixes. These are explicit feature costs;
+the RPC validation coordinator remains excluded from browser/mobile bundles.
+
+The transfer extension is an **unpublished 2.13.0 candidate**. Published 2.12.0
+has no record-transfer methods. Check exact build provenance and authenticated
+runtime capabilities, not a version label alone. An oversized record on a legacy
+source cannot be rescued by upgrading only its destination; upgrade the source
+before retrying. Records exceeding the negotiated 64 MiB frame limit fail safely
+without being skipped or advancing their checkpoint.
+
+Large individual records can use the negotiated
+[bounded transfer protocol](./docs/sync-transfer.md), with durable staging,
+integrity verification and checkpoint replay protection. Its authenticated
+HTTP/SQLite/IndexedDB regression exercises a 7 MiB binary record, an interrupted
+upload across client/server restart, a lost part acknowledgement, corrupted
+download rejection and a verified restore followed by an unchanged resync.
+The current frame limit is 64 MiB; legacy providers must be upgraded to use it.
+It also passes with a one-second delay on every authenticated transport send;
+that models added latency, not a measured bandwidth limit or a real mobile network.
+These synthetic regressions are separate from the large-wallet timing evidence above.
+
 Wallet storage replication applies each received page and its durable sync
 checkpoint in one provider transaction. IndexedDB and Knex therefore avoid
 per-record transaction startup, and a failed page rolls back without advancing
-the checkpoint. The sync wire format and persisted schemas are unchanged.
+the checkpoint. Sources fill each bounded page with adaptive, size-aware reads,
+and Knex storage adds user-scoped proof lookup indexes. Clients may set
+`includeTotals` on a sync-chunk request to receive optional source record totals
+for exact progress reporting. Older providers ignore the hint, and totals are
+not counted unless requested. New clients also send the writer-local sync-state
+identifier selected during provider registration. New providers use it to
+disambiguate legacy duplicate checkpoints, while either side remains compatible
+with older protocol peers. When a provider rejects a sync page because its
+serialized RPC response exceeds the service ceiling, remote clients retry the
+read-only request with a smaller chunk budget and remember the working limit
+for the rest of the session.
+
+IndexedDB schema version 6 adds a non-unique transaction-ID/user index. Sync
+identity lookups, commissions, and relation maps use selective indexes or exact
+keys instead of scanning the growing wallet for each row. Proof batch checks
+resolve requested transaction IDs through the existing index, preserving primary-key
+ordering, pagination, and proof-validation rules. Existing bytes and
+legacy duplicate transaction IDs are preserved. Databases upgrade automatically;
+older clients that open schema version 5 cannot reopen an upgraded database, so
+keep a compatible client when retaining a local backup.
+
+Updated servers advertise `syncCheckpointVersion: 1` in runtime settings.
+Compatible clients fetch a compact checkpoint once, then use the checkpoint
+returned by each committed page. The complete ID mapping remains durable on
+the writer and is no longer downloaded before every page. Older providers use
+the existing full-state path; authentication, gateway, and malformed checkpoint
+errors remain failures rather than compatibility fallbacks. A retry starts
+from the writer's durable checkpoint. `includeNextCheckpoint` is optional, and
+legacy requests retain their existing response shape.
+
+When a reader negotiates binary JSON, large schema-defined sync byte fields
+are encoded as base64 instead of decimal number arrays. Legacy readers retain
+the existing arrays; unrelated numeric fields are never reinterpreted as bytes.
+Clients with `binaryRequests: true` use the same compact representation for
+sync uploads after the server negotiates binary request support. The default
+request setting is unchanged.
+Binary JSON parsing preserves the existing marker and escaping rules while
+avoiding a JavaScript reviver callback for every scalar byte. The SDK also
+prevents certificate work or session recovery from dispatching another request
+after the caller's authentication deadline has expired. This does not cancel a
+write already received by a server or automatically replay failed writes.
+
+Run the authenticated candidate-provider sync benchmark with:
+
+```sh
+pnpm bench:storage-sync
+```
+
+Set `WALLET_TOOLBOX_BENCH_MYSQL=true`, `MYSQL_CONNECTION`, and optionally
+`WALLET_TOOLBOX_BENCH_MYSQL_DATABASE` to exercise the same fixture through a
+MySQL-backed provider. The benchmark reports HTTP p50/p95 latency and the
+source-query limits used to fill a 250-record page; it is observational rather
+than a cross-machine latency SLA. It also compares the old reviver with the
+current parser on identical synthetic data and measures checkpoint size. On
+one local Node 24 run, a 1 MiB numeric-array fixture (3.74 MB of JSON) measured
+501.2 ms versus 10.1 ms median parsing time across nine alternating samples.
+A synthetic 50,000-entry mapping occupied 678,850 bytes; its compact checkpoint
+occupied 432 bytes. These are CPU and payload measurements, not a claim of the
+same end-to-end network speedup. Encoding the synthetic byte field through
+the negotiated sync codec reduced its JSON payload from 3,743,771 to 1,398,163
+bytes (62.7%).
+
+Retained integration tests cover authenticated HTTP backup and complete restore
+into a fresh IndexedDB store, multipage progression, no-change resync,
+interruption/resume, user isolation, malformed checkpoints, and legacy-provider
+fallback. Live deployment results must be reported separately with the tested
+revision and scope; a partial page sample is not a full restore verification.
+
+A native desktop integration run against candidate runtime
+`a88d18abf14b75a3227016bfd947d5a08b3ee236` completed a full remote-to-local
+copy in 769.5 seconds, compared with 990.3 seconds for the preceding candidate
+run with identical entity counts. Remote reads took 619.2 seconds, local writes
+146.0 seconds, and measurement 4.1 seconds. Proof-page writes fell from 75.7 to
+9.8 seconds after indexed preflight lookup. These are sequential observations,
+not a controlled full-wallet comparison against upstream main. The all-state
+100 ms timer probe reported p95 delay of 908 ms; foreground focus was not recorded,
+so this does not establish foreground UI latency. Separate 90-second native
+foreground probes during a retained backup measured p95 delays of 5 ms for
+transactions, 8 ms for outputs, 10 ms for heavier output pages, and 5 ms for
+proof requests. Their maxima were 60, 51, 298, and 62 ms respectively; these
+samples are not a whole-copy latency guarantee. The retained-backup test also
+verified cancellation at a page boundary and automatic checkpoint recovery after
+a full native app restart. Development testing required refreshing Vite's cached
+linked dependencies to load the candidate schema consistently. See
+[PR486](https://github.com/bsv-blockchain/ts-stack/pull/486) for final integration
+completion and release evidence. Personal deployment and wallet details are
+retained privately, outside this repository.
 
 `listOutputs` reports `totalOutputs` as the full matching result count on every
 page for both Knex and IndexedDB storage, including short final pages and pages
@@ -92,13 +244,22 @@ checks leave multiple valid UMP tokens, and only when the pinned outpoint is
 present in the verified candidates. A pin cannot introduce an outpoint that the
 wallet did not independently retrieve and validate.
 
+New WAB registrations are interruption-safe across the off-chain/on-chain
+boundary. A WAB that advertises `registrationStatus: "pending"` lets a verified
+retry reuse the stored presentation key when a clean UMP lookup confirms that
+publication has not happened. After publishing the UMP token, the manager
+finalizes WAB idempotently. A lost finalization response is non-fatal: the next
+verified login finds the published token and repairs the pending state. Missing
+or invalid lifecycle metadata remains fail-closed for established accounts, and
+older WAB servers and clients retain their existing wire behavior.
+
 Authenticated applications can verify a phone number and roll the presentation
 key, including when the user enters the same phone number:
 
 ```ts
 await manager.startPhoneNumberChange('+12065550100')
 await manager.completePhoneNumberChange(code)
-await persist(manager.saveSnapshot())
+await platformKeyStore.storeSecret('wallet-snapshot', manager.saveSnapshot())
 ```
 
 The completion call first stages the verified phone association and new key in
@@ -112,6 +273,29 @@ also resumes an unpublished staged change without committing another key.
 Persist the snapshot immediately after success. Deploy the compatible overlay
 topic and WAB schema/routes before enabling this UI.
 
+### Snapshot security
+
+`CWIStyleWalletManager` and `SimpleWalletManager` snapshots contain wallet root
+key material and intentionally embed the key needed to restore that material.
+Encryption protects their internal representation, but it does not make the
+snapshot safe to disclose: **access to a snapshot is access to the wallet**.
+Store the complete snapshot as a secret in an OS Keychain, hardware-backed
+keystore, or comparably trusted storage. Do not put snapshots in ordinary
+localStorage/AsyncStorage, logs, analytics, crash reports, unprotected backups,
+clipboard data, or cloud sync. If a snapshot may have escaped trusted storage,
+treat the wallet credentials as compromised and rotate them; deleting one copy
+does not revoke other copies.
+
+Remote `StorageClient` and credential-bearing Arcade SSE endpoints require
+HTTPS. Plain HTTP is accepted only for explicit loopback hosts during local
+development. Arcade SSE dependency debug logging remains disabled because its
+request URL and headers carry wallet callback credentials.
+
+Certificate signatures fail closed at every wallet trust boundary. Direct and
+issuer-mediated acquisition require an affirmative certifier-signature result
+before storage, and identity discovery verifies each untrusted overlay
+certificate before decryption or trust scoring.
+
 ### ChainTracks sources and networks
 
 Wallet services do not require a WhatsOnChain key for ChainTracks. Node

package/docs/sync-transfer.md

@@ -0,0 +1,144 @@
+# Bounded wallet sync transfers, version 1
+
+This optional transport carries complete BRC-40 request/response objects across
+HTTP message limits. It does not change the BRC-40 entity order, inclusive
+watermark, ID maps, tombstones, merge rules, or completion condition. Ordinary
+pages continue to use `getSyncChunk` and `processSyncChunk`.
+
+## Negotiation and limits
+
+A migrated Knex-backed `StorageServer` advertises `syncTransfer` in runtime
+settings: `{ version: 1, maxBytes, partBytes, inlineBytes }`. These are transport
+capabilities, not persisted settings columns. `syncTransfers: false` disables
+advertisement and transfer RPCs during a mixed-version deployment. A client
+must not infer support from compact checkpoints or binary JSON alone.
+
+Version 1 accepts frames up to 64 MiB, with parts no larger than 256 KiB. Parts
+are carried by the existing authenticated binary-JSON codec. The frame itself
+stores binary fields directly, avoiding a second base64 encoding. The server
+uses smaller parts for smaller request or response limits, and leaves this
+feature disabled when either limit is below 4096 bytes. This is bounded transfer of
+large records, not unlimited-size or constant-memory database streaming: the
+current storage and merge APIs still materialize a complete record/page. Records
+above the advertised limit fail explicitly; they are never skipped.
+
+## Framing and integrity
+
+A frame starts with a four-byte unsigned big-endian JSON-header byte length,
+followed by that many UTF-8 bytes encoded with the existing binary-JSON escaping
+rules. The header is `{ version: 1, value, fields }`. Each `fields` entry is
+`{ path, length }`: `path` identifies a null placeholder in `value` using object
+keys or numeric array indices. Raw field bytes follow the header in entry order.
+Dates retain their existing ISO JSON representation. Only actual byte views are
+extracted; sync callers first select the declared binary fields with
+`syncChunkBinary`. Ordinary numeric arrays retain their semantics.
+
+Decoders reject invalid lengths, missing/duplicate placeholders, unsafe paths,
+more than 4096 byte fields, paths deeper than 64 levels, trailing bytes, and
+unsupported versions. The manifest SHA-256 covers the entire frame. A receiver
+must verify it before decoding and merging. BRC-103 authentication additionally
+binds every request/response to the authenticated session.
+
+## RPC sequence
+
+After negotiation a `getSyncChunk` request can include `syncTransferVersion: 1`.
+If its normal response exceeds the HTTP ceiling, the server returns
+`{ syncTransfer: manifest }` in the JSON-RPC result instead of HTTP 413. The
+client reads, verifies and decodes the staged frame before exposing the ordinary
+`SyncChunk` to its caller. Requests without the hint keep their legacy response
+shape. This avoids repeated oversized responses and repeated source queries.
+
+Every transfer method takes one object in `params`, including the authenticated
+`identityKey`. Method arguments below are additional fields in that object.
+
+- `beginReadSyncTransfer`: `{ args: RequestSyncChunkArgs }` returns a manifest.
+  The source validates the ordinary sync request and stages an immutable frame.
+- `readSyncTransferPart`: `{ transferId, offset }` returns `{ offset, bytes }`.
+  Offsets are aligned to `partBytes`; the final part may be shorter.
+- `beginWriteSyncTransfer`: `{ digest, totalBytes }` returns a manifest plus
+  `receivedBytes`. Identical staged uploads resume after process restarts.
+- `writeSyncTransferPart`: `{ transferId, offset, bytes }` returns the next byte
+  offset. An identical replay is accepted; changed or out-of-order bytes fail.
+- `commitSyncTransfer`: `{ transferId }` verifies a complete frame containing
+  `{ args, chunk }`, validates the wallet/storage identities and proofs, then
+  invokes the existing atomic page merge with a matching-checkpoint guard.
+- `releaseSyncTransfer`: `{ transferId }` removes only staging data.
+
+Manifests contain `{ transferId, digest, totalBytes, partBytes, expiresAt }`.
+Identifiers and hashes are 64 lowercase hexadecimal characters. Expiry is Unix
+milliseconds. Transfer identifiers never grant access: all lookups also require
+the authenticated wallet identity. Unknown/expired and another user's transfers
+produce the same unavailable response.
+
+## Recovery and resource ownership
+
+The additive `2026-09-09-001` migration creates `sync_transfers` and
+`sync_transfer_parts`. Eight fixed staging slots, at most two per identity,
+bound storage to at most 512 MiB of frame data, plus metadata/database overhead.
+Allocation and part updates serialize through a database row lock, shared across
+replicas. Expired staging is reclaimed on subsequent allocation. The fixed
+15-minute expiry bounds retention but may require restarting an expired record.
+Staging is storage-global operational data and is excluded from BRC-38 exports.
+
+Uploads retain acknowledged pieces across client/server restart. Interrupted
+downloads can retry individual immutable pieces within an attempt; after an app
+restart, sync resumes at the last durable BRC-40 record checkpoint and may
+re-download the incomplete record. No partial record becomes wallet data.
+
+A lost commit acknowledgement is not automatically replayed by the client.
+Retrying sync first rereads the writer checkpoint. A staged commit requires its
+watermark and offsets to match the current durable checkpoint under the page
+transaction; stale commits cannot advance counters twice. Completed transfer
+results are retained until release/expiry, including after a server restart.
+
+Run the wallet migration before enabling the new server code on every replica.
+For rollback, stop transfer traffic, preserve the current database, then use the
+new runtime's Knex migration source to run **only** this migration down (including
+its ledger entry) before restarting the old runtime. This removes incomplete
+staging, not wallet records or committed checkpoints; clients can resume those
+records. Merely leaving an unknown migration in the ledger can prevent an older
+runtime from starting. Never restore an older database over later wallet writes.
+The SQLite migration is transactional; table/slot creation is also restart-safe
+for MySQL's implicit DDL commits.
+
+## Standards scope
+
+BRC-40 is transport-agnostic. This framing is an optional transport extension;
+its reassembled objects retain BRC-40 semantics. Legacy peers still use ordinary
+pages and cannot transfer records above their message limits.
+
+BRC-38 specifies canonical portable wallet exports, and BRC-39 specifies their
+password-encrypted wrapper. This transport changes neither file format. A live
+IndexedDB replica is not itself a BRC-38 or BRC-39 export file. Passing portable
+export/import regression tests is evidence for those tested paths, not a blanket
+claim that every wallet feature or legacy migration is strictly conformant.
+
+## Artifact cost requiring review
+
+The framing, integrity checks, adaptive page controller and validated proof-provider
+lookup add portable code. After integrating upstream security fixes, exact packed
+macOS consumers measured the following bytes. Hermes compression varies slightly
+with build paths.
+
+| Artifact | Raw | Gzip | Brotli | Raw ceiling | Gzip ceiling | Brotli ceiling |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| Vite | 1,716,150 | 404,965 | 316,747 | 1,717,000 | 406,500 | 317,000 |
+| esbuild | 1,338,800 | 368,089 | 295,540 | 1,339,500 | 369,500 | 296,000 |
+| Metro | 1,767,013 | 448,892 | 347,746 | 1,768,000 | 455,000 | 360,000 |
+| Hermes | 3,586,809 | 1,439,723 | 1,133,805 | 3,588,000 | 1,460,500 | 1,135,000 |
+
+Before upstream integration, Linux CI measured Vite gzip at 404,970 and Hermes
+gzip at 1,457,902, above the corresponding macOS measurements. The combined
+ceilings retain that platform allowance and the upstream security artifact costs.
+The combined Linux esbuild artifact measured 369,222 gzip bytes; its ceiling is
+369,500 bytes. The complete hosted platform checks must pass these limits before
+review.
+
+Browser composition contains only the existing SDK, wallet client, noble hashes,
+hash-wasm and IndexedDB dependencies. No Node storage or new dependency enters
+the graph. Server staging and RPC proof orchestration remain outside
+browser/mobile exports. The SDK's combined esbuild consumer measures 560,560 raw
+bytes against a 561,000-byte ceiling; its compressed ceilings are unchanged.
+
+These are explicit feature costs requiring maintainer review under the repository
+artifact-growth policy, not claims of reduced application bundle size.

package/out/src/Wallet.js

@@ -369,7 +369,8 @@ class Wallet {
         })).publicKey;
         try {
             const certificate = new sdk_1.MasterCertificate(vargs.type, vargs.serialNumber, vargs.subject, vargs.certifier, vargs.revocationOutpoint, vargs.fields, vargs.keyringForSubject, vargs.signature);
-            await certificate.verify();
+            if (!(await certificate.verify()))
+                throw new Error('Certificate verification failed');
             await sdk_1.MasterCertificate.decryptFields(this, vargs.keyringForSubject, vargs.fields, vargs.certifier, vargs.privileged, vargs.privilegedReason);
         }
         catch (error_) {
@@ -442,7 +443,8 @@ class Wallet {
         if (!valid)
             throw new Error('Invalid serialNumber');
         this.validateIssuedCertificate(signedCertificate, vargs, certificateFields);
-        await signedCertificate.verify();
+        if (!(await signedCertificate.verify()))
+            throw new Error('Certificate verification failed');
         await sdk_1.MasterCertificate.decryptFields(this, masterKeyring, certificate.fields, vargs.certifier);
         return await (0, acquireDirectCertificate_1.acquireDirectCertificate)(this, auth, {
             ...certificate,