wative-core 2.2.1 → 2.4.0

package/LICENSE

@@ -53,3 +53,117 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+================================================================================
+THIRD-PARTY NOTICES
+================================================================================
+
+The terms above are the terms under which the copyright holder licenses the
+portions of the Software that the copyright holder authored.
+
+The distributed form of the Software (the files under `dist/`) additionally
+embeds compiled components authored by third parties, listed below. Each is
+governed by its own license, reproduced here as those licenses require. Nothing
+in this section alters the terms above as they apply to the copyright holder's
+own work, and nothing in the terms above — including the attribution condition —
+imposes any obligation on the third-party components beyond what their own
+licenses state. A recipient who obtains those components from their original
+authors receives them under their original terms alone.
+
+--------------------------------------------------------------------------------
+1. hash-wasm — MIT License
+--------------------------------------------------------------------------------
+
+Two compiled WebAssembly modules (Argon2 and BLAKE2b) extracted from hash-wasm
+4.12.0 are embedded in the distributed bundles as base64 constants.
+
+    https://github.com/Daninet/hash-wasm
+
+MIT License
+
+Copyright (c) 2020 Dani Biró
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Embedded C implementations might use other, similarly permissive licenses.
+Check the beginning of the files from the /src directory.
+
+--------------------------------------------------------------------------------
+2. The Go Authors — BSD 3-Clause License
+--------------------------------------------------------------------------------
+
+The embedded Argon2 WebAssembly module is compiled from hash-wasm's
+`src/argon2.c`, which states: "Based on Golang's Argon2 implementation from
+crypto package". That implementation is golang.org/x/crypto/argon2, distributed
+under the following license. Clause 2 requires this notice to accompany
+redistribution in binary form.
+
+Copyright (c) 2009 The Go Authors. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+   * Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+   * Redistributions in binary form must reproduce the above
+copyright notice, this list of conditions and the following disclaimer
+in the documentation and/or other materials provided with the
+distribution.
+   * Neither the name of Google Inc. nor the names of its
+contributors may be used to endorse or promote products derived from
+this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+--------------------------------------------------------------------------------
+3. BLAKE2 reference implementation — CC0 1.0 Universal (credit only)
+--------------------------------------------------------------------------------
+
+The embedded BLAKE2b WebAssembly module is compiled from hash-wasm's
+`src/blake2b.c`, the BLAKE2 reference C implementation. Its author offers it
+under CC0 1.0, the OpenSSL License, or the Apache License 2.0, at the
+recipient's option. CC0 1.0 is elected here, which waives all attribution
+requirements. The credit is retained regardless:
+
+    BLAKE2 reference source code package - reference C implementations
+    Copyright 2012, Samuel Neves <sneves@dei.uc.pt>.
+    Released under CC0 1.0 Universal.
+    https://creativecommons.org/publicdomain/zero/1.0/
+    https://blake2.net
+
+--------------------------------------------------------------------------------
+Other dependencies
+--------------------------------------------------------------------------------
+
+Every other third-party library this package uses is a declared runtime
+dependency, resolved from `node_modules` at load time and not embedded in
+`dist/`. Each ships its own license with its own package; no reproduction is
+required or attempted here.
+================================================================================

package/README.md

@@ -152,9 +152,25 @@ await ws.lock();
 | Extra setup    | none                                   | `Buffer` polyfill                |
 | Keys can vanish| no                                     | yes — storage is evictable       |
 
-`HybridProvider` and `FileSink` are also re-exported from the package root in
-Node, so existing imports keep working. New code should take them from
-`wative-core/node`.
+`HybridProvider`, `HybridProviderV3` and `FileSink` are re-exported from the
+package root in Node.
+
+Take the provider from the **same entry point** as `Workspace`:
+
+```ts
+// Right — one entry point.
+import { Workspace, HybridProvider } from "wative-core";
+const ws = await Workspace.open(new HybridProvider("~/wallets"), password);
+
+// Wrong — rejected with a PARAMETER_ERROR naming the fix.
+import { Workspace } from "wative-core";
+import { HybridProvider } from "wative-core/node";
+```
+
+Each entry point is a separate bundle with its own class identities and module
+state, so a provider built by one is not recognised by a `Workspace` from the
+other. `Workspace.open` rejects it with an error naming the fix. A bare
+`import "wative-core/node"` for its side-effects is unaffected.
 
 ### Browser: the Buffer polyfill
 
@@ -207,6 +223,128 @@ const backup = await provider.exportContainer(); // still encrypted
 await otherProvider.importContainer(backup);     // same password opens it
 ```
 
+## Key derivation
+
+Passwords are stretched with Argon2id (RFC 9106) at t=3, m=64 MiB, p=1 before
+they ever touch a key. That is deliberately expensive, and an account unlock
+runs one derivation per sealed secret — so the implementation matters.
+
+By default it runs on a vendored WebAssembly build: no native binary, no build
+step, nothing to install. Measured over a full workspace lifecycle it is about
+**25x** faster than the pure-JS implementation it replaced.
+
+### Browser: grant `'wasm-unsafe-eval'`
+
+```
+Content-Security-Policy: script-src 'self' 'wasm-unsafe-eval'
+```
+
+Without it the browser blocks WebAssembly compilation entirely — synchronously
+and asynchronously, main thread and worker alike. **Nothing throws.** Key
+derivation quietly falls back to a pure-JS implementation that produces
+identical bytes roughly 17x slower, so unlocking a wallet with a dozen addresses
+goes from under a second to tens of seconds. The fallback is announced once on
+the console and reported permanently by `argon2BackendInfo()`.
+
+## Upgrading to 2.3.0
+
+**v1 containers can no longer be opened.** Support for the v1 envelope
+(PBKDF2-HMAC-SHA256, written by wative-core 1.x) was removed and there is no
+migration path in this release. Containers written by any 2.x version are v2 and
+open unchanged.
+
+If you hold a v1 container, recover it with **2.2.x or earlier** before
+upgrading. `exportContainer()` will not do it — it copies sealed bytes without
+decrypting, so the export is as unreadable as the original. Use the accessors
+that return plaintext:
+
+```ts
+// under wative-core 2.2.x — NOT 2.3.0, which can no longer open a v1 container
+import { Workspace, HybridProvider } from "wative-core";
+
+const ws = await Workspace.open(new HybridProvider("~/wallets"), password);
+
+for (const account of ws.accounts) {
+  await account.tryUnlock(password);
+
+  // HD accounts: the mnemonic regenerates every derived key, so it is the only
+  // thing you need.
+  if (account.organizationType === "HD") {
+    console.log(account.slug, "mnemonic:", account.dumpMnemonic());
+    continue;
+  }
+
+  // PK accounts: there is no mnemonic, so every imported key must be kept.
+  // `dumpPrivateKey` lives on the WALLET and takes the VM of the address you
+  // want — a wallet holds at most one address per VM.
+  for (const wallet of account.wallets) {
+    for (const address of wallet.addresses) {
+      console.log(account.slug, wallet.id, address.vm, wallet.dumpPrivateKey(address.vm));
+    }
+  }
+}
+```
+
+Keep that material somewhere safe, upgrade, then re-import it with
+`accounts.create(...)` and `importPrivateKey(...)`.
+
+Three public members were removed with v1: `Provider.passwordTanren`,
+`ContainerProvider.passwordTanren` and `HybridProvider.kdfIterations`. All three
+existed only to expose the PBKDF2 derivation.
+
+### One derivation per container: `HybridProviderV3` (Node only)
+
+```ts
+import { Workspace, HybridProviderV3 } from "wative-core";
+
+const ws = await Workspace.open(new HybridProviderV3("~/wallets"), password);
+```
+
+The default provider derives an Argon2 key per sealed secret, so unlocking an
+account costs one derivation per address — at production parameters that is
+essentially the whole cost, and it grows with the account. `HybridProviderV3`
+derives once per container instead. Measured: unlocking a 50-address account
+goes from 7.3 s to 144 ms, and the v3 figure does not grow with the address
+count.
+
+It is opt-in, and Node-only: it derives through native `@node-rs/argon2`, which
+has no browser build. In a browser use `HybridProvider`, which needs no binary
+and no install and is already about 25x faster than what preceded it.
+
+⚠️ **The speedup applies to records written as v3, not to ones you already
+have.** Pointing `HybridProviderV3` at a container built by 2.x keeps every
+existing secret on its own salt, so it keeps costing one derivation each — the
+container still opens, it just does not get faster. Rewriting an account's
+secrets with `account.resetPassword(old, new)` converts them. A container
+reaches one derivation once all of its records have been written as v3, which
+happens on its own only for containers created under v3.
+
+The first v3 unlock of an existing container costs one extra derivation, once,
+and converts its CONFIG record to v3 — after which wative-core 2.2.x and earlier
+can no longer open it.
+
+Reads do not depend on the choice — every record carries its own version byte,
+so either 2.3.0 provider opens either format, in both directions. ⚠️ But **older
+library versions cannot read v3**: wative-core 2.2.x and earlier know only v1 and
+v2 and will fail with `Unknown envelope version: 3`. Adopting v3 is a one-way
+door with respect to the library version.
+
+### Checking which implementation ran
+
+```ts
+import { argon2BackendInfo } from "wative-core";
+
+argon2BackendInfo();
+// { backend: "wasm", wasm: true, overrides: [] }
+// { backend: "noble", wasm: false, reason: "...", overrides: [] }  ← degraded
+// { backend: "unresolved", wasm: false, ..., overrides: ["node-rs"] }
+```
+
+`backend` is the process-wide default. A provider may carry its own — a
+`HybridProviderV3` does — so check **`overrides`** to confirm the native path
+took. It is a pure read and resolves nothing, so before the first unlock it
+honestly answers `"unresolved"`.
+
 ## Runnable examples
 
 An `examples/` folder ships with the package — runnable JavaScript files demonstrating every domain's use cases. Read them top-to-bottom as walkthroughs, or run them as integration tests via Node's built-in test runner.
@@ -236,7 +374,7 @@ The library is organized around seven things you'll work with:
 - **`Address`** — an on-chain identity. Sign messages, build transactions, send them.
 - **`Network`** — chain metadata. 10 networks ship pre-loaded.
 - **`Asset`** — token metadata. 25 tokens ship pre-loaded.
-- **`Transaction`** — `EvmTransaction` or `SvmTransaction`. Subscribe to lifecycle events (`change` / `confirmed` / `failed`) or await terminal states (`whenSubmitted` / `whenMined` / `whenConfirmed` / `whenFinalized`).
+- **`Transaction`** — `EvmTransaction` or `SvmTransaction`. Subscribe to lifecycle events (`change` / `confirmed` / `failed`) or await terminal states (`whenSubmitted` / `whenMined` / `whenConfirmed` / `whenFinalized`). Tracking stops at first inclusion, so `whenFinalized()` rejects `UNSUPPORTED_OP` unless the node reported finality directly.
 
 Everything is encrypted on disk under your workspace password.
 
@@ -568,10 +706,11 @@ import { TokenProgram, Token2022Program } from "wative-core/artifacts/svm";
 
 ## Compatibility notes
 
+- **Content-Security-Policy (browser)**: grant `'wasm-unsafe-eval'` in `script-src`, or key derivation silently degrades to a ~17x slower pure-JS path. See [Key derivation](#key-derivation).
 - **Runtime**: Node.js 22.12+. Deno / Bun / browser support is partial. Some chain libraries that ship as compiled dependencies do not have universal builds yet.
 - **Platform builds**: a few compiled dependencies lack pre-built binaries for Windows-ARM64 and Alpine-musl. Most installs on macOS / Linux x64 / Linux ARM64 won't notice.
 - **One process at a time**: opening the same workspace from two Node processes simultaneously isn't supported.
 
 ## License
 
-[BUSL-1.1](./LICENSE) — Business Source License 1.1.
+[Modified MIT](./LICENSE) — MIT terms with one added condition: products or services earning over US$50,000 monthly revenue must display "Wative" in their user interface. Everything else is standard MIT. The `LICENSE` file also carries third-party notices for the compiled components embedded in `dist/`.