wative-core 2.2.1 → 2.3.9

package/CHANGELOG.md

@@ -2,32 +2,505 @@
 
 All notable changes to `wative-core` are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.3.9] — 2026-08-10
+
+Three breaking items. Two are on paths that were producing results no
+counterparty could act on; the third changes how a refused broadcast is
+reported, on both chains, so that it cannot be read as "safe to send again". Everything else here narrows what error messages reveal, or
+accepts input that was being refused for no reason.
+
+### Security
+- **BREAKING. The endpoint-reply check now covers Solana.** 2.3.6 stopped an
+  endpoint choosing which transaction was watched after a broadcast, but that
+  check only ever applied to EVM sends — the Solana lane still took the reply at
+  face value, so an endpoint could hand back an identifier of its own and report
+  results for a transaction you never sent. That reply is now checked against the
+  transaction that was actually signed, and everything afterwards follows the
+  signed value. A send refused
+  for this reason reports `timeout`, not `failed`, because the endpoint did
+  acknowledge it and the transaction may well have been relayed — look it up by
+  its signed signature before sending anything else, and do not rebuild it with a
+  fresh blockhash. The signed identifier is still reported, so it can be looked
+  up. Endpoints that answer correctly are unaffected.
+- **BREAKING. A refused broadcast reports `timeout`, not `failed`, on EVM too.**
+  The same check on the EVM side already refused an endpoint that acknowledged a
+  broadcast with the wrong identifier, but reported the result as `failed` — the
+  one status a caller reads as "that never went out, send it again". The
+  endpoint did acknowledge it, so those bytes may be on the network: a retry can
+  then take a fresh position and both transactions land. It now reports
+  `timeout`, meaning the outcome is unknown, and the error still names both
+  identifiers. The transaction continues to report the identifier it signed, and
+  awaiting its submission now fails with that same explanation rather than
+  reporting that it was never sent.
+- **An RPC URL missing its scheme was handed back with one attached.** Provider
+  dashboards present an endpoint host-first with the key in the path and no
+  scheme. Pasting that produced an error that repeated the whole value with
+  `https://` prefixed — a ready-to-use secret URL, in a message that can reach a
+  log file or a crash reporter. Both refusals for an unparseable RPC URL now say
+  what is wrong without repeating any of it. A rejected scheme and a blocked
+  host are still named, since those are not the caller's secret.
+- **A value rejected as a malformed number is no longer shown in full.** This
+  completes the sweep 2.3.8 began, which was scoped to address fields and noted
+  that amounts and gas prices were still shown whole — that note no longer
+  applies. A private key or recovery phrase pasted into an amount, a gas price or
+  a gas limit used to appear in the error in its entirety. Such a value is now
+  shortened. It is shortened rather than removed because for a number the
+  rejected text is the diagnosis: a thousands separator, a stray decimal point or
+  an exponent is still perfectly legible.
+- **The last two address errors stopped repeating their value.** A token
+  contract address that is not a valid address, and a network's multicall
+  address, were the two sites the 2.3.8 sweep left. Adding a custom token by
+  contract address is something an end user does by pasting, and the same slip
+  applies. Both now name the field instead of showing its contents.
+
+### Fixed
+- **Malformed typed data, measured.** Of twenty-four malformed payload shapes,
+  twenty-two are now refused with this library's own error code and none escapes
+  as an untyped error. The remaining two — a domain given as an array or a
+  number — are signed deliberately, because every other implementation signs
+  them identically and refusing them would break real callers.
+- **BREAKING. A field whose declared type is not a type at all is now refused.**
+  A type is a name followed by zero or more array suffixes and nothing else.
+  Anything trailing the suffix — `uint256[]extra`, `uint256[2]junk` — or an
+  unclosed bracket such as `uint256[` was accepted, and produced a signature no
+  counterparty could check. Such a payload now reports
+  `PARAMETER_ERROR` naming the type, which is what other implementations already
+  do. Every valid type signs exactly as before, including nested and fixed-size
+  arrays such as `uint256[2][3]`, a zero-padded length such as `uint256[01]`, and
+  the shorthands `uint` and `int`.
+- **An amount too large to exist is refused when you set it, not when you
+  sign.** Every numeric field of an EVM transaction holds a 256-bit value, and
+  a larger one was accepted and carried all the way to signing, which then
+  failed with a message naming neither the field nor the reason. Such a value
+  is now refused immediately and by name. The largest legal value is still
+  accepted, and nothing was ever silently altered.
+- **A wallet's address list can no longer be rewritten in place.** It is
+  declared read-only and, unlike an account's wallet list, nothing enforced
+  that: assigning an entry, truncating it, pushing to it or deleting from it
+  were all accepted, and the next ordinary save wrote the result through. Both
+  lists now refuse those, and both also refuse being frozen or having their
+  prototype changed — neither of which writes anything itself, but both of which
+  make a later legitimate change fail from somewhere the caller cannot connect
+  to what they did. Reading, iterating and the collections' own methods are
+  unchanged.
+- **More invisible characters are removed from names.** Free-text names — a
+  wallet's display name, an asset or network name — are cleaned of characters
+  that carry no glyph before anything else looks at them, so nothing can hide
+  inside a word. Five that were missing are now included, among them the
+  directional isolates, which belong to the same family as the overrides that
+  were already covered. Emoji are untouched.
+- **A malformed Solana address is reported the same way wherever it is given.**
+  Depending on which call it came through, the same mistake produced either this
+  library's own `PARAMETER_ERROR` or a bare decoding error with no code — and in
+  one case nothing at all until much later, from a place that could no longer
+  say which address was at fault. Every one of them now reports
+  `PARAMETER_ERROR` and names the field. Nothing that built before is refused.
+- **A typed-data payload that declares `EIP712Domain` as null no longer throws a
+  raw error.** Naming that key as a field's type, with the key itself set to
+  `null` or `undefined`, produced a `TypeError` from inside the encoder instead
+  of a `PARAMETER_ERROR`. Leaving the key present but empty while nothing
+  references it is a normal payload and still signs, byte for byte as before.
+- **A Solana fee payer naming the sending account is no longer refused.**
+  Signing rejected any fee payer that was not the exact same string as the
+  sender, so supplying the sender's own key as a public-key object or as raw key
+  bytes — both of which build correctly for external signing — was turned away,
+  as was `null`. All three now sign, and describe a transaction identical to
+  leaving the field out. A fee payer naming a genuinely different account is
+  still refused, and is still available for external signing.
+
+## [2.3.8] — 2026-08-09
+
+Typed-data signing (`signTypedData`) is stricter about payloads that were
+producing signatures no counterparty can verify. If you sign typed data, read
+the three breaking items below. Nothing else here changes what is accepted.
+
+### Security
+- **Four address errors no longer repeat the value they rejected.** A
+  destination that is not a valid address, a malformed Solana recipient, a
+  Solana fee payer that differs from the sender, and a transaction whose sender
+  does not match the address signing it: each used to include the value it had
+  just refused. Pasting a private key into a destination field is an easy slip,
+  and the message could then reach anything that records errors — a log file, a
+  crash reporter, a support ticket. Each now names the field that was wrong
+  instead of showing its contents. An address that IS valid is still shown, so
+  a checksum typo remains easy to spot. Note this covers address fields: a
+  value rejected as a malformed *number* — an amount, a gas price — is still
+  shown in full.
+- **BREAKING. A domain carrying an unrecognised field is now refused.** Only
+  `name`, `version`, `chainId`, `verifyingContract` and `salt` are part of an
+  EIP-712 domain. A misspelled or mis-cased field — `chainID` with a capital D,
+  or keys lower-cased by a JSON round-trip — was previously dropped in silence,
+  and the signature was then bound to no chain and no contract at all. Such a
+  payload is refused rather than signed. A domain with no fields still signs,
+  unchanged.
+
+### Fixed
+- **BREAKING. A field typed `uint` or `int` now signs as `uint256`/`int256`.**
+  These are the same types under a shorter name and every other implementation
+  treats them that way; this one did not, so the signature verified as a
+  different address than the actual signer, with no error anywhere. Any
+  signature previously produced for such a field changes — the new one is the
+  one a counterparty accepts. Fields with an explicit width are unaffected.
+- **BREAKING. A fixed-size array field must hold exactly its declared number of
+  values.** `uint256[2]` given three values used to sign something no verifier
+  would evaluate; it is now refused.
+- **Malformed typed data reports this library's error.** Bad values in `message`
+  — a missing or `null` nested struct, a number out of range for its declared
+  width, a malformed address or byte length, an unreadable field — now report
+  `PARAMETER_ERROR` naming the field, instead of escaping as a plain error with
+  no code. Payloads that signed before still sign, and produce the same
+  signature; only the error changed.
+- **A malformed recipient on a native SOL transfer reports this library's
+  error.** Such an address was always rejected, but by an underlying library, as
+  a plain error carrying no code — so it could not be handled alongside every
+  other failure. It now reports `PARAMETER_ERROR` naming the field, and says
+  whether the address is not valid base58 or is the wrong length. Every address
+  that built before still builds; only the error changed.
+
+## [2.3.7] — 2026-08-08
+
+A security and correctness release. Upgrade if you display names your users
+typed, import Solana keys, send Solana transactions, or rely on the password
+strength report.
+
+### Security
+- **A hidden character could smuggle a dangerous link into a display name.**
+  Names, tags and other free-form text are cleaned before storage, and that
+  cleaning removed dangerous prefixes like `javascript:` before it removed
+  zero-width and control characters. A single invisible character placed inside
+  such a prefix therefore survived the check and was then tidied away, handing
+  back exactly the thing that was supposed to have been removed. Anything
+  putting a stored name on a page received a working link. All affected
+  prefixes and every invisible-character class are covered.
+- **The password strength report described a different password than the one in
+  use.** Passwords are normalised before the key is derived, but the strength
+  check read the text exactly as typed. A password written in decomposed form —
+  ordinary for some keyboards and languages — was reported as longer and
+  stronger than the secret actually protecting the wallet, and could pass a
+  minimum-length rule the real one fails. The report now measures what is
+  actually used. Nothing about existing wallets or how keys are derived changes,
+  and the warning about passwords that shift form between machines is unchanged.
+
+### Fixed
+- **A malformed Solana private key is now refused in this library's terms.**
+  Such a key was always rejected, but by an underlying library, as a plain error
+  carrying no error code — so it could not be handled alongside every other
+  failure. It now reports `INVALID_PRIVATE_KEY`, matching what the EVM side
+  already did.
+- **A rejected logging change no longer takes effect anyway.** Changing sinks or
+  the log level while the workspace is locked correctly fails — but the new
+  settings were applied before that failure, leaving the previous sinks closed
+  and, for file logging, records being written under a configuration you were
+  told had been rejected. Nothing changes now unless the change succeeds.
+- **Closing RPC clients now closes all of them.** Solana connections were left
+  open, each holding a network connection and two timers, once per endpoint used
+  for the lifetime of the process.
+- **An expired Solana transaction now says so.** Previously it was polled for the
+  full two minutes and then reported as a timeout — the same answer given for a
+  slow node, though the two call for opposite responses. A timeout means the
+  outcome is unknown and sending another transaction risks paying twice; an
+  expired one can never be accepted, so replacing it is safe. It now ends as
+  dropped, saying the blockhash expired.
+- **Wallet lookup by tag is no longer case-sensitive**, matching how the same
+  method already looked up accounts and addresses. Tags keep the capitalisation
+  you gave them.
+
+### Added
+- **`workspace.damagedAccountSlugs`** lists account records that are present but
+  could not be opened. Such a record is deliberately kept rather than discarded,
+  and creating an account with the same name will not overwrite it — but until
+  now nothing reported that it existed, and the only visible sign was new
+  accounts receiving unexpected names. The list is read-only: removing such a
+  record is left to you, because it may still hold a recoverable recovery
+  phrase.
+
+## [2.3.6] — 2026-08-08
+
+A correctness release for anyone who sends transactions. Several ways a
+transaction could do something other than what you asked, or be reported as
+something it was not, all of them silent.
+
+### Security
+- **A redirect could carry your RPC request to a host you never configured.**
+  The RPC address you set was checked, but a redirect from that address was
+  followed automatically — and the kinds that preserve the request body would
+  re-send the whole call somewhere else, including addresses the check exists to
+  block. Redirects are no longer followed, and one is now reported as a
+  redirect, naming where it was being sent, rather than as an unreachable node.
+- **The transaction being watched was chosen by the endpoint.** After a
+  broadcast, the identifier the endpoint replied with was taken at face value
+  and everything afterwards followed it — so an endpoint could hand back an
+  identifier of its own and report a result for a transaction you never sent,
+  while yours went unwatched. That reply is now checked against the transaction
+  that was actually signed. An endpoint that does not acknowledge a broadcast
+  still reports no identifier, exactly as before.
+  (Scope correction, added in 2.3.9: this covered EVM sends only. The wording
+  above did not say so, and the Solana lane kept taking the reply at face value
+  until 2.3.9.)
+- **A mistyped token contract address was silently corrected.** The same
+  checksum repair that was fixed for transaction destinations in 2.3.5 also
+  applied where you supply a token's contract address. It is now refused.
+  Addresses given entirely in lower or upper case are unaffected.
+
+### Fixed
+- **Call data with an odd number of digits changed the function being called.**
+  It was padded on the left, which shifts every byte — turning a token transfer
+  into a call to something else, with the arguments shifted too. The
+  transaction signed, sent and mined perfectly well; it simply did something
+  else. Such call data is now refused, because what was intended cannot be
+  known.
+- **An automatic nonce could be handed out more than once.** The nonce was
+  requested from the node every time and nothing recorded what had already been
+  used, so transactions prepared before the node caught up all received the same
+  one. Sending three transfers in a row let one arrive while the rest could
+  never be mined, and all three reported as sent. A nonce you supply yourself is
+  still honoured exactly as given, so replacing an in-flight transaction with a
+  higher fee works as before.
+- **A mined transaction could be reported as a failed send.** One unreadable
+  field in an otherwise successful receipt — the gas figures — was enough to
+  report the whole send as failed and to discard the receipt proving the funds
+  moved. Those figures are now read tolerantly and simply omitted when they
+  cannot be read.
+- **An address will not sign for one chain and send to another.** An address and
+  the network it is pointed at could disagree about which chain they belong to;
+  signing now refuses rather than producing a signature for one chain and
+  handing it to another.
+- **A signed transaction's fields can no longer be changed.** Editing a field
+  after signing was accepted and reported back, while the bytes that would be
+  sent still carried the original values. This covers both EVM and Solana
+  transactions. Build a new transaction to change something.
+- **A wallet list handed to you can no longer be modified in place.** Assigning
+  to it changed the account's own list, and the next save wrote that through.
+- **A dropped network no longer comes back.** Saving a network after removing it
+  added it again, in memory and on disk.
+- **A blank address filter no longer matches the first address**, and passing
+  something that is not an account now reports a parameter error rather than an
+  unrelated type error.
+- **Creating an account no longer overwrites one another handle just created.**
+  Two handles open on the same workspace could each create an account with the
+  same name, leaving one record holding the second recovery phrase and
+  destroying the first.
+
+## [2.3.5] — 2026-08-07
+
+A security release. Upgrade if you send EVM transactions, or if you keep more
+than one account in a workspace.
+
+### Security
+- **A mistyped destination address was silently corrected.** An EVM address
+  carries a checksum whose whole purpose is to catch a mistyped character. When
+  a transaction destination arrived with a checksum that did not match, it was
+  quietly rewritten into a valid-looking address rather than refused — so a
+  single wrong character could send funds to an address you never typed, with no
+  warning. Such a destination is now rejected. Addresses given entirely in lower
+  or upper case carry no checksum to check and are unaffected, and address
+  lookup stays as forgiving as before.
+- **An account could overwrite another account's stored secrets.** On macOS and
+  Windows, where file names ignore case, creating an account could write over a
+  stored account whose name differed only in capitalisation — destroying the
+  sealed recovery phrase it held. Names are now checked the way the file system
+  actually compares them.
+- **Two addresses reached cloud metadata services.** The RPC URL check missed one
+  IPv6 spelling of the metadata address, and the well-known metadata host names
+  entirely.
+- **Sealed material no longer appears when an object is logged.** The stored
+  recovery phrase and stored keys were ordinary visible properties, so they
+  surfaced in `console.log` output and in anything that walks an object's
+  properties.
+- **A password policy option set to `undefined` no longer disables it.** Building
+  an options object from optional values — the ordinary way to forward
+  settings — removed the minimum-length rule entirely, so short passwords stopped
+  being reported.
+
+### Fixed
+- **`confirmed` no longer fires for a reverted transaction.** Subscribers were
+  told a transaction had confirmed, receiving a receipt whose own success flag
+  was false, and only afterwards told it failed.
+- **A stray file no longer blocks removing a network.** A single duplicate left
+  in the storage folder — the kind a file manager creates — made network removal
+  refuse permanently.
+- **A log file prefix can no longer choose the directory.** A prefix containing
+  path separators wrote the log outside the folder it was given. Sizes and file
+  counts are validated too.
+- **Aborting a transaction cannot leave a stale finish behind.** Internal
+  finishing can no longer be triggered while a transaction is still in flight.
+- **Key material is cleared in three more places** where an unusual failure —
+  one bad address, an interrupted derivation, a rolled-back add — previously left
+  it in memory.
+
+## [2.3.4] — 2026-08-07
+
+A security release. Upgrade if you hold keys in a long-running process, or if
+you log anything from a Solana wallet.
+
+### Security
+- **Key material could survive `lock()`.** Two separate cases. Records sealed by
+  the optional faster storage format left one readable copy of each record's key
+  in memory after the workspace was locked — and because that format seals each
+  secret the same way, such a copy is the secret itself. Separately, part of the
+  password-derivation scratch space was not being cleared, leaving
+  password-derived bytes resident. Both are now cleared, and both are covered by
+  checks that can actually observe the memory in question.
+- **`lock()` could return while an account stayed unlocked.** An `unlock` that
+  landed at the same moment as a `lock` could complete inside it: the workspace
+  reported locked while the account still held its mnemonic and could sign, and
+  no later `lock()` could reach it. Locking is now closed to that race.
+
+### Fixed
+- **Signing typed data with a `bytes` field.** A `Uint8Array` or `Buffer` was
+  hashed as text rather than as its bytes, so the signature did not match what
+  any other implementation computes — and two containers holding the same bytes
+  gave two different results. Passing a `0x` string was, and remains, correct.
+  Text that is not `0x`-hex is now rejected rather than silently hashed a
+  second, incompatible way.
+- **Malformed typed data now raises the library's own error.** Several shapes —
+  including a `primaryType` naming a built-in type, and a struct that contains
+  itself — escaped as a raw `TypeError` with no error code. (This entry
+  originally gave a count. It was not reproducible against the released build
+  and has been replaced by the property it was trying to describe; the current
+  coverage is stated under 2.3.9.)
+- **Solana signatures and transaction ids are no longer removed from logs.** The
+  redactor treated any long base58 value as a secret, which is exactly the shape
+  of a signature, so the one value worth correlating on disappeared silently.
+  Redaction by field NAME was broadened at the same time, so tokens, passcodes
+  and recovery keys that previously slipped through are now covered.
+- **Logging a non-string no longer throws.** `logger.info(x)` where `x` was
+  undefined, a number or an object took down the caller.
+- **Adopting an account into another workspace** now refuses when that
+  workspace's password would not open it, instead of writing a record that can
+  never be opened again.
+- **Adding an account no longer loses concurrent work.** Wallets derived while
+  the account was being added were kept in memory but never written.
+
+## [2.3.3] — 2026-08-07
+
+A security fix for typed-data signing. Upgrade if you use `signTypedData`.
+
+### Security
+- **A signature could be produced for a value other than the one you were shown.**
+  When a typed-data payload declared a custom type whose name collides with one of
+  EIP-712's own built-in type names, a field of that type was not bound by the
+  signature: every value produced the same result, and an independent verifier
+  read the field as a fixed value nobody chose. The same collision could also
+  detach a signature from the chain and contract it was meant for. Because the
+  payload is normally supplied by the site requesting the signature, this did not
+  require anything unusual from the wallet holder. Such payloads are now rejected
+  with `PARAMETER_ERROR`, which is also what other EIP-712 implementations do, so
+  no payload that they accept is affected.
+
+### Fixed
+- **A retired wallet index could come back.** Dropping a wallet records its index
+  so it is never derived again. If another account setting was changed at the same
+  moment, that record could be lost, and the next `deriveWallets()` returned the
+  same address and private key as the wallet that was dropped.
+- **`sliceWallets` could empty an account.** It kept no minimum, so on an account
+  whose first wallet had already been dropped it could remove every remaining
+  wallet, leaving an account with no keys and reporting no error. It now refuses,
+  as `wallet.drop()` already did.
+- **Aborting a transaction no longer reports a confirmation afterwards.**
+  `abort()` could still fire `confirmed` listeners for a receipt that arrived
+  after the abort, having already reported the failure. The receipt itself is
+  still kept on the tracker — if the transaction did land, you can still see it —
+  but it is no longer announced as a confirmation, and the abort remains the
+  reported cause.
+- **Secrets are cleared in two cases where they were kept.** A wallet drop, or a
+  password reset, that failed because the workspace was locked at that moment
+  could leave key material in memory that a later `lock()` would not reach.
+
+### Changed
+- ⚠️ **`whenFinalized()` now rejects instead of never settling.** Transaction
+  tracking ends at first inclusion, so on EVM — and on Solana whenever the node
+  reports `confirmed` first — this promise previously neither resolved nor
+  rejected. It now rejects with `UNSUPPORTED_OP`. A Solana node that reports
+  finality directly still resolves as before.
+
+  **Migration.** `void tracker.whenFinalized().then(...)` used to do nothing,
+  because the promise never settled; it is now an unhandled rejection and will
+  terminate a Node process. Attach a `.catch()`, or await it. Awaiting it
+  alongside `whenConfirmed()` is unaffected.
+- **A `types.EIP712Domain` list that disagrees with your domain is now rejected**
+  rather than ignored. The domain separator has always been computed from the
+  domain object itself, so a mismatched list previously produced a signature that
+  your own verifier would reject, with nothing to point at the cause. An empty or
+  absent list still works, so the JSON-RPC shape is unaffected.
+
+- ⚠️ **Documented late — this shipped in 2.3.3 without a note.** `record.unlock(password)`
+  on a record that is already open now re-checks the password instead of returning
+  success. Records arrive already open in the common case, so a caller using
+  `record.unlock(pw)` as a password check was previously told yes for **every**
+  string, including a wrong one. It also refuses once the workspace has been locked
+  or the record dropped, where a retained handle used to keep answering password
+  guesses indefinitely.
+
+  **Migration.** If you relied on `unlock()` succeeding for an already-open record,
+  pass the real password. Reading `.value` is unaffected — that is a snapshot you
+  already hold, and it is deliberately not gated.
+
+## [2.3.2]
+
+Not released.
+
+## [2.3.1] — 2026-08-07
+
+A types-only fix. Six types that appear in the public API could not be imported,
+so TypeScript users could call a method but not write down what it took or
+returned. Nothing changed at runtime, and JavaScript users are unaffected.
+
+### Fixed
+- `OpenOptions` (the options bag for `Workspace.open()`), `PasswordCheckContext`,
+  `NetworkConfig`, `AbiItem`, `SplTokenArgs` and `SplTokenAccountSet` are now
+  exported and can be imported by name.
+
+## [2.3.0] — 2026-08-06
+
+Unlocking is much faster. Drop-in from 2.2.x; wallets from 1.x need a manual step first.
+
+### Added
+- An optional storage format that keeps unlocking fast however many addresses an account holds.
+
+### Changed
+- Unlocking is roughly 25x faster. In a browser, allow `'wasm-unsafe-eval'` in your Content-Security-Policy, or it quietly falls back to a much slower path.
+
+### Removed
+- Wallets created by 1.x can no longer be opened — export their secrets with 2.2.x before upgrading.
+
 ## [2.2.1] — 2026-07-29
 
-Documentation and packaging only — the library code is identical to 2.2.0.
+Documentation and packaging only. `dist/` is byte-identical to 2.2.0 — no source changed, so the published build was deliberately left exactly as built and verified for that release.
 
 ### Changed
-- The runnable examples moved from `tests/` to `examples/`; update any path references.
-- Clearer README: how Workspace, Account, Wallet and Address relate, and when to use a recovery-phrase account versus an imported-key one.
+- **The runnable examples ship as `examples/` instead of `tests/`.** They are the only human-readable code in the published package, and `tests/` reads as internal scaffolding nobody is invited to open. The `files` allowlist follows. Consumers who referenced `wative-core/tests/...` by path must update; nothing importable from the package entry changed.
+- **README** gains npm / CI / node / license badges, an ASCII diagram of the containment model (`Workspace > Account > Wallet > Address`), and a section distinguishing the two account kinds. The HD/PK difference is not in the nesting but in what a `Wallet` *means* — a derivation slot holding both an EVM and a Solana key under HD, versus a single imported key on one chain under PK. That was previously described in prose only, and it is the thing new users get wrong first.
 
 ### Fixed
-- One example failed when run from an installed copy.
+- **`11-subpath-imports` example** imported the chain artifacts by relative path into `dist/` rather than by subpath, despite its own header documenting the subpath form. It resolved inside the repo and nowhere else, so it passed in-repo while being broken for every real installation. Caught by the new published-package CI job before release.
+
+### Internal
+- `.github/workflows/ci.yml`: runs the examples against this build on Node 22.12 and 24, and separately installs `wative-core` from the registry into a clean directory and runs the same files against it — exercising the real tarball's `files` list, `exports` map and dependency resolution. Runs weekly as well, since a published package sits on a moving dependency graph.
+- The private development repo is now guarded against reaching npm (`private`, a `prepublishOnly` refusal, and a `publishConfig` registry pointing nowhere). It shares a package name with the public repo, so a stray publish there would have succeeded and replaced the package.
 
 ## [2.2.0] — 2026-07-28
 
-Runs in the browser now. Existing Node code keeps working unchanged.
+> **The browser entry is here.** The main entry now resolves for a browser with **zero** unresolvable Node builtins, and ships an IndexedDB storage backend. **No public API was removed** — existing Node imports keep working unchanged, so this remains a minor.
 
 ### Added
-- **Browser support.** The library works in a web app, keeping wallets in the browser's own storage. See the browser example in the Quick start.
-- **Backup and restore.** Export a workspace as encrypted data and load it somewhere else. A workspace created in a browser opens on a desktop, and the other way round.
-- **Writing your own storage is simpler.** A custom backend now needs six small methods; encryption and file layout are handled for you.
+- **`IdbProvider` — IndexedDB storage backend.** Created via the async factory `IdbProvider.create(name, opts)`, which negotiates durable storage before returning. Exposes `durability` (`"persistent" | "best-effort"`) and a `quota` snapshot.
+- **`ContainerProvider`** — the storage-agnostic base extracted from `HybridProvider`. A custom backend now implements only six primitives (`_exist`, `_listItems`, `_read`, `_write`, `_remove`, `_ensureDir`) and inherits record framing, the encrypted envelope and its identity AAD, the key layout and the container session. Previously `Provider` declared the record API abstract, so a custom provider had to reimplement encryption — which is why the shipped custom-provider example carried a hand-rolled XOR cipher and a warning to use a real one.
+- **`exportContainer()` / `importContainer()`** on `ContainerProvider`. Both require an unlocked workspace and throw `WORKSPACE_LOCKED` otherwise — a precondition that was not stated when they shipped. Sealed records move verbatim — never decrypted, so no key is materialized and nothing is re-keyed. Because every backend shares one framing, a container round-trips IndexedDB ⇄ filesystem and opens with the same password. Import refuses a non-empty target without `{ overwrite: true }` and rejects entries outside the container layout.
+- **`wative-core/node` subpath** — `HybridProvider`, `FileSink` and the default-workspace-path resolver.
+- **`STORAGE_NOT_DURABLE`** error code.
 
 ### Changed
-- `HybridProvider` and `FileSink` are still available from the main import in Node. They also live at `wative-core/node`, which is where new code should get them.
+- **The root entry is condition-split.** A browser bundler resolves the universal core; Node resolves an entry that still re-exports `HybridProvider` and `FileSink`, so `import { Workspace, HybridProvider } from "wative-core"` compiles and runs exactly as before. Those two re-exports are **deprecated** in favour of `wative-core/node` and will be removed in a future major. Condition order is significant — `browser` is declared before `node`, since resolvers take the first match.
+- `tsconfig` `lib` gains `DOM`; the browser is now a real target.
+
+### Browser notes
+- Creating a **new** workspace in evictable storage is **refused** with `STORAGE_NOT_DURABLE` unless `{ acknowledgeEvictionRisk: true }` is passed. Opening an existing workspace is never blocked. Browser storage is evictable and this library holds private keys: Chrome and Firefox treat IndexedDB as best-effort unless `navigator.storage.persist()` is granted, Safari caps script-writable storage at roughly 7 days without user interaction, and private-mode windows may have no IndexedDB at all. Request persistence from a user gesture, and use `exportContainer()` for a durable backup.
+- A **`Buffer` polyfill is still required** — `@solana/web3.js` and `@coral-xyz/anchor` read the global. Standard for any Solana dapp.
 
-### Please note
-- Browsers can clear their own storage. Creating a **new** wallet in a browser is blocked unless the browser promises to keep the data, or you explicitly accept the risk — an existing wallet always opens. Give users a way to back up.
-- A `Buffer` polyfill is needed in the browser. One line, shown in the Quick start.
+### Internal
+- `scripts/browser-e2e.mjs` (`pnpm test:browser`) bundles the real dist through the `browser` condition, loads it into headless Chromium and drives a full lifecycle against the browser's own IndexedDB, asserting the same published BIP-44 vectors the Node suite pins. Resolving is not the same as running — a build can resolve cleanly and still fail at runtime, as a 2.1.0 regression showed. Wired into `prepublishOnly`.
+- The published bundle is exercised under each platform to prove the export map lands where intended; asserting its shape is not the same as asserting a resolver's behaviour.
 
 ## [2.1.0] — 2026-07-28
 
@@ -114,7 +587,7 @@ Runs in the browser now. Existing Node code keeps working unchanged.
 ### Security
 - **Envelope v2 — Argon2id + AAD-bound on-disk records.** New seals use Argon2id (RFC 9106; t=3, m=64 MiB, p=1) and bind every record's GCM tag to its on-disk identity. HybridProvider records bind to `wative:v2:record:<recordType>:<slug>`; per-account mnemonic ciphertexts bind to `wative:v2:account:<slug>:mnemonic`; per-address private-key ciphertexts bind to `wative:v2:account:<slug>:wallet:<id>:<vm>:pk`; recovery envelopes bind to `wative:v2:recovery:account:<slug>`. Closes the blob-swap class of attack where an attacker with workspace-dir write access (but not the password) could substitute one record's ciphertext for another's. Legacy v1 records (PBKDF2-SHA256, no AAD) continue to read; new writes are always v2.
 - **Slug-collision suffix now CSPRNG.** Was `Math.random()`; now `crypto.randomInt`. Prevents predictable filenames in `accounts/<slug>-<suffix>.db`.
-- **`#seed` Buffer scrubbed before drop.** `Account.lock()` now `.fill(0)`s the BIP-39 seed Buffer before nulling the reference. JS string immutability still prevents perfect zeroization of mnemonic + plaintext private keys (documented on `Workspace.lock()`).
+- **The derived seed is zeroed on lock.** `Account.lock()` now overwrites the BIP-39 seed bytes before releasing them. JS string immutability still prevents perfect zeroization of mnemonic + plaintext private keys (documented on `Workspace.lock()`).
 - **`useTestKdfIterations` Jest auto-detect removed.** The `typeof globalThis.expect !== "undefined"` opt-in arm fired in any downstream consumer using Jest, not just our own test process. Now requires explicit `WATIVE_ALLOW_TEST_KDF=1` (or `NODE_ENV=test`). Internal-only function; not on the package surface.
 
 ## [2.0.1] — 2026-04-29