Harden wallet lifecycle: remove implicit auto-init, enforce explicit identity boundary

[nulllpc]

Summary

This PR removes the reactive, implicit wallet auto-initialization model and replaces it with an explicit, race-free lifecycle centered entirely in useWalletManager

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

[nulllpc]

It started as cleanup of a deprecated prop and turned up a real identity-boundary bug along the way. So I did a deeper refactoring and the result was pretty satisfying. Here's a detailed report of what I found:

Motivation

WdkAppProvider defaulted enableAutoInitialization to true, which drove a reactive effect in useWalletOrchestrator that auto-created/unlocked wallets whenever currentUserId and the worklet were ready - bypassing whatever biometric/auth gate the consuming app built. Auditing that path surfaced a confirmed, reproducible bug: a persisted activeWalletId could get silently unlocked after the app moved to a different user, and switching users could report READY without the new wallet ever being initialized.

Approach

• Removed the implicit lifecycle entirely. Deleted enableAutoInitialization, currentUserId, retry, and clearSensitiveDataOnBackground/useAppLifecycle — all either dead, unused, or actively fighting the "consumer owns auth" model. useWalletOrchestrator is now a pure state-derivation hook with no side effects.
• Closed the identity-boundary bug at the root, not with a patch:
  • activeWalletId is no longer persisted to disk — identity is caller-owned, so nothing should silently outlive a session/user change. Existing installs get it force-reset on every rehydrate too, not just future writes.
  • unlock(walletId) now requires an explicit id; no implicit fallback to whatever the store happens to hold.
  • READY status now requires the loaded wallet's identifier to actually match activeWalletId, not just "something is initialized."
  • Removed setActiveWalletId, an unguarded setter with no real callers that was the most direct way to desync identity from what's actually loaded.
• Extended the same discipline everywhere it was missing. createWallet and restoreWallet had the exact same "can silently overwrite an active session" gap as the original unlock bug — both now reject unless the caller explicitly lock()s first. lock() itself now shares the same operation mutex as every other lifecycle call, closing a race where it could be silently undone by an in-flight unlock/createWallet/etc. completing afterward. Added switchWallet(walletId) as the one deliberate convenience (atomic lock() + unlock()) for the genuinely frequent case of switching between existing accounts.
• Removed dead weight found along the way: an unexported, unused WalletSwitchingService implementing a second, less-safe wallet-switching path with none of the above guards.
• Rebalanced test coverage — dropped ~20 tests that were coverage padding on trivial pass-throughs, replaced with tests that actually pin the identity-boundary invariant, mutex atomicity, and manual lock→unlock composition.

Net result: all wallet identity mutation lives in one place (useWalletManager), behind one real mutex, with no path left that can move activeWalletId without doing the corresponding work.

Breaking changes

• WdkAppProvider: removed enableAutoInitialization, currentUserId, clearSensitiveDataOnBackground props.
• useWdkApp/WdkAppContextValue: removed retry.
• useWalletManager: removed setActiveWalletId; added switchWallet; unlock(walletId) now requires an explicit argument; lock() now returns Promise<void> (callers should await it before chaining another lifecycle call); createWallet/restoreWallet now throw if a wallet is already active - callers must lock() first.

[nulllpc]

Breaking Changes

Each item below only applies if the removed/changed API was actually used. If a given prop or method was never called, no action is needed for that item.

• enableAutoInitialization, currentUserId, and clearSensitiveDataOnBackground have been removed from WdkAppProvider. Call unlock(walletId) / createWallet(walletId) explicitly instead of relying on auto-init; for background locking, listen to AppState directly and call lock().

• retry() has been removed from useWdkApp. Re-call whichever lifecycle method failed (unlock/createWallet/restoreWallet) instead.

• state.walletId is now optional when status === 'LOCKED' (previously always a string). The undefined case needs to be handled.

• setActiveWalletId has been removed. unlock/createWallet/restoreWallet/switchWallet manage identity correctly as part of doing real work and should be used instead.

• unlock() now requires an explicit walletId argument (previously optional).

• lock() now returns Promise<void> (previously void) and shares a mutex with unlock/createWallet/restoreWallet/switchWallet. It must be awaited before calling another lifecycle method - await switchWallet(id) handles switching wallets in one call.

• createWallet/restoreWallet now throw if a wallet is already active, instead of silently overwriting the session. lock() must be awaited first.

• activeWalletId is no longer persisted across app restarts. Identity must be re-established on every launch (e.g. calling unlock(userId) from the app's own session state).

Also Fixed

• NO_WALLET no longer misreports right after lock() when a wallet is actually known to exist - it now only fires when confirmed empty.

[NirmalPatidar]

Please rebase onto main before merge. This branch is 8 commits behind main (missing PR #78 swidge protocol support, the beta.14 release/version bump, and a dependabot postcss bump). As-is, this diff shows package.json going from 1.0.0-beta.15 → 1.0.0-beta.13, @tetherto/pear-wrk-wdk downgrading from beta.10 → beta.8, and 'swidge' being silently dropped from useProtocol.ts's protocolType union. None of that is intentional — it's just staleness — but merging as-is would revert those changes.

[NirmalPatidar]

On unlock(): this only checks whether something is ready (walletLoadingState.type === 'ready'), not whether it's the requested wallet — so unlock('wallet-b') while wallet-a is active silently resolves without switching, leaving wallet-a active. That's confirmed intentional by the new test (should not switch identity when unlock is called directly while a different wallet is ready), but it's inconsistent with createWallet/restoreWallet, which now throw in the identical scenario. A caller has no way to distinguish "already where I wanted to be" from "my request was silently dropped." Could we either make unlock throw the same way when a different wallet is active, or at minimum only no-op when walletLoadingState.identifier === walletId?

On restoreWallet/createWallet: nice, this correctly closes the same gap unlock used to have — throwing instead of silently overwriting an active session. It'd be good if unlock matched this pattern too (see comment above).

[NirmalPatidar]

"unlock, createWallet, and restoreWallet all reject if a wallet is already active" — this isn't accurate for unlock. Per the actual implementation (and the test should not switch identity when unlock is called directly while a different wallet is ready), unlock silently no-ops and resolves rather than rejecting. Either the doc needs to say "silently no-ops" instead of "reject," or unlock's behavior should be changed to match (see the useWalletManager.ts comment above) — but the two should agree either way.