Skip to content

Add isolated Assisted Multisig preview and verification foundations - #7041

Draft
antuz123 wants to merge 31 commits into
sprintfrom
feature/recoverable-wallet-preview
Draft

antuz123 wants to merge 31 commits into
sprintfrom
feature/recoverable-wallet-preview

Conversation

@antuz123

@antuz123 antuz123 commented Oct 8, 2026 •

Copy link
Copy Markdown
Collaborator

Purpose

Continue the separately installed, testnet-only Assisted Multisig engineering preview toward verifiable wallet functionality. The setup/recovery walkthrough is simulated and creates no spendable wallet, hardware session, cloud backup or Server Key. The explicit Test Mobile Key → Check Key diagnostic can create a real unbacked-up Preview key; it never enables wallet readiness.

Current change (8c0656d2f41af4e49992b103c687278647d2ef7b)

  • Add native Android/iOS read-existing operations under the exact Preview identity guards. The diagnostic creates/loads once, then reloads without permission to generate a replacement. Validate complete testnet BIP48 public metadata and snapshot each observation before asynchronous reads.
  • Extract the actual Android storage core for executable Kotlin/JVM tests. Preserve process/file locks, Keystore alias/record mismatch rejection, interrupted-write artifacts, authenticated AES-GCM and durable readback. Bound corrupted-file reads to the fixed record size. Improve best-effort clearing of owned native buffers.
  • Reject duplicate underlying account public keys despite altered tpub metadata, fingerprints or chain codes; reject malformed inheritance/quorum overrides and inherited/accessor/private data. Bound and audit public Coldcard/Jade exports while keeping possession and policy verification explicitly pending.
  • Verify final-transaction ECDSA witnesses for all three 2-of-3 pairs, receive/change and boundary indices. Reject altered signatures, inputs, amounts, outputs, witness order and outsider keys. Synthetic UTXOs only; no broadcast or Bitcoin Core consensus execution.
  • Add disconnected local backup fixtures with fixed PBKDF2-SHA256/AES-256-GCM, fresh randomness requests, authenticated versioned context, exact independently held policy/Mobile identity binding, and verified write/readback. Verification returns evidence only: no native seed import or wallet activation. Native crypto defaults unavailable; cloud/native-restore/wallet flags remain false.
  • Add a scoped Recoverable Preview checks workflow for the native core/bridge harness and offline regressions. Refresh stale documentation and carry forward the current sprint AGENTS.md contract.

Preserved boundaries

Separate Android/iOS app IDs, no-backup/cloud namespaces and unreachable Preview service configuration remain. Normal/mainnet behavior is unchanged by this continuation. Earlier PR changes in shared onboarding/Home/navigation/saga files remain preview-guarded and still need native regression review. No R4 or Reproducibility changes are folded in.

The UI still models fixed Mobile + chosen Hardware + Server 2-of-3, with optional inheritance before final review. TAPSIGNER/Satochip/Jade delayed inheritance stays blocked; Coldcard is an unverified candidate. Public imports and compiler candidates do not prove physical compatibility or genuine Server Key enrollment. The future first user trial remains normal Keeper Testnet mode only, after reviewed integration. Timing/contact recovery decisions and actual inheritance maturity/exit validation remain open.

No SigningServer, Relay, new Server Key/backend implementation, deployment, production backup access, mainnet enablement, merge or release. Adam's contribution and owner approval remain prerequisites for feature-related server work.

Cloud checks

Check Actual result
Offline Jest, excluding existing live-Electrum suites PASS: 32 suites / 350 tests
Focused Mobile Key + diagnostic UI / policy-import-signing / backup fixtures PASS: 50 / 66 / 49 cases, included in offline total
Actual production Kotlin core PASS: 21 cases, including record-byte tampering, corruption, interruption, readback mismatch, thread/process concurrency
Android bridge typecheck PASS against real API 36 / React Native 0.83.9 classes; only generated BuildConfig is a fixture
Full Jest FAIL: 3 suites / 40 tests; 32 suites / 363 tests passed. Existing client/wallet/vault live-Electrum connection failures; --forceExit required for retained network handles
Repository ESLint FAIL: 4,554 errors / 919 warnings. Touched-source comparison against fed6c935: zero added diagnostics
Repository TypeScript FAIL: 1,010 diagnostics, identical normalized set to fed6c935; none in edited Preview files
Changed TS/TSX Prettier, shell syntax, workflow YAML, git diff --check PASS

The existing frozen dependency install fails on manifest/lock mismatch. Cloud used yarn install --pure-lockfile --ignore-scripts; no package/lockfile changes were made. Hosted verification is recorded below; repository Lint uses continue-on-error and its status alone is not a lint pass.

Hosted CI for the current PR head

Repository CI 38212962553 raw Tests log reports 35 suites / 403 tests passed. Recoverable Preview checks 38212962662 raw logs report 32 offline suites / 350 tests, 21 actual native-core cases, and the Android bridge typecheck passed. CodeQL 38212962611 passed.

These PR-triggered jobs checked out GitHub merge commit da5a4370de3cec44576be9b449a4bb28a746a36f, combining feature head 8c0656d2f41af4e49992b103c687278647d2ef7b with sprint 53f0ddd01e594c63e3c8d38824a6c2fc2e05c101. They are hosted integration evidence, separate from Cloud's disclosed live-Electrum failures. The raw hosted Lint log still reports 4,554 errors / 919 warnings and exit 1, tolerated by the existing workflow. The keeper/local-validation status remains failing as expected for NEEDS_LOCAL.

Reproducible Cloud commands:

node_modules/.bin/jest --runInBand --coverage=false --testPathIgnorePatterns /node_modules/ 'tests/services/(client|wallet|vault)\.test\.ts
No current-head APK/IPA build, emulator/simulator launch or physical device/hardware test was performed here. Java/Linux native core tests and a bridge typecheck do not execute Android Keystore/AtomicFile or iOS Security. Historical Android emulator evidence at `86f4be0265` does not validate this checkpoint.

Seed bytes still cross the native-to-JavaScript bridge; immutable strings and BIP32 copies cannot be reliably erased. No non-exportable/hardware-backed Mobile Key claim or independent security review is made. Dedicated Preview cloud credentials/containers, credential/policy persistence and rollback protection, replacement-phone native restoration, hardware possession/full-policy checks, authentic Server Key, real testnet receive/send, contact crypto, inheritance maturity and external exit remain unavailable or unverified.

## Codex local handoff

```text
State: NEEDS_LOCAL
PR: #7041
Base: sprint
Head branch: feature/recoverable-wallet-preview
Head commit: 8c0656d2f41af4e49992b103c687278647d2ef7b
Goal and acceptance criteria: validate exact-head Preview isolation and Mobile Key create/read/restart/corruption/interruption/reinstall behavior without silent replacement; all setup, cloud, recovery and wallet-readiness claims remain simulated or blocked.
Changes made: native read-existing/core extraction/bounded record reads, public identity and policy/import hardening, cryptographic synthetic signing tests, isolated encrypted recovery fixtures, scoped CI and corrected evidence documentation.
Cloud checks: actual commands/outcomes are above and reproducible in tests/native/preview-mobile-key/README.md; 350 offline Jest cases and 21 native core cases pass; full Jest/lint/typecheck fail as disclosed.
Required local checks: IOS, ANDROID, HARDWARE
Local checks requested: build both exact-head Preview apps; inspect signed IDs/entitlements/no-backup/no-cloud/deep links; co-install beside normal Keeper; test guarded read-existing before creation, create/read/restart/background/lock, Android alias/record/artifact corruption and valid AtomicFile backup recovery, iOS missing/corrupt/duplicate Keychain access, reinstall identity against an independently recorded policy, production uninstall safety, small screens/larger fonts, and physical TAPSIGNER/Satochip/Jade/Coldcard transport/policy capabilities. Use disposable Preview data only, no real funds or production recovery material.
Risks / known gaps: native platform execution/builds and physical signer proof pending; seed-export/security-review limits; cloud/native restore and independently held credential/policy persistence absent; Server Key/backend held for Adam and approval; no spendable wallet, broadcast, contact recovery or validated inheritance/exit.

node_modules/.bin/jest --runInBand --coverage=false --forceExit
bash tests/native/preview-mobile-key/run.sh --android-bridge-typecheck
npm run lint
node_modules/.bin/tsc --noEmit --pretty false

Native and recovery blockers

No current-head APK/IPA build, emulator/simulator launch or physical device/hardware test was performed here. Java/Linux native core tests and a bridge typecheck do not execute Android Keystore/AtomicFile or iOS Security. Historical Android emulator evidence at 86f4be0265 does not validate this checkpoint.

Seed bytes still cross the native-to-JavaScript bridge; immutable strings and BIP32 copies cannot be reliably erased. No non-exportable/hardware-backed Mobile Key claim or independent security review is made. Dedicated Preview cloud credentials/containers, credential/policy persistence and rollback protection, replacement-phone native restoration, hardware possession/full-policy checks, authentic Server Key, real testnet receive/send, contact crypto, inheritance maturity and external exit remain unavailable or unverified.

Codex local handoff

State: NEEDS_LOCAL
PR: #7041
Base: sprint
Head branch: feature/recoverable-wallet-preview
Head commit: 8c0656d
Goal and acceptance criteria: validate exact-head Preview isolation and Mobile Key create/read/restart/corruption/interruption/reinstall behavior without silent replacement; all setup, cloud, recovery and wallet-readiness claims remain simulated or blocked.
Changes made: native read-existing/core extraction/bounded record reads, public identity and policy/import hardening, cryptographic synthetic signing tests, isolated encrypted recovery fixtures, scoped CI and corrected evidence documentation.
Cloud checks: actual commands/outcomes are in the table above and reproducible in tests/native/preview-mobile-key/README.md; 350 offline Jest cases and 21 native core cases pass; full Jest/lint/typecheck fail as disclosed.
Required local checks: IOS, ANDROID, HARDWARE
Local checks requested: build both exact-head Preview apps; inspect signed IDs/entitlements/no-backup/no-cloud/deep links; co-install beside normal Keeper; test guarded read-existing before creation, create/read/restart/background/lock, Android alias/record/artifact corruption and valid AtomicFile backup recovery, iOS missing/corrupt/duplicate Keychain access, reinstall identity against an independently recorded policy, production uninstall safety, small screens/larger fonts, and physical TAPSIGNER/Satochip/Jade/Coldcard transport/policy capabilities. Use disposable Preview data only, no real funds or production recovery material.
Risks / known gaps: native platform execution/builds and physical signer proof pending; seed-export/security-review limits; cloud/native restore and independently held credential/policy persistence absent; Server Key/backend held for Adam and approval; no spendable wallet, broadcast, contact recovery or validated inheritance/exit.

antuz123 and others added 24 commits October 9, 2026 15:32

Copy link
Copy Markdown
Collaborator Author

Codex Cloud continuation handoff

Workstream and goal. Assisted Multisig (internal Recoverable Wallet) client preview in KeeperCommunity/bitcoin-keeper. Continue a separately installable, testnet-only, production-safe preview toward a real 2-of-3 Mobile + chosen Hardware + Server wallet with optional inheritance. This is parallel to R01–R10 and is not a release commitment.

Git baseline (12 October 2026). Draft PR #7041 targets sprint from feature/recoverable-wallet-preview; exact remote/head commit: fed6c93554e9e0941b4c31c8ded55d87577c4d48. Latest checked sprint: 6c4e1db2c8f621cf1a0ace378d115f8c4f513602 (the new AGENTS.md Cloud-to-Local contract). This PR is 30 commits ahead and one behind sprint. The separate local worktree /Users/devaccount/Workspace/keeper-recoverable-wallet-preview was clean with no staged, unstaged, non-ignored untracked, or unpushed work. It fast-forwarded from 2999a75c1ccfc6ff1436f29d75227ab67c62e8d6 to this exact remote head, preserving all 18 newer remote commits without conflict. Ignored Gradle/build, coverage, and dependency outputs were excluded. No new code commit was needed for this handoff.

Implemented. A distinct Android recoverablePreview flavor and iOS preview scheme use separate app IDs and device storage; preview configuration has unreachable local service endpoints, Android CloudBackup disabled, and no preview iCloud entitlement. The preview opens an empty Wallets screen with Single-Key Wallet, Assisted Multisig, Custom Wallet, and Import; Add Wallet reaches the same chooser. Assisted Multisig has labeled simulated Mobile/Server progress, hardware choice, failure/retry, cancel/resume, optional inheritance, final whole-policy review, and Recovery Options/contact walkthroughs. A separate preview-only native Mobile Key store, public Coldcard/Jade BIP48 import validator, policy-draft validator, optional Recovery-Key/BIP85 allocation helper, and public-only, explicitly unfundable testnet wsh(sortedmulti(2,...)) script/descriptor vectors with synthetic-UTXO PSBT signer-pair tests are committed. The latest head adds an opt-in Test Mobile Key diagnostic: it can generate a real device-only testnet key and compare two immediate public identity reads, while displaying that backup, wallet readiness, and recovery are unverified.

Partial / blocked / known issues. The normal Assisted Multisig setup is still a simulation: it creates no spendable wallet, authentic Server Key, backup, transaction, or hardware session. The new opt-in diagnostic does not prove restart/reinstall continuity and can leave an unbacked-up testnet key; it must never turn the simulated 'ready' status into a real one. Native seed material currently crosses the native-to-JavaScript bridge for public derivation and needs security review. Hardware import is public-only and not wired to a device; Coldcard inheritance is only an unverified candidate, while TAPSIGNER/Satochip/Jade inheritance remains blocked pending full-policy verification. The 2-of-3 vector is for tests only: no deposit address, real UTXO, broadcast, or external-wallet exit. iOS has not been built, and real cloud backup/readback, exact-key restore, Recovery Contact crypto, inheritance maturity spend, and independent recovery are absent. Shared normal-app entry, chooser, Home, navigation, and saga files changed behind preview guards, so normal-app regressions still require review. The older PR body/README are stale where they say the native store is wholly uncalled, cite only 108 focused tests or pending CI, or imply shared production source files were untouched. One older CodeQL review thread on policyDraft.ts line 199 remains unresolved.

Tests and evidence. At the exact fed6c93554e9e0941b4c31c8ded55d87577c4d48 head, CI run 38199878140 raw Tests log reports 34/34 suites and 304/304 tests passed; CodeQL run 38199878128 completed successfully. CI metadata also marks Lint successful, but the raw Lint step reports 4,554 errors, 919 warnings, exit code 1; .github/workflows/test.yml uses continue-on-error: true. Treat repository-wide lint as failing, not as a pass; determine whether any diagnostics are new in this PR. git diff --check is clean at this head. At the older 86f4be0265f37a9ee7ebc2f9c5f6a2ec97ada1d6 checkpoint, 108 focused Jest tests in 14 suites passed; an embedded-JS arm64 Android debug APK built, installed beside production Keeper v2.6.3 on an emulator, and a 320dp/1.6× text walkthrough exercised the simulated flow. No native APK/iOS build or device test is recorded for the current head. An older local full Jest run had 29 passing suites and 3 network-dependent wallet/Electrum failures when the configured node was unreachable; current-head CI tests passed.

Codex Local/native checks still needed after the next Cloud checkpoint. Build the exact PR head on iOS and Android; inspect signed app ID/entitlements and verify production/Preview co-installation, app-data/Keychain separation, no production deep links/cloud access, and uninstall safety on physical devices. Exercise the opt-in native key create/load/restart/corruption/interrupted-write/reinstall behavior and verify public identity against the eventual policy; do not use real funds or production recovery material. Recheck small screens and larger fonts, and test actual TAPSIGNER, Satochip, Jade, and Coldcard transports/capabilities before claiming support. Real testnet signing, cloud restore, inheritance maturity, and independent exit remain later dedicated validations.

Dependencies and decisions to preserve. sprint now has the Cloud-to-Local AGENTS.md contract; bring it forward carefully rather than blindly rebasing. Separate R4 / 2.6.4 candidate #7045 is a draft at d59d620c542a6d9e13cdbc31c9f5f5a038cf065c, with 11 overlapping paths (Android/iOS packaging, navigation, Home, package.json, BHR saga); keep R4 review/validation and this feature separate. Adam's SigningServer #4 is still draft, reference-only, with no functional Keeper server implementation or reply yet to the focused follow-up request. The owner has explicitly frozen feature-related SigningServer, Relay, production infrastructure, and server recovery changes pending Adam and a separate decision. Public chooser term is Assisted Multisig; default Mobile Key is independently generated, with Recovery Key derivation optional and absent from chooser copy. Hardware is chosen last; optional Inheritance Key precedes one final policy review. Base policy is 2-of-3, and any heir path must be encoded in wallet Miniscript and allow an Inheritance Key plus an accessible original signer without requiring Keeper's server. Fixed/renewed inheritance timing and the exact second signer remain product questions; do not claim a resolved or fundable inheritance path. The first eventual user-facing trial belongs only in normal Keeper Testnet mode after reviewed isolation; the separate Preview remains an engineering build.

Next Codex Cloud tasks, in priority order.

  1. Recheck the live PR head, latest sprint and R4: 2.6.4 mobile integration and release-readiness candidate #7045 overlap, then update stale PR/README status against the exact head. Investigate the tolerated ESLint failure and old CodeQL review comment without folding in R4 work.
  2. Strengthen the preview Mobile Key lifecycle and safety boundary with focused tests for create/load/public-identity consistency, interruption/corruption, restart/reinstall expectations, and no 'ready' state without verified persistence and recovery. Keep the diagnostic opt-in and clearly unbacked-up.
  3. Implement isolated client-side encrypted Mobile Key backup and authenticated readback/restore foundations using preview-only credentials/containers or fail-closed mocks until dedicated iCloud/Drive identities exist. Prove same-key/policy identity before any wallet activation; never reuse production backup containers.
  4. Connect public hardware import/possession checks to supported preview transports, and maintain honest policy-capability gates. Prepare real device scenarios for Codex Local; do not infer policy verification from a public xpub.
  5. Build and test the testnet-only wallet-activation/signing gates around genuine, independently verified signer identities. Keep addresses unfundable and the walkthrough simulated until an authentic Server Key, complete backup, hardware proof, and end-to-end 2-of-3 path are available; then prepare a disposable testnet receive/send checkpoint. Leave inheritance and independent contact recovery behind their separate compatibility/security gates.
  6. At the next meaningful installable checkpoint, add the exact-head Codex local handoff required by sprint/AGENTS.md, with actual Cloud checks and targeted Mac/device tests.

Restrictions. No SigningServer or Relay edits, backend deployment, production signing or wallet access, mainnet enablement, PR merge, release-branch merge, store submission, or release publication in this stream without the owner's explicit approval. Keep #7041 draft and R4/R5–R10 independent. This comment is the durable baseline; it supersedes stale verification statements in the older PR body but does not claim native or security validation.

@antuz123 antuz123 changed the title Add isolated Recoverable Wallet client preview Add isolated Assisted Multisig preview and verification foundations Oct 12, 2026

Copy link
Copy Markdown
Collaborator Author

Codex local handoff

State: NEEDS_LOCAL
PR: #7041
Base: sprint
Head branch: feature/recoverable-wallet-preview
Head commit: 8c0656d2f41af4e49992b103c687278647d2ef7b
Goal and acceptance criteria: independently validate Preview app isolation and native Mobile Key create/read/restart/corruption/interruption/reinstall without silent replacement; all wallet setup and recovery stay simulated or blocked until real proofs exist.
Changes made: guarded read-existing APIs on both platforms; actual Android core extraction, bounded authenticated record reads and lifecycle tests; stricter public identity/policy/hardware import; cryptographic synthetic signing checks; disconnected authenticated encrypted backup/readback fixtures; scoped preview CI and corrected documentation. No Server Key/backend, mainnet, R4 or Reproducibility work.
Cloud checks: offline Jest PASS 32 suites/350 tests; focused Mobile/UI 50, policy/import/signing 66, backup 49 cases PASS (included in offline count); native harness PASS 21 cases + real API36/RN0.83.9 bridge typecheck. Full Jest FAIL 3 existing live-Electrum suites/40 cases with 32 suites/363 passing. npm run lint FAIL 4554 errors/919 warnings, zero added touched-source diagnostics vs fed6c935; tsc --noEmit FAIL 1010 existing diagnostics identical to baseline, none in edited preview files. Changed TS/TSX formatting, workflow YAML, shell syntax and diff whitespace PASS.
Required local checks: IOS, ANDROID, HARDWARE
Local checks requested: build exact-head Android/iOS Preview; inspect package IDs/entitlements/no-backup/no-cloud/deep links; co-install beside production Keeper. Read-existing before creation must fail without a new record/alias. Create/read/restart/parallel/background/locked-device checks must preserve full independently recorded public identity. Test Android corrupted/truncated/oversized record, missing alias/record, interrupted writes and .new/.bak artifacts; valid AtomicFile backup recovery must keep the original key. Test iOS locked/unlocked, missing/corrupt/wrong-length Keychain and duplicate creation. Reinstall semantics differ (Android app/Keystore deletion vs possibly retained iOS Keychain); never call a new or retained key a recovered wallet without authenticated restore proof. Check uninstall safety, 320dp/larger fonts and actual TAPSIGNER/Satochip/Jade/Coldcard transport/whole-policy capability. Use disposable Preview data only, no real funds or production recovery material.
Risks / known gaps: no current APK/IPA or device/platform-service runtime test here; seeds still cross native/JS with immutable-copy limits; no independent security review, dedicated Preview cloud identities, durable recovery-secret/policy custody or rollback protection, native restore, hardware proof, genuine Server Key, spendable wallet, real broadcast, contact recovery or validated inheritance/exit. Server work awaits Adam and owner approval. Do not merge or release.

Commands and evidence are in the updated PR description and native harness README, plus native device checklist.

Hosted Tests: 35/35 suites, 403/403 cases passed. Preview checks: 350 offline cases + 21 core cases + bridge typecheck passed. CodeQL: passed. Raw hosted lint still fails (tolerated), not a lint pass. These jobs checked PR merge commit da5a4370de3cec44576be9b449a4bb28a746a36f containing the above feature head and sprint 53f0ddd01e594c63e3c8d38824a6c2fc2e05c101. Physical/native acceptance and the local-validation gate remain open.

This supersedes stale native/verification claims in the earlier continuation handoff. The setup/recovery UI remains simulated; the opt-in Mobile Key diagnostic is real but unbacked-up; signing and encrypted recovery results are offline fixtures.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants