Encrypt the wallet file with a password derived from the mnemonic

[peachbits]

Fixes the wallet-file half of Zano wallet file passphrase (Kimi K3 F8a, High / conditional Critical), relocated here from EdgeApp/edge-currency-accountbased#1082 so the library that owns the wallet-file API owns its encryption. The accountbased PR shrinks to offline mnemonic utilities.

The problem

startWallet used its one seedPassword argument for two unrelated roles: decrypting the seed phrase, and encrypting the wallet file on disk. The seed passphrase is the empty string for every wallet created in-app and every import that does not set one, so those files — which hold the seed and spend keys — were effectively unencrypted. On iOS they live in the documents directory, which reaches iCloud/iTunes backups.

The fix

The file password is now derived from the mnemonic: domain-separated SHA-512, first 16 bytes as 32 hex characters. 32 chars is deliberate — Zano caps wallet-file passwords at 40 over a restricted alphabet (PASSWORD_REGEXP, enforced inside wallet2::generate), so a longer password would pass restore/open and then fail the moment anything called generate. The derivation is pinned by a golden-vector test; changing it orphans every file already encrypted with it.

Migration happens inside startWallet, decided entirely by what the file does (idempotent, self-healing, no persisted state):

1. File absent → restore with the derived file password and the real seed password, now distinct.
2. Opens with the derived password → done.
3. WRONG_PASSWORD → try the legacy passwords (seedPassword, then ''), and on a hit: resetWalletPassword → closeWallet → reopen to verify.
4. Anything unrecoverable → delete and rebuild from the mnemonic, costing one re-scan.

Signature is backward-compatible (new optional log callback only), and thrown errors keep the exact historical <code> <message> shape — accountbased's error.message.includes('ALREADY_EXISTS') recovery is pinned by a test, trailing space included.

Why the sequence is shaped this way

Verified against the pinned SDK (zano_native_lib 239d4a39 → Zano d6be0ecf), each of these silently corrupts wallets if ignored:

• reset_wallet_password only assigns the in-memory password (wallet2.cpp:3196). The file is re-encrypted when the wallet next stores, which closing does — so the close result is checked and the migration only believed after a verify-reopen.
• closeWallet, not stopWallet: the async 'close' path discards close_wallet's return code and always reports OK (plain_wallet_api.cpp:779-785), so it cannot confirm the file was written.
• Never re-key via store(path, password): it encrypts the keys blob with the argument but the body with m_password (wallet2.cpp:3500 vs :3524), producing a file that opens, fails to deserialize its body, wipes history, and silently re-scans. There is a comment against it in the code.

Also fixed while here: the catch-all macros report failure as success-shaped payloads ({result:{return_code:"INTERNAL_ERROR ..."}}, or UNINITIALIZED before init), which previously resolved into a WalletDetails with an undefined wallet_id. And generateSeedPhrase no longer leaves its side-effect wallet file on disk — the caller only wants the seed, and the first startWallet recreates the file properly via restore.

Testing

New mocha suite (npm test, first test infrastructure in this repo): 21 tests running the real CppBridge against a fake native module at the callZano string-protocol level. The fake mirrors the semantics that matter — resetWalletPassword mutates only in-memory state, and closing is what persists it — so dropping the close-to-persist step fails the suite. Covered: fresh restore with distinct passwords, re-key from '' and from a real passphrase (exact call sequence asserted), idempotence, failed reset, failed close, no-known-password rebuild, ALREADY_EXISTS rethrow with message-shape pin, success-shaped error payloads, and the derivation golden vector.

Pure TypeScript — no native code changes. The .cpp/binary layer is untouched; resetWalletPassword was already wired natively.

Release notes for whoever publishes

This should ship as 0.4.0 (behavior change: files get re-keyed on open). Both consumers currently declare ^0.3.0, which does not admit 0.4.0 — accountbased and the GUI bump their pins at merge time, per the usual stacked-PR flow. prepack runs the full native rebuild; before npm publish, verify the packed tarball contains all four Android .so files and the iOS xcframework, with sizes comparable to 0.3.0 — two past releases shipped with bad binaries.

Not yet done, required before shipping: the on-device QA pass, in particular sending from a migrated wallet, which is the only real proof the re-key preserved the spend key.

---

Note

High Risk
Changes wallet file encryption, on-disk migration, and backup exclusion for seed-bearing paths; mistakes could corrupt wallets, leak keys via backups, or mis-handle passphrases.

Overview
Wallet files are no longer encrypted with the seed passphrase (often empty). deriveWalletFilePassword hashes the normalized mnemonic into a stable 32-character file password; startWallet uses it for restore/open while keeping the seed passphrase separate.

startWallet now migrates existing files: open with the derived password, fall back to legacy passwords, re-key via resetWalletPassword + closeWallet with verify-reopen, or delete/rebuild when safe. Wrong seed passphrases and concurrent ALREADY_EXISTS cases throw instead of overwriting. An optional log callback reports recovery and re-key events.

ZanoError carries native return codes; handleRpcResponse throws on error payloads and non-OK return_code values so callers do not get wallets with undefined wallet_id. generateSeedPhrase deletes the side-effect wallet file after closing.

On iOS, ZanoModule pre-creates wallets, logs, and app_config and marks them excluded from backups. update-sources checks SDK folder #defines against that list; submodule update uses --force for repeatable prepack.

Adds npm test (mocha + fake native module), tweetnacl for derivation, and tsconfig.eslint.json for lint/verify over tests and scripts.

^{Reviewed by Cursor Bugbot for commit f69632f. Bugbot is set up for automated code reviews on this repo. Configure here.}

---

• To see the specific tasks where the Asana app for GitHub is being used, see below:
  • https://app.asana.com/0/0/1217260686418273

[cursor]

Stale comment

{"review_module":"platform_pattern_reviewer","findings":[]}

  

_{Sent by Cursor Security Agent: Security Reviewer}

[j0ntz]

Review pass over this PR. The migration logic is careful and the test suite is genuinely thorough, so most of this is about edge paths rather than the core design. I verified the derivation and the migration matrix by running the suite locally at this head (27 passing, npm install --ignore-scripts then mocha).

1. rebuild() trusts a delete the code itself says cannot be trusted (src/CppBridge.ts:371)

const rebuild = async (): Promise<WalletDetails> => {
  await this.deleteWallet(storagePath)
  return await restoreFresh()
}

The comment in generateSeedPhrase already states the native layer "reports OK regardless" of whether the delete succeeded. If the file survives, restoreFresh() calls restore() against a path that still has a file, which the fake models as ALREADY_EXISTS (test/fakeZanoModule.ts:84). Neither rebuild() call site catches it, so it propagates to edge-currency-accountbased, whose recovery is "adopt the already-open wallet by storage path". Nothing is open, so the lookup finds nothing and the wallet is stuck: no known password opens it, and every retry repeats the same failed rebuild.

The suite does not cover this because the fake's deleteWallet unconditionally succeeds (fakeZanoModule.ts:127-130). Suggest checking the delete result, or re-listing getWalletFiles() afterward and failing loudly if the path is still present.

2. The new SDK-folder tripwire cannot actually fail the build (scripts/update-sources.ts)

checkSdkFolders() is documented as "Fails the build if the SDK declares a directory we do not handle", and it throws. But the file ends with:

main().catch(error => console.log(error))

The throw is caught, logged, and the process exits 0. Since update-sources is the prepack script, a tripped check (or any fetch/build failure) still produces a "successful" npm pack / npm publish against a stale ios/ZanoModule.xcframework. That line is pre-existing rather than introduced here, but this PR is what gives it something to lose. One-line fix:

main().catch(error => {
  console.error(error)
  process.exitCode = 1
})

3. A transient verify-reopen discards a wallet file that was already migrated (src/CppBridge.ts:437)

In the legacy-password loop, once resetWalletPassword and closeWallet both succeed the file is genuinely re-keyed and held is false. If only the confirming openWith(filePassword) throws something other than ALREADY_EXISTS, the catch skips the held branch and falls straight into rebuild(), deleting a correctly-migrated file and forcing a full rescan. Consider retrying the verify open once, or treating a failed verify as non-fatal given the file is already correct. Only the ALREADY_EXISTS branch has coverage.

4. Rebuilding on "no known password" is a silent history wipe (src/CppBridge.ts:472)

The docstring calls this out, so this is a design question rather than a defect. Reaching this branch means something unexpected happened: a corrupt file, an unknown password scheme, or a native error mapped to WRONG_PASSWORD for a non-password reason. Funds are safe since the wallet is deterministic, but transaction history and labels go, and the caller gets a successful result with only a log line. Worth considering whether this branch should throw and let the caller decide rather than rebuild unprompted.

5. Em-dash in CHANGELOG.md:14

The - security: startWallet now encrypts... entry uses U+2014. It is the only one across the four Zano PRs, and the very next line uses --. A comma reads the same. Full ruleset: https://github.com/EdgeApp/edge-dev-agents/blob/main/.cursor/skills/no-slop/SKILL.md

6. Question rather than a finding: getOpenedWallets returns the wallet-file password

wallets_manager::get_opened_wallets sets owr.pass = ...get_wallet_password(), so the response carries the plaintext file password for every open wallet. WalletDetails does not declare pass, but the JSON still crosses the bridge. Given this PR exists specifically to protect that password, worth confirming nothing downstream logs raw RPC responses. edge-currency-accountbased#1082 adds a getOpenedWallets call on every view-key request.

7. Nothing runs the new test suite

This repo has no .github/workflows, so the mocha suite added here never runs on a PR. It passes today, so turning it on is cheap. Note a plain npm ci triggers prepare (husky + lint-staged + tsc) and prepack (update-sources, a full native build), so a test job wants --ignore-scripts.

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit c0a000c. Configure here.}

[peachbits]

As of 6292d00.

1. rebuild() trusts a delete the code itself says cannot be trusted. Fixed. It confirms with isWalletExist, a filesystem probe, rather than reading the getWalletFiles listing. Bugbot caught that my first attempt was still fail-open, since getWalletFiles is typed WalletFiles | {} and I treated a missing items field as proof the file was gone.

2. The SDK-folder tripwire cannot fail the build. Fixed on #15, since that PR is what rewrites the script. main().catch now sets process.exitCode = 1. This one had already cost me an afternoon before you raised it: the script no-opped on a missing ANDROID_HOME and exited 0.

3. A transient verify-reopen discards a migrated file. Fixed. Once the close has reported OK the file really is re-keyed, so only a wrong password on the confirming open means the migration missed. Anything else leaves the file alone.

4. Rebuilding on "no known password" is a silent history wipe. Kept, but narrowed, and the narrowing came out of this. Rebuilding restores from the mnemonic with seedPassword, so it only reproduces this wallet when that is the passphrase the file was written with. Opening the file with seedPassword proves that; opening it with '' does not, and 0.3.0 wrote '' for wallets it believed had none. Both the post-loop path and the re-key failure path now refuse to rebuild when those disagree, so a wrong passphrase can no longer delete an intact file or write a different wallet over it.

Detecting a weakly keyed file is unaffected and there is a test pinning it: a wallet that has a passphrase but whose 0.3.0 file was keyed with '' still re-keys in place, because both candidates are tried before the guard.

For wallets with no passphrase it still rebuilds behind a log line. That is your original point, and it is a deliberate call on our side.

5. Em-dash in the changelog. Fixed.

6. getOpenedWallets returns the wallet-file password. Confirmed and accepted for now. Nothing in the bridge logs raw RPC responses. Narrowing it would mean a new native method for the two accountbased callers, which we would rather not add here.

7. Nothing runs the new test suite. Still open. The repo has no .github/workflows at all. Agreed that it is cheap, and noted on the --ignore-scripts caveat, since a plain npm ci triggers prepack and a full native build.