From ef0d4d89e1879cfdb072008816bb85fb7cdf1e61 Mon Sep 17 00:00:00 2001 From: Anant Date: Wed, 7 Oct 2026 02:05:22 +0530 Subject: [PATCH 01/15] Package public backend contributor setup for sprint (cherry picked from commit f225c1978c254830350068f8a08b659ecdd80fa6) --- .github/pull_request_template.md | 29 ++ .github/workflows/public-backend.yml | 59 ++++ CONTRIBUTING.md | 113 ++++++++ Readme.md | 10 + dev/local-backend/.env.example | 5 + dev/local-backend/.gitignore | 3 + dev/local-backend/ACCESS.md | 24 ++ dev/local-backend/CI.md | 54 ++++ dev/local-backend/HANDOFF.md | 61 ++++ dev/local-backend/README.md | 173 +++++++++++ dev/local-backend/VERIFICATION.md | 273 ++++++++++++++++++ .../adapters/signing/files/.dockerignore | 9 + .../adapters/signing/files/Dockerfile.local | 11 + .../signing/files/scripts/local-entry.cjs | 14 + .../adapters/signing/files/src/config.ts | 100 +++++++ .../adapters/signing/local.patch | 132 +++++++++ dev/local-backend/app.env.local.example | 10 + dev/local-backend/compose.yaml | 98 +++++++ dev/local-backend/dev | 3 + dev/local-backend/keeper.py | 181 ++++++++++++ dev/local-backend/nginx.conf | 22 ++ dev/local-backend/sources.lock.json | 18 ++ dev/local-backend/test_keeper.py | 92 ++++++ dev/local-backend/verify-local.sh | 3 + dev/local-backend/verify.py | 151 ++++++++++ setup.sh | 13 +- 26 files changed, 1653 insertions(+), 8 deletions(-) create mode 100644 .github/pull_request_template.md create mode 100644 .github/workflows/public-backend.yml create mode 100644 CONTRIBUTING.md create mode 100644 dev/local-backend/.env.example create mode 100644 dev/local-backend/.gitignore create mode 100644 dev/local-backend/ACCESS.md create mode 100644 dev/local-backend/CI.md create mode 100644 dev/local-backend/HANDOFF.md create mode 100644 dev/local-backend/README.md create mode 100644 dev/local-backend/VERIFICATION.md create mode 100644 dev/local-backend/adapters/signing/files/.dockerignore create mode 100644 dev/local-backend/adapters/signing/files/Dockerfile.local create mode 100644 dev/local-backend/adapters/signing/files/scripts/local-entry.cjs create mode 100644 dev/local-backend/adapters/signing/files/src/config.ts create mode 100644 dev/local-backend/adapters/signing/local.patch create mode 100644 dev/local-backend/app.env.local.example create mode 100644 dev/local-backend/compose.yaml create mode 100755 dev/local-backend/dev create mode 100644 dev/local-backend/keeper.py create mode 100644 dev/local-backend/nginx.conf create mode 100644 dev/local-backend/sources.lock.json create mode 100644 dev/local-backend/test_keeper.py create mode 100755 dev/local-backend/verify-local.sh create mode 100644 dev/local-backend/verify.py diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000000..45f51ccc3d --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,29 @@ +## Problem and change + + + +Issue: +OpenSpec change / archived proposal: +Target branch: + +## Test results + + + +| Check / scenario | Platform | Passed / failed / blocked / not run | Evidence or reason | +| --- | --- | --- | --- | +| | | | | + +## Review considerations + + + +- [ ] The diff excludes local secrets, wallet data and generated build/dependency files. +- [ ] Test failures and untested behavior are recorded above. +- [ ] The issue/spec and implementation describe the same scope. + +Keeper maintainers own security review, acceptance, merging and official releases. +Passing checks does not constitute approval. diff --git a/.github/workflows/public-backend.yml b/.github/workflows/public-backend.yml new file mode 100644 index 0000000000..9212bdce78 --- /dev/null +++ b/.github/workflows/public-backend.yml @@ -0,0 +1,59 @@ +name: Public backend setup + +on: + push: + branches: [sprint, main] + paths: + - 'dev/local-backend/**' + - '.github/workflows/public-backend.yml' + pull_request: + branches: [sprint, main] + paths: + - 'dev/local-backend/**' + - '.github/workflows/public-backend.yml' + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: public-backend-${{ github.event.pull_request.number || github.ref }} + cancel-in-progress: true + +jobs: + signing: + name: Public SigningServer adapter + runs-on: ubuntu-latest + timeout-minutes: 20 + steps: + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + with: + persist-credentials: false + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 + with: + node-version: '22' + - run: ./dev/local-backend/dev prepare-signing + - run: npm ci --ignore-scripts + working-directory: dev/local-backend/.sources/signing + - run: npm run compile + working-directory: dev/local-backend/.sources/signing + - run: npm test + working-directory: dev/local-backend/.sources/signing + + backend: + name: Local backend and bootstrap + runs-on: ubuntu-latest + timeout-minutes: 25 + steps: + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + with: + persist-credentials: false + - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5 + with: + python-version: '3.9' + - run: python3 -B -m unittest discover -s dev/local-backend -p 'test_*.py' + - run: ./dev/local-backend/dev up + - run: ./dev/local-backend/verify-local.sh --persistence --boundaries + - name: Stop containers and retain volumes + if: always() + run: ./dev/local-backend/dev stop diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..569fc61460 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,113 @@ +# Contributing to Bitcoin Keeper + +Contributions are welcome through forks and pull requests. Keeper +maintainers are responsible for code and security review, assessing privacy risks, +deciding whether to accept changes, and controlling merges and public releases. +Passing automated checks or submitting a working build does not constitute approval. + +## Set up a local workspace + +Fork this repository on GitHub and clone your fork for contributions. You do not +need write access to the Keeper repository or production credentials. Follow the +[local development guide](dev/local-backend/README.md) for tool versions, Docker +backend setup, Android Studio/Xcode builds and troubleshooting. Docker runs the +backend; native SDKs and the mobile app run on your host. + +The [SigningServer source](https://github.com/KeeperCommunity/SigningServer) is +public and can be cloned, installed, built, tested and contributed to on its own. +The full Docker app/backend setup uses the public +[Relay](https://github.com/KeeperCommunity/Relay) and SigningServer sources; +it requires no repository invitation. Optional private development resources +follow a separate [access process](dev/local-backend/ACCESS.md). Access approval +is separate from acceptance of contributed code. + +The guide's [capability table](dev/local-backend/README.md#what-works-locally) lists +supported local flows and unavailable integrations. The +[verification record](dev/local-backend/VERIFICATION.md) distinguishes tested +behavior from failures and untested platforms. Start with disposable testnet +wallets. Store accounts, release signing keys and production backend access are +not prerequisites for contributing. + +## Develop a focused change + +1. Find an existing issue or describe the problem in a new issue. For a suspected + vulnerability, use the private process in [SECURITY.md](SECURITY.md) instead. +2. Create a branch in your fork. Use the base branch associated with the issue; + if none is specified, use the repository's default development branch, + `sprint`. Do not assume a release tag includes every unreleased feature. +3. Capture the change's scope and acceptance criteria using the repository's + OpenSpec workflow. The CLI is included in the locked development dependencies: + + ```sh + yarn openspec new change your-change-name + yarn openspec status --change your-change-name + yarn openspec instructions proposal --change your-change-name + ``` + + Follow the artifact instructions for proposal, specs, design and tasks. Read + [OpenSpec configuration](openspec/config.yaml); for UI changes, also read + [DESIGN.md](DESIGN.md). The repository's + [change-engineer workflow](.github/agents/change-engineer.agent.md) describes + planning, implementation and archiving. Respect any explicit repository-owner + restrictions on committing, pushing or publishing when using coding agents. +4. Implement the agreed scope, reuse existing components and keep unrelated + formatting, dependency upgrades, feature reconciliation and version bumps out + of the change. Maintainers coordinate version numbers and the + [Android](android/fastlane/README.md) and [iOS](ios/fastlane/README.md) release + workflows separately from local development. + +For backend development, bootstrap creates ignored checkouts under +`dev/local-backend/.sources/`. Save backend work in a branch/patch and submit it to +the appropriate backend repository; an app PR does not include those ignored +edits. Changes to packaged adapters must update the corresponding SHA-256 entries +in `sources.lock.json` and be verified from freshly prepared sources. Do not +package a generated checkout, database or signing volume in a PR. + +## Test and report the result + +Run checks relevant to the changed behavior. These commands run from the app root: + +| Change | Checks | +| --- | --- | +| App logic | `yarn test --runInBand` (or the relevant Jest test paths) and `yarn lint` | +| User flow or native code | Build the affected development app and exercise the acceptance scenarios; use/update relevant Maestro flows under `flows/` | +| Local backend/bootstrap | `python3 -B -m unittest discover -s dev/local-backend -p 'test_*.py'` and `./dev/local-backend/dev verify` | +| Persistence or isolation | `./dev/local-backend/verify-local.sh --persistence --boundaries` on a disposable, otherwise idle Compose project | +| OpenSpec | `yarn openspec validate your-change-name --strict` | + +Shared mobile changes should be checked on both Android and iOS. If a platform, +hardware device or integration is unavailable, say so; maintainers decide what +additional testing is required before acceptance. A local backend smoke test does +not validate recovery, transaction signing or every mobile feature. + +Report the commands, commit, platform/device, actual results and relevant redacted +evidence. Keep **passed**, **failed/blocked** and **not run** separate. Describe +existing failures rather than hiding them or reporting an unexecuted check as a +pass. Screenshots can support manual verification but do not turn a failed +automated assertion into a passing automated test. + +## Submit and review + +Open a pull request from your fork and complete the supplied template. Link the +issue and OpenSpec artifacts, explain the behavior change and provide the test +results. Review the diff before submission: exclude local environment files, +generated dependencies, databases, keys, wallet backups and signing credentials. +Use [SECURITY.md](SECURITY.md) for private vulnerability details. + +Keeper maintainers review correctness, product fit, security/privacy, dependencies +and test evidence. They may request revisions or additional tests, and decide +whether a change is accepted. Only authorized maintainers merge and release +official builds. Contributors do not need release permissions to participate. + +Some existing CI checks use maintainer-managed services or secrets. If a check is +unavailable on a fork PR, report it in the PR so maintainers can arrange review; +do not request production secrets or treat an unavailable check as passing. +This document defines review responsibilities; it does not claim that GitHub +branch protection or approval rules have been configured or verified. + +GitHub runs app tests and separate public backend/bootstrap checks. The existing Electrum/wallet integration +tests use public testnet nodes and fee services; an internet connection is needed. +Coverage, where generated, measures the configured Electrum/wallet source +directories, not every app screen. SonarCloud analysis on the development branch +is deferred; passing tests are not a security analysis pass. See [CI notes](dev/local-backend/CI.md) +for the branch-specific checks, deferred analysis work and evidence limits. diff --git a/Readme.md b/Readme.md index 3f1f9d298a..70ed94e5c0 100644 --- a/Readme.md +++ b/Readme.md @@ -60,6 +60,16 @@ Refer to platform-specific documentation for detailed setup requirements. yarn install ``` +## Contributing and local backends + +See [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution process and +[the local development guide](dev/local-backend/README.md) for a reproducible +backend setup using public [Relay](https://github.com/KeeperCommunity/Relay) +and [SigningServer](https://github.com/KeeperCommunity/SigningServer) sources. +The local stack uses disposable testnet fixtures and needs no production +credentials. Keep native app builds on your host; the backend runs in Docker. +Report suspected vulnerabilities through [private reporting](SECURITY.md). + ## Build and Run ### Varients diff --git a/dev/local-backend/.env.example b/dev/local-backend/.env.example new file mode 100644 index 0000000000..ed62df3b1f --- /dev/null +++ b/dev/local-backend/.env.example @@ -0,0 +1,5 @@ +# Copy to .env only when changing the defaults. No secrets required. +COMPOSE_PROJECT_NAME=keeper-contributor +KEEPER_RELAY_PORT=3000 +KEEPER_CHANNEL_PORT=4002 +KEEPER_SIGNING_PORT=3003 diff --git a/dev/local-backend/.gitignore b/dev/local-backend/.gitignore new file mode 100644 index 0000000000..53a25a248d --- /dev/null +++ b/dev/local-backend/.gitignore @@ -0,0 +1,3 @@ +.sources/ +.env +__pycache__/ diff --git a/dev/local-backend/ACCESS.md b/dev/local-backend/ACCESS.md new file mode 100644 index 0000000000..d9012a6548 --- /dev/null +++ b/dev/local-backend/ACCESS.md @@ -0,0 +1,24 @@ +# Optional private development resources + +The public [app](https://github.com/KeeperCommunity/bitcoin-keeper), +[Relay](https://github.com/KeeperCommunity/Relay), and +[SigningServer](https://github.com/KeeperCommunity/SigningServer) can be cloned, +built, tested and contributed to without a Keeper invitation. The local Docker +setup in [README.md](README.md) uses only those public repositories and +disposable development identities. Production credentials are never needed. + +Some assigned work may need separate private repositories, provider dashboards, +or test infrastructure. Ask the Keeper maintainer coordinating that work in your +existing private conversation. Include your GitHub username, task and the exact +resource needed. Do not post credentials or private access requests in a public +issue. If you do not have a maintainer contact, use the +[community contact](../../Readme.md#community) to reach one privately. + +Maintainers review the work and grant only the needed permissions after checking +that the resource is ready to share. Approval covers the development access, not +every local command or proposed code change. Record invitation acceptance and +setup success in the internal development backlog. A contributor must use their +own GitHub identity; maintainers must not share personal tokens. + +Security reports follow [SECURITY.md](../../SECURITY.md). Code acceptance, +merges, production access and releases remain separate maintainer decisions. diff --git a/dev/local-backend/CI.md b/dev/local-backend/CI.md new file mode 100644 index 0000000000..66064cccd7 --- /dev/null +++ b/dev/local-backend/CI.md @@ -0,0 +1,54 @@ +# Contributor checks and analysis + +## Public backend CI + +The app's local backend workflow pins the public +[Relay](https://github.com/KeeperCommunity/Relay) and +[SigningServer](https://github.com/KeeperCommunity/SigningServer). It requires no +private repository token or production credential. The default branch runs +`Public backend setup` for the packaged adapter, bootstrap and disposable API +checks. Earlier Linux backend runs failed while fetching the private Relay; +those historical runs do not establish the result for this public pin. +Code acceptance and releases remain maintainer decisions. + +## Active checks + +The default branch's existing `Run Tests` workflow runs app tests. The new +`Public backend setup` workflow runs a separate public SigningServer adapter +fetch/install/compile/test job and full local backend bootstrap, API, +persistence and network-boundary checks. Neither job uses hosted credentials. +Pull requests are checked against their proposed merge with the target branch. +The development branch's `Contributor checks` workflow additionally publishes +app test coverage; its results are tracked with PR #7014. + +Where generated, Jest's LCOV measures only the +Electrum/wallet directories listed in `jest.config.js`; this is not whole-app +coverage. Test success is evidence about the exercised cases, not a security +clearance. Maintainers retain security review and acceptance responsibility. + +## SonarCloud deferred on 26 September 2026 + +The project owner chose to defer SonarCloud on the development branch. That job +was removed from its active workflow; app tests and an LCOV artifact remain there. `sonar-project.properties` is +retained for future restoration, including the report path and quality-gate wait +setting. No analysis or quality-gate pass is claimed, and no threshold has been +lowered. GitHub protection settings were not changed; if a required Sonar status +blocks merging, a maintainer must reconcile that setting with this decision. + +Before deferral, PR #7014's original and updated scanners failed while retrieving +the pull request, before analysis. Public project metadata lists the repository +as `bithyve/bitcoin-keeper`, while this PR lives in +`KeeperCommunity/bitcoin-keeper`. This suggests a stale binding; an administrator +needs to verify the exact access/configuration problem when analysis is restored. + +Deferred follow-up: inspect the project's Repository binding and GitHub app +access, confirm project/organization keys and the secret, restore a pinned scanner +that consumes LCOV and waits for its quality gate, then review the actual result. +Keep analyzer credentials away from fork code. See Sonar's +[repository binding instructions](https://docs.sonarsource.com/sonarqube-cloud/managing-your-projects/administering-your-projects/changing-binding). + +The last existing `sprint` analysis (17 September, commit `1adf4f663`) reported a +failed quality gate: 0% new-code coverage, reliability rating C, 5.1% duplication +and 0% reviewed security hotspots, using a September 2024 previous-version +baseline. These are historical findings, not this PR's analysis. Deferral does +not resolve them or replace Keeper's review. diff --git a/dev/local-backend/HANDOFF.md b/dev/local-backend/HANDOFF.md new file mode 100644 index 0000000000..8d2fe447e2 --- /dev/null +++ b/dev/local-backend/HANDOFF.md @@ -0,0 +1,61 @@ +# Independent contributor setup check + +Use this full-stack checklist with the public Relay and SigningServer sources. +SigningServer-only work can follow +[its independent setup](README.md#signingserver-without-relay-access). A maintainer's working Mac does not establish that the guide works +on another developer's machine. This check does not authorize code acceptance or +an official release. + +## Start clean + +1. Use an anonymous fresh app clone at the exact commit + supplied by the maintainer. Record `git rev-parse HEAD`. Do not copy another + developer's `.env`, databases, signing volume, account credentials or key files. +2. Follow [README.md](README.md) for the toolchain and a + running Docker engine. If other Keeper projects are running, choose a distinct + Compose project and three unused ports as documented there. +3. Run `./dev/local-backend/dev up`. It must prepare the pinned sources, start the + services and pass the local API checks without production credentials. +4. Run `./dev/local-backend/verify-local.sh --persistence --boundaries` while no + other test is using this project's services. It recreates this project's + containers while retaining its volumes. Both persistence and rejection of + mainnet/hosted database settings must pass. +5. Run `python3 -B -m unittest discover -s dev/local-backend -p 'test_*.py'`. +6. Follow the native development build instructions for the platforms available + on this machine. iOS requires a Mac and Xcode. Record unavailable platforms as + untested, not passed. +7. In the development app, create only a disposable local test fixture, complete + passcode/onboarding, reach Mobile Wallet and More Options, then relaunch and + unlock. Confirm that the app uses the local environment. Do not import a real + wallet or move real funds for this check. +8. Stop the selected stack with `./dev/local-backend/dev stop`. Retain the volumes + for follow-up unless you intentionally choose to discard this test fixture. + +## Send the result privately to the coordinating maintainer + +Copy this summary into the existing private conversation. Maintainers keep it in +the internal development backlog, not a new public administrative issue. + +```text +App commit: +Backend revisions (from dev/local-backend/sources.lock.json): +Host OS and architecture: +Docker/Compose, Node/Yarn, Python, Java and Xcode versions as applicable: +Fresh clone and new project/volumes: yes/no (explain reused state) + +PASS: +FAIL or BLOCKED (exact step and sanitized error): +NOT TESTED: +Guide corrections or undocumented steps needed: +Native platform(s), simulator/emulator and onboarding/relaunch result: +``` + +Do not attach recovery words, private keys, authentication tokens, receipts, +databases, captured emails or unreviewed full logs. Report security findings via +[SECURITY.md](../../SECURITY.md). Ordinary reproducible user-facing defects can +have public product issues after removing private details. + +Passing this checklist proves only the listed local setup and smoke checks. +Purchases, push delivery, scheduled inheritance, hardware wallets, transaction +signing and recovery correctness require their own acceptance evidence; see the +[capability table](README.md#what-works-locally) and [verification record](VERIFICATION.md). diff --git a/dev/local-backend/README.md b/dev/local-backend/README.md new file mode 100644 index 0000000000..0968bf0885 --- /dev/null +++ b/dev/local-backend/README.md @@ -0,0 +1,173 @@ +# Contributor development environment + +Run MongoDB, Keeper relay/channel and the testnet signing backend in Docker. Run Metro, Android Studio and Xcode on your host. Hosted development services have been retired; this setup needs no production backend or release credentials. + +For choosing a change, OpenSpec, test reporting and submitting a pull request, see +[Contributing](../../CONTRIBUTING.md). Keeper maintainers own security review, +acceptance, merges and official releases. + +## Prerequisites + +Both [Relay](https://github.com/KeeperCommunity/Relay) and +[SigningServer](https://github.com/KeeperCommunity/SigningServer) are public. +The full local Docker stack uses pinned revisions of these clean public sources +and needs no repository invitation or production credentials. Optional private +development resources have a separate [access process](ACCESS.md). + +- Git, Python 3.9+, Docker Engine with Compose v2.20+ (or a newer Compose release). On macOS use Docker Desktop or Colima; Linux can use Docker Engine. Start the engine before setup. Reserve about 3–4 GB for Docker and run native builds sequentially on a 16 GB Mac. +- Anonymous GitHub access to both public backends. First setup downloads sources, container images and dependencies. Subsequent starts can reuse them. +- Mobile: Node 20.19.4+ (Node 22 is a suitable supported baseline), Yarn Classic 1.22.22. Use the committed `yarn.lock`. +- Android: Android Studio, JDK 17, SDK platform 36, build tools 35.0.0, NDK 27.1.12297006, CMake 3.22.1 and platform tools. Set `JAVA_HOME` and `ANDROID_HOME`. These versions come from this app's Gradle files. +- iOS: macOS, Xcode with an iOS simulator runtime, Ruby 3.3.0 (`.ruby-version`) and Bundler. Use the root `Gemfile.lock` and `ios/Podfile.lock`. + +Earlier native validation on this Mac used Apple Silicon, Xcode 26.4, Node 25.9.0, Yarn 1.22.22, JDK 17 and Ruby 3.3.0. App tests also passed in GitHub Linux CI on Node 22. Full contributor setup on Intel Macs, Linux and Windows/WSL still needs independent verification; iOS builds require macOS. See [verification](VERIFICATION.md) for actual results and limitations. + +Native tool installation: [React Native 0.83 environment guide](https://reactnative.dev/docs/0.83/set-up-your-environment). Follow the repo-specific Android versions above when they differ from that guide. + +## First start + +Clone the public default branch: + +```sh +git clone https://github.com/KeeperCommunity/bitcoin-keeper.git +cd bitcoin-keeper +``` + +`dev up` fetches only public backend sources. + +From this app checkout's root: + +```sh +./dev/local-backend/dev doctor +./dev/local-backend/dev up +./dev/local-backend/dev env +yarn install --frozen-lockfile --non-interactive +``` + +`up` fetches the exact backend Git revisions, applies the local development adapters, builds containers, waits for readiness and runs real disposable API checks. `env` creates `.env.local` with restrictive permissions; it refuses to overwrite an existing different configuration. Existing `.env` and production files are not used or modified. + +## SigningServer without Relay access + +For SigningServer changes that do not need the mobile app or Relay, use the +[public repository's instructions](https://github.com/KeeperCommunity/SigningServer#install-and-verify): + +```sh +git clone https://github.com/KeeperCommunity/SigningServer.git +cd SigningServer +npm ci --ignore-scripts +npm run compile +npm test +``` + +Use Node 22 and report the exact tested commit. The server's unit tests use +disposable local fixtures; they do not establish full app/backend integration or +live signing behavior. To check this app's local adapter against its pinned +public source, run `./dev/local-backend/dev prepare-signing` from the app clone. +That command checks the adapter digests and applies it under ignored +`.sources/signing/` without fetching Relay or starting Docker. Submit upstream +SigningServer changes to its own repository. Full `dev up`, API checks and native +app setup use the public Relay source. + +The JavaScript install hook only installs the repo's Node compatibility shims. Native dependencies are separate explicit steps below. It no longer runs CocoaPods on Android-only machines or rewrites `android/local.properties` with a Mac-specific path. + +If default ports 3000/4002/3003 are occupied, copy `dev/local-backend/.env.example` to `dev/local-backend/.env`, set distinct ports and a unique project name, then run the commands above. Use the same settings for every invocation. Multiple copies using the same Compose project name share containers and volumes; give each independent environment a unique name. `.env.local` must match those ports. Commands work from any directory except the native/Yarn commands, which assume the app root. + +## Android + +Create and boot an emulator through Android Studio. Use an ARM64 image on Apple Silicon, x86_64 on Intel/Linux. Use `adb devices` to select its serial. In one terminal at the app root: + +```sh +yarn start +``` + +In another terminal: + +```sh +./dev/local-backend/dev android-forward --serial YOUR_SERIAL +ENVFILE=.env.local ./android/gradlew -p android app:assembleDevelopmentDebug -PreactNativeArchitectures=arm64-v8a --max-workers=2 +adb -s YOUR_SERIAL install -r android/app/build/outputs/apk/development/debug/app-development-debug.apk +adb -s YOUR_SERIAL shell am start -n io.hexawallet.keeper.development/io.hexawallet.keeper.MainActivityDefault +``` + +Use `-PreactNativeArchitectures=x86_64` for an x86_64 emulator. `ANDROID_HOME` lets Gradle locate the SDK without a machine-specific committed `local.properties`. Android debug signing uses the disposable debug keystore already in the repository. No release signing key is needed. + +Keep `localhost` in `.env.local`: the app's Android cleartext policy allows it. `android-forward` connects the selected device to Metro and the configured backend ports; rerun after restarting the device. A physical Android device can use the same USB forwarding, but physical-device validation is a separate step. + +## iOS + +Select Ruby 3.3.0 with your Ruby manager, then from the app root: + +```sh +bundle install +(cd ios && BUNDLE_GEMFILE="$PWD/../Gemfile" RCT_NEW_ARCH_ENABLED=1 bundle exec pod install) +xcrun simctl list devices available +``` + +Use the root Gemfile explicitly; the `ios` directory has a different Gemfile. CocoaPods may refresh checkout-path-dependent Hermes podspec checksums on initial installation; review any lockfile diff and do not treat dependency version changes as routine setup. + +Start `yarn start` in a separate terminal. You can inspect the workspace in Xcode (`ios/hexa_keeper.xcworkspace`, scheme `hexa_keeper_dev`). Use the command below for local builds so `ENVFILE` reaches every native build phase; simply clicking Run with the default scheme settings does not select `.env.local`: + +```sh +ENVFILE=.env.local xcodebuild -workspace ios/hexa_keeper.xcworkspace -scheme hexa_keeper_dev -configuration Debug -destination 'platform=iOS Simulator,id=YOUR_SIMULATOR_UDID' -derivedDataPath ios/build/local-dev build +xcrun simctl boot YOUR_SIMULATOR_UDID +xcrun simctl install YOUR_SIMULATOR_UDID ios/build/local-dev/Build/Products/Debug-iphonesimulator/hexa_keeper_dev.app +xcrun simctl launch YOUR_SIMULATOR_UDID io.hexawallet.hexakeeper.dev +``` + +Skip `simctl boot` if already booted. Keep simulator signing enabled so the app retains required entitlements. Store publishing/signing is separate from contributor development; see the release documentation. + +## Daily use and verification + +```sh +./dev/local-backend/dev status +./dev/local-backend/dev verify +./dev/local-backend/dev logs +./dev/local-backend/dev stop +``` + +`stop` removes containers but retains both named volumes. A later `up` restores the environment. To check persistence and configuration boundaries explicitly: + +```sh +./dev/local-backend/verify-local.sh --persistence --boundaries +``` + +This recreates only the selected Compose project's containers, retains its volumes, and compares the same app record and testnet signing public key. It also checks startup rejection of mainnet and hosted databases. Run when no other test is using that project. Ordinary `verify` does not restart containers. Every verify run adds a disposable app/signer fixture to the local database; no testnet coins are needed and no transaction is sent. Tokens and private keys are not printed. + +For native smoke testing: launch the development app, complete onboarding with a disposable wallet, unlock, open Wallets and More Options, and select testnet before testing network functionality. An API smoke pass does not prove wallet backup/recovery or a real signing transaction. + +## What works locally + +| Capability | Scope | +| --- | --- | +| Mongo, relay app records | Local persistence and API create/read checks | +| Channel | Socket.IO connection handshake | +| Server Key | V3 testnet setup, public-key derivation, valid/invalid 2FA and persistence | +| Email | Captured inside signing volume at `/local-data/outbox.jsonl`; never delivered | +| Push, purchases, Ask Keeper AI, faucet, price feeds | Unavailable; relay reports unsupported routes explicitly | +| Scheduled signing / inheritance jobs | Disabled; timer-dependent flows are not covered | +| Blockchain / Electrum | Separate mobile internet connection; not provided by this stack | +| Legacy V2 Server Key | Not supported by this acceptance check; a V2 setup probe terminated the pinned upstream process (see verification notes) | + +The relay health field `signing: false` describes the relay, not the separate signing service. Use each service's health endpoint. No production service deployment is performed. + +## Sources, data and network boundaries + +`sources.lock.json` pins both public backend revisions and the SigningServer adapter SHA-256 checksums. Relay's public source already includes local mode, so it needs no app-side adapter. The Node, Mongo and nginx base images are pinned by digest. Backend dependency installs use frozen Yarn / npm lockfiles; OS packages in the relay build still use Debian repositories, so this is a reproducible development workflow, not a bit-for-bit reproducible image build. + +`adapters/signing/` contains the local-mode modifications for the pinned public SigningServer source. `.sources/` is generated and ignored. Bootstrap never overwrites an existing checkout; reruns preserve local backend edits. After editing a backend, rerun `up` to rebuild. To change pins/adapters, save your backend edits and move the generated checkout aside first. Do not deploy the development adapter to production. + +Only the gateway publishes host ports, all on `127.0.0.1`. Mongo, relay and signing share an internal network with no external egress; the gateway also has a host-access network. Compose waits on service health, following [Docker's startup ordering](https://docs.docker.com/compose/how-tos/startup-order/). Build-time dependency downloads still use the internet. Mobile native integrations are outside Docker; this is not a fully offline mobile mode. + +Signing identities are randomly generated per signing volume and stored with restricted permissions. Use disposable test wallets. Keep the Mongo and signing volumes together: deleting signing keys invalidates their stored Server Key records. There is deliberately no automatic reset/delete command. `docker compose down --volumes` is destructive and not part of normal setup. Do not distribute databases, keys, email captures, `.env` files or native signing credentials with the source. + +## Troubleshooting + +- Docker unavailable: start Docker Desktop or Colima, then rerun `doctor`. +- Backend source fetch failure: check the public pinned revision and network connection; no application secret is needed. +- Stale source/adapter marker: save edits and move the relevant `.sources/relay` or `.sources/signing` directory aside. Bootstrap refuses to overwrite it. +- Health succeeds but a feature fails: consult the capability table; cloud integrations are not restored by local startup. +- App cannot reach local services: check `.env.local`, rebuild with `ENVFILE=.env.local`, and rerun Android port forwarding. Changing an env file requires a native rebuild. +- Xcode reports a missing Node executable: inspect the ignored `ios/.xcode.env.local`; CocoaPods may have cached a version-specific path removed by a Node upgrade. Update its `NODE_BINARY` to your current executable and rebuild. +- If several Metro servers are running, select the one for this checkout on each device. Android emulator defaults can bypass USB forwarding via `10.0.2.2`; set its debug server host to `localhost:8081` when using `adb reverse`. +- iOS pod install fails under system Ruby: select the repo's Ruby version and root Bundler environment. Do not run an unrelated globally installed CocoaPods. +- Memory pressure: build iOS and Android sequentially, limit Gradle workers, and shut down unused simulators without erasing their data. diff --git a/dev/local-backend/VERIFICATION.md b/dev/local-backend/VERIFICATION.md new file mode 100644 index 0000000000..1205569afc --- /dev/null +++ b/dev/local-backend/VERIFICATION.md @@ -0,0 +1,273 @@ +# Contributor setup verification + +## Sprint contributor package — 7 October 2026 + +This focused `sprint` contributor package uses the same public backend pins and +adapter digests as the earlier sprint PR #7014 and main PR #7026. It changes the +developer setup hook and adds contributor/security documentation and a +public-backend CI workflow; it does not modify mobile, dependency or release +files. Backend/bootstrap verification for this exact branch is recorded with +its PR checks. Native app builds must be assessed against the selected app +branch and platform separately. +The dated sections below preserve earlier sprint and public-source evidence; +historical private-source failures are not the current public backend result. + +## Public Relay transition — 7 October 2026 + +- Clean-history [Relay](https://github.com/KeeperCommunity/Relay) is public at + `3e1a01bd2fd5381d8546229922c431ce50bedad4`; the legacy credential-bearing + Relay repository remains private. GitHub private vulnerability reporting is + enabled on the public repository. +- An anonymous Relay clone at that exact commit passed a frozen Node 22 install, + compilation, 104 tests across nine suites with disposable MongoDB, current + source and full-history secret scans, and the runtime dependency audit. A + separate local Compose run served ready/local health, persisted a synthetic + app record and returned 503 for an unavailable hosted integration. Its + disposable containers and volumes were removed. +- Sprint PR #7014's public Relay pin and public SigningServer pin were fetched with + Git credential helpers disabled. Six bootstrap regression tests passed. The + isolated full stack passed health, Socket.IO, unsupported-route behavior, + synthetic app record create/read, and V3 testnet signer authorization and + valid/invalid 2FA. No production credentials or funded wallets were used. +- The optional persistence/boundary rerun stopped during Docker network + recreation with an engine input/output error after the host filled its disk. + That rerun is **not passed**. Free space was recovered, but no further Docker + build is being run while concurrent mobile QA uses the machine. CI on the + updated app commit and an independent developer/machine remain pending. +- No new native mobile build, physical-device check, hosted provider delivery, + real signing transaction, or production deployment is claimed by this + contributor source-pin change. + +## Public SigningServer follow-up — 6 October 2026 + +- The pinned SigningServer source is now the public + `KeeperCommunity/SigningServer` revision + `b82dc4f4a8f75676b70b12545d59c7906556a92b`. Its local adapter checksum + check and patch application pass. With Node 22, the adapted source passes + `npm ci --ignore-scripts`, `npm run compile` and `npm test` (2 suites, 108 tests). + The new independent GitHub SigningServer adapter job passes those same steps. +- SigningServer's previously cancelled current-source readiness job was rerun at + its public head: current-source and history scans both pass on the rerun. + Its own public test workflow also passes. Dependency review remains open; + successful source scans and tests are not security acceptance. +- A separate anonymous app checkout at app commit + `41e482ec97ebffb0beff43ed807b1205fb26ed8e` used an empty home and package + cache, disabled Git credential helpers and prompts, and copied no backend + source or environment files. `dev prepare` stopped at private Relay as expected. + `dev prepare-signing` fetched the public pin and applied its adapter without + Relay. `dev env` created a local-only file with mode `0600`; six bootstrap + regression tests passed. No full Docker stack or native build was possible + without Relay access. +- A separate anonymous SigningServer clone, with an initially empty package + cache and no Git credentials, passed `npm ci --ignore-scripts`, + `npm run compile` and `npm test` (2 suites, 108 tests). The local anonymous app + Yarn install was stopped before completion when this Mac had about 1.5 GB free; + no local anonymous app JavaScript install or Jest pass is claimed. On the same + app commit, GitHub Linux CI passed frozen Yarn install, 17 Jest suites / 183 + tests, strict active OpenSpec validation and LCOV upload. Its full backend job + passed bootstrap tests but failed fetching private Relay; later API/persistence + checks were skipped. These CI results do not establish an independent + full-stack checkout or native app acceptance. +- Relay remains private and its publication is deferred. Safe CI Relay access, + independent full-stack setup, remaining dependency/security review and + maintainer acceptance remain open. No production deployment or credential + change was part of this follow-up. + +## Earlier evidence — 26–28 September 2026 + +## Contributor handoff follow-up — 28 September 2026 + +- Removed the public contributor-access issue template. Access instructions now + use private intake/internal tracking, matching the owner's policy. Added + `HANDOFF.md` for independent-machine setup and separate pass/fail/untested reports. +- Five bootstrap regression tests, strict contributor OpenSpec validation, ten + local documentation links and diff whitespace checks: PASS. +- Restarted this Mac's existing Colima profile and ran the documented `dev up` + against the same pinned sources, existing disposable project/volumes and build + caches. Health, Socket.IO, explicit unsupported-route failure, app create/read + and V3 testnet authorization/2FA: PASS. +- `verify-local.sh --persistence --boundaries`: PASS, including retained app and + signing identity after recreation and rejection of mainnet/hosted databases. + This rerun is not a fresh-machine, native UI or transaction-signing test. +- Published baseline app head `434cd7c405d8723b3c21c7ce6e82745b9b254517`, GitHub + run `36240719417`: app tests/coverage PASS; backend bootstrap unit tests PASS; + backend startup FAIL and subsequent integration checks SKIPPED. CI access is + still unresolved; these CI results apply to that baseline, not a later head. +- Independent-machine verification, supported mobile Server Key acceptance, + backend readiness acceptance and safe CI source access remain open. No new + native build, full UI automation, provider-purchase or security-clearance pass + is claimed by this follow-up. + +## Readiness before private access + +The owner requires the same repository hygiene before private contributor access +as before public publication. Backend cleanup is published in private draft PRs. +This app now pins those updated revisions and its refreshed adapters have passed +a fresh Docker setup on this Mac. Broader backend access still awaits history +hygiene, credential handling, remaining dependency/security review and acceptance. +Detailed findings remain private. + +## Fresh backend readiness integration + +Updated pins: relay `5f59876b43fba1be9091657a6bf3389ce43831d0`, signing +`5ad45119ab014ea58efecabd54702b488d8fd254`. New app worktree, newly fetched +backend sources and new Docker volumes; host image/package caches and existing +GitHub read access reused. Project `keeper-readiness-proof` used ports +23000/24002/23003, preserving other development projects. + +- Source fetch, adapter checksums/application and container builds: PASS. +- All four service health checks, Socket.IO handshake, explicit unsupported-route + response and persisted app record create/read: PASS. +- V3 testnet Server Key setup, authorization and valid/invalid 2FA: PASS. +- Container recreation preserves the same app record and derived signer public + key: PASS. Mainnet/hosted database startup rejection: PASS. +- Five bootstrap regression tests: PASS. Active contributor OpenSpec validation: + PASS. Both backend test jobs and current-source scans pass in their own CI; + their history scans remain failing, tracked privately. +- Updated native development builds: iOS PASS after replacing a stale local + Node path; Android PASS after selecting the installed JDK 17 (976 tasks, 58 + executed, 918 cached). Both builds embed the isolated 23000/24002/23003 backend + configuration. Native app source is the previously verified sprint integration; + this follow-up changes only backend pins/adapters and documentation. +- Relay container compilation initially failed from memory exhaustion. Importing + only the existing Android Publisher v3 client reduced measured local compiler + memory to about 422 MB; the final image builds successfully with a 1 GB Node + heap. This retains the same provider API/library version. +- Final image startup/API/V3/2FA and persistence/configuration-boundary checks: + PASS. The earlier iOS onboarding record survives recreation. No actual store + purchase, signing transaction or backup/recovery correctness test is claimed. +- Native local smoke: iOS passcode/onboarding, Mobile Wallet and More Options + PASS using Maestro steps plus screenshot inspection. Initial Start New selector + failed despite the visible control; a visually guided tap continued the flow. + Relaunch/unlock after final backend restart PASS after handling the notification + prompt and repeated introductory/recovery-backup reminders; More Options assertion + passed. The original uninterrupted automation flows remain recorded as failures. +- Android: disposable emulator user 10 preserves the prior user's app data. Fresh + passcode/onboarding, Mobile Wallet and More Options PASS using ADB assertions + plus a visually guided Next tap. The first attempt used the wrong Metro; after + selecting the matching checkout and resetting only this new user's disposable + fixture, the relay created the native app record with HTTP 200. UIAutomator could + not reach idle during the animated Next screen; that original assertion timed + out, while visual navigation and subsequent assertions passed. An earlier + attempt also overlapped the deliberate backend restart and was retried. +- Native app records are confirmed in local MongoDB. This is onboarding/connectivity + evidence, not real signing, recovery, purchase or cloud-integration acceptance. +- Full Linux Docker CI still lacks private-source access. Independent-machine + setup and Keeper security acceptance remain pending. These commits are draft + review inputs and are not an approval to deploy production backends. + +## Access policy and analysis update + +The owner chose approved contributor access and deferred SonarCloud on 26 +September. [Access instructions](ACCESS.md) and a GitHub request template now +cover profile/context review, approved resource grants and setup confirmation. +Local edits need no individual approval. No invitations or CI credentials were +provisioned by this documentation change. SonarCloud is removed from active CI; +its earlier failures below remain historical evidence, not a passing analysis. +App tests and coverage remain active; private-source access still blocks backend +CI. Independent contributor setup remains pending. + +This documentation/workflow update passed YAML and issue-template parsing, +21 local documentation link checks, all five bootstrap tests and strict validation +of both active OpenSpec changes. Native builds were not repeated for this update; +the existing build results below apply to the unchanged app/native code. + +## Integration onto sprint + +The current PR is being integrated onto `sprint` commit `1adf4f663`; the release +baseline results below are historical and are not a substitute for these checks. +Fresh worktree and node_modules, host SDKs/caches reused: + +- Frozen Yarn installation: PASS. +- Jest: 17 suites / 183 tests PASS; process exits normally after adding test-only + Electrum/HTTP teardown. LCOV is generated (coverage scope is the existing + Electrum/wallet directories). +- Five bootstrap regression tests (including denied source access) and both active + OpenSpec changes: PASS. +- Broad validation of all legacy OpenSpec specs: 17 pre-existing specs failed; + CI validates active changes, not these legacy documents. +- Ruby lockfile constraints synchronized with Gemfile without gem version changes. +- Initial CocoaPods install failed because `sprint` locked openiap 1.2.22 while + its existing react-native-iap 16.5.0 requires 3.4.0. Targeted `pod update openiap` + aligned NitroIap/NitroModules/openiap with existing JavaScript dependencies; + 142 pods installed successfully. The updated lockfile is part of this PR. +- Fresh backend API, V3 authorization/2FA, persistence and configuration boundary + checks: PASS using this Mac's existing backend source access. +- Android development build: PASS (976 tasks, 5m20s). Install over the disposable + development app, local backend configuration and testnet passcode-screen launch: + PASS. Fresh signed iOS Debug simulator build: PASS (142 pods). Simulator install and + launch to the passcode screen: PASS by screenshot inspection. These launch + checks are not complete onboarding, recovery or transaction tests. +- GitHub Linux app job: PASS, 17 suites / 183 tests, active OpenSpec validation and + LCOV artifact upload. Measured line coverage is 57.37% (1451/2529) within the + existing configured source scope; no 80% coverage claim is made. +- GitHub Linux bootstrap unit tests: PASS. Docker startup: FAIL during source + fetch because both backend repositories were private at the time and CI lacked + access. Current full-stack CI still requires private Relay access. This is not + a passing full-stack setup check. +- SonarCloud: both the original and updated scanner failed before analysis; repository binding + still points at the old organization. See [CI notes](CI.md). No analysis pass + or security clearance is claimed. + +This integration preserves `sprint`'s app version fields; the separate 2.5.15 +release-version work is not imported or reverted by this contributor PR. + +## Test environment + +Fresh HTTPS clone of the published app tag `v2.5.15` (`e79e16b572d6e3472ac94500bf812d937bd89135`), plus this contributor setup change. New app dependency directories and newly fetched backend checkouts; no copied backend env files, databases or signing keys. Existing host SDKs, package caches and container image caches were reused. + +Apple Silicon Mac, macOS 26.6.2, Xcode 26.4/iOS 26.4 simulator, Node 25.9.0, Yarn 1.22.22, Python 3.9, Ruby 3.3.0/CocoaPods 1.15.2, JDK 17.0.19. Docker Engine 29.5.2/Compose 5.5.1 on Colima. Independent Compose project `keeper-contributor-clean`, newly generated volumes, loopback ports 13000/14002/13003. Existing developer/release services and data were preserved. + +## Results + +| Check | Result | +| --- | --- | +| Fetch pinned sources and verify/apply packaged adapters | PASS, both backends fetched from GitHub | +| Advertised `dev up`, including API checks | PASS after correcting the smoke fixture to use current V3 Server Key APIs | +| Mongo, relay, signing, gateway readiness | PASS | +| Socket.IO polling handshake | PASS | +| Relay create/read persisted app record | PASS | +| Unsupported relay integration | PASS, explicit HTTP 503 | +| V3 testnet Server Key setup and public-key format | PASS | +| Invalid authorization, valid 2FA, invalid 2FA | PASS | +| Container removal/recreation with retained volumes | PASS, same app record and derived signing public key | +| Mainnet and hosted Mongo configuration rejection | PASS for relay and signing | +| Actual container network/port inspection | PASS, backend network internal, no database port published, gateway bound only to loopback | +| Rerun setup, existing env preservation, adapter tampering, unknown checkout preservation, duplicate ports | PASS, four regression tests plus real repeated bootstrap | +| Fresh `yarn install --frozen-lockfile --non-interactive` | PASS; no tracked dependency version changes | +| Fresh CocoaPods installation | PASS, 142 pods; see path-dependent checksum note below | +| Fresh Android `assembleDevelopmentDebug` | PASS, 976 tasks executed, 5m17s | +| Android installed local configuration | PASS, development environment and alternate local backend ports verified in generated BuildConfig | +| Android fresh install, passcode creation, onboarding, Mobile Wallet and More Options | PASS via ADB UI assertions and observed emulator controls | +| Android local app record creation | PASS, HTTP 200 and database record confirmation | +| Android Maestro driver | UNAVAILABLE, gRPC connection failed twice before flow execution; no Maestro pass claimed | +| Fresh iOS development simulator build | PASS, signed Debug simulator app from fresh Pods/derived data | +| iOS simulator launch, passcode creation/unlock and local relay connection | PASS, dev app launched; local app record created (two native app records total) | +| iOS onboarding through Wallets | PASS by simulator screenshot inspection; Maestro text assertion failed despite the visible Mobile Wallet tile | +| iOS More Options | PASS, simulator navigation and screenshot inspected | +| Node/Mongo/nginx pinned image manifests | PASS, each includes Linux amd64 and arm64 | +| Existing release version consistency | PASS, unchanged 2.5.15 / Android 622 / iOS 615 | +| Strict OpenSpec validation | PASS | + +Native apps use a separate Metro process on port 8082 during this acceptance run, preserving the existing developer's Metro on 8081. Android's dev-server host is set to localhost with device port 8081 forwarded to host 8082. Ordinary single-checkout instructions use port 8081. + +## Findings and limits + +- The pinned relay and signing backends acknowledge creation before their save callbacks complete. The check polls for record visibility for up to five seconds before dependent reads; it does not hide a rejected verification token or an unexpected response. +- An exploratory legacy V2 Server Key setup returned success and then terminated its signing process. Its source uses a structured verifier schema but writes a string. This is an observed limitation of the pinned backend, not a verified production incident. Current app acceptance uses V3. Legacy V2 workflows remain outside the supported acceptance scope; this packaging change does not repair wallet/signing business logic. +- Initial CocoaPods `--deployment` failed because the Hermes podspec embeds an absolute `HERMES_CLI_PATH`. A normal locked `pod install` refreshed only that podspec checksum to the new checkout path. Comparing old/new podspec JSON confirmed the path is the only difference. No dependency version changed. This generated lockfile difference is not part of the contributor source change. +- Initial iOS UI scripts hit modal timing/selector failures, and one automated unlock was rejected. Retrying the same fixture PIN with waits succeeded. The XCUITest driver also needed a simulator restart after a failed connection; app data was preserved. The Mobile Wallet tile and Start New card were visible in screenshots when text assertions could not find them. These are recorded as automation limitations, not passes of the original complete flows; visual checks are explicitly distinguished from automated assertions. +- React Native/third-party dependencies emit existing peer-dependency, export-resolution and native deprecation warnings. Build success is not a claim that those upstream warnings are resolved. +- This proves a fresh checkout on this Mac, not a second physical machine. Intel/Linux/Windows, physical devices, cloud integrations, hardware wallets, real Server Key transactions, recovery correctness and scheduled inheritance flows remain unverified here. Recovery T-060 and store/source reconciliation are separate tasks. +- Backend image digests and source pins constrain inputs; package caches and Debian package repositories prevent claiming a bit-identical image build. + +## Reproduce checks + +```sh +./dev/local-backend/dev up +./dev/local-backend/verify-local.sh --persistence --boundaries +python3 -B -m unittest discover -s dev/local-backend -p test_keeper.py +npx --no-install openspec validate package-contributor-development --strict +``` + +The acceptance logs and emulator fixtures remain on the maintainer's machine outside the source package. Do not include local databases, generated signing identities, recovery material or captured emails in a source review or handoff archive. diff --git a/dev/local-backend/adapters/signing/files/.dockerignore b/dev/local-backend/adapters/signing/files/.dockerignore new file mode 100644 index 0000000000..e8b30bfc29 --- /dev/null +++ b/dev/local-backend/adapters/signing/files/.dockerignore @@ -0,0 +1,9 @@ +.git +.env* +node_modules +dist +**/*.pem +**/*.p12 +**/*.key +logfile.log +coverage diff --git a/dev/local-backend/adapters/signing/files/Dockerfile.local b/dev/local-backend/adapters/signing/files/Dockerfile.local new file mode 100644 index 0000000000..f14a93fd88 --- /dev/null +++ b/dev/local-backend/adapters/signing/files/Dockerfile.local @@ -0,0 +1,11 @@ +FROM node:22-bookworm-slim@sha256:43ac6c60b8f89723f746e8a92ce91abd5017e627ce1ddfe4238355d3a30b772c +WORKDIR /app +COPY package.json package-lock.json ./ +RUN npm ci --ignore-scripts +COPY tsconfig.json ./ +COPY src ./src +COPY scripts/local-entry.cjs ./scripts/local-entry.cjs +RUN npm run compile && mkdir /local-data && chown node:node /local-data /app +ENV NODE_ENV=development +USER node +CMD ["node", "scripts/local-entry.cjs"] diff --git a/dev/local-backend/adapters/signing/files/scripts/local-entry.cjs b/dev/local-backend/adapters/signing/files/scripts/local-entry.cjs new file mode 100644 index 0000000000..2795934ca9 --- /dev/null +++ b/dev/local-backend/adapters/signing/files/scripts/local-entry.cjs @@ -0,0 +1,14 @@ +// Local test keys are created once per Docker volume. Never print their values. +const fs = require('node:fs'); +const crypto = require('node:crypto'); +const bip39 = require('bip39'); +if (process.env.LOCAL_DEV !== 'true' || process.env.ENVIRONMENT !== 'TEST') throw new Error('Local entry requires LOCAL_DEV and TEST'); +const file = '/local-data/secrets.json'; +if (!fs.existsSync(file)) { + const rsa = crypto.generateKeyPairSync('rsa', { modulusLength: 2048, + privateKeyEncoding: { type: 'pkcs1', format: 'pem' }, publicKeyEncoding: { type: 'spki', format: 'pem' } }); + const secrets = { 'local-rsa-private': rsa.privateKey, 'local-rsa-public': rsa.publicKey }; + for (const id of ['local-signer-v2', 'local-signer-v3', 'local-inheritance-v2', 'local-inheritance-v3']) secrets[id] = bip39.generateMnemonic(256); + fs.writeFileSync(file, JSON.stringify(secrets), { mode: 0o600, flag: 'wx' }); +} +require('../dist/index.js'); diff --git a/dev/local-backend/adapters/signing/files/src/config.ts b/dev/local-backend/adapters/signing/files/src/config.ts new file mode 100644 index 0000000000..1df0526542 --- /dev/null +++ b/dev/local-backend/adapters/signing/files/src/config.ts @@ -0,0 +1,100 @@ +import * as bitcoinJS from "bitcoinjs-lib"; +import dotenv from "dotenv"; +import { fetchSecrets } from "./utilities/secretManager"; +import { logger } from "./utilities/logger" +import { WalletCredsVersion } from "./interfaces/wallet"; + +const result = dotenv.config(); + +if (result.error && process.env.LOCAL_DEV !== "true") { + throw result.error; +} + +export enum SERVER_TYPE { + MAIN = "MAIN", + TEST = "TEST" +} + +export enum DATABASE_TYPE { + DEV = "DEV", + PROD = "PROD" +} + +class Config { + public LOCAL_DEV = process.env.LOCAL_DEV === "true"; + public ENVIRONMENT: string = process.env.ENVIRONMENT; + public PORT: string = process.env.PORT || "3003"; + public NETWORK: bitcoinJS.Network; + public HEXA_ID = process.env.HEXA_ID + public RELAY = process.env.RELAY + + public INHERITANCE_KEY_REQUEST_THRESHOLD: number; // 30days(prod) / 5 mins(dev) + public INHERITANCE_KEY_REQUEST_TTL: number; // 3x of request threshold duration + public ADMIN_KEY: string = process.env.BIT_ADMIN_KEY; + public VERSION: string = process.env.VERSION; + + public MAILER_CONFIG = { + SES_REGION: process.env.SES_REGION, + SOURCE_EMAIL: process.env.SES_SOURCE_EMAIL, + ACCESS_KEY_ID: process.env.SES_ACCESS_KEY_ID, + SECRET_ACCESS_KEY: process.env.SES_SECRET_ACCESS_KEY, + } + + public DB_MODE = process.env.DB_MODE; + public DATABASE_NAME_V2: string = process.env.DATABASE_NAME_V2; + public DATABASE_SECRET_IDENTIFIER_V2: string = process.env.DATABASE_SECRET_IDENTIFIER_V2; + public PROJECT_ID: string = process.env.PROJECT_ID; + public MIN_POLICY_UPDATE_DELAY: number; + + public MNEMONIC_IDENTIFIERS = { + [WalletCredsVersion.V2]: process.env.MNEMONIC_IDENTIFIER_V2, + [WalletCredsVersion.V3]: process.env.MNEMONIC_IDENTIFIER_V3, + }; + + public INHERITANCE_MNEMONIC_IDENTIFIERS = { + [WalletCredsVersion.V2]: process.env.INHERITANCE_MNEMONIC_IDENTIFIER_V2, + [WalletCredsVersion.V3]: process.env.INHERITANCE_MNEMONIC_IDENTIFIER_V3, + }; + + public RSA_PRV_KEY_IDENTIFIER: string = process.env.RSA_PRV_KEY_IDENTIFIER; + public RSA_PUB_KEY_IDENTIFIER: string = process.env.RSA_PUB_KEY_IDENTIFIER; + public RSA_PRV_KEY: string; + public RSA_PUB_KEY: string; + + constructor() { + if (this.LOCAL_DEV) { + const db = new URL(process.env.LOCAL_DATABASE_URL || ""); + if (this.ENVIRONMENT !== "TEST" || this.DB_MODE !== "DEV" || + db.protocol !== "mongodb:" || !["mongo", "localhost", "127.0.0.1"].includes(db.hostname) || + db.username || db.password || db.pathname !== "/keeper_signing_local") { + throw new Error("Local signing requires TEST, DEV and the isolated local database"); + } + if (this.HEXA_ID !== "keeper-local-only") throw new Error("Local signing requires its own application credential"); + } + this.configureNetwork(); + } + + public configureNetwork = () => { + if (this.ENVIRONMENT === SERVER_TYPE.MAIN) { + this.NETWORK = bitcoinJS.networks.bitcoin; + this.INHERITANCE_KEY_REQUEST_THRESHOLD = 2592000000 // 30 days in milliseconds + this.MIN_POLICY_UPDATE_DELAY = 1 * 7 * 24 * 60 * 60 * 1000 // 1 week in milliseconds + } else if (this.ENVIRONMENT === SERVER_TYPE.TEST) { + this.NETWORK = bitcoinJS.networks.testnet; + this.INHERITANCE_KEY_REQUEST_THRESHOLD = 300000 // 5 mins in milliseconds + this.MIN_POLICY_UPDATE_DELAY = 1 * 60 * 60 * 1000 // 1 hour in milliseconds + } else { + throw new Error("Please specify an apt environment(MAIN||TEST)"); + } + this.INHERITANCE_KEY_REQUEST_TTL = (this.INHERITANCE_KEY_REQUEST_THRESHOLD / 1000) * 3 + }; + + public initRSAKeys = async () => { + const [privResponse, pubResponse] = await fetchSecrets([this.RSA_PRV_KEY_IDENTIFIER, this.RSA_PUB_KEY_IDENTIFIER]); + this.RSA_PRV_KEY = privResponse[this.RSA_PRV_KEY_IDENTIFIER] + this.RSA_PUB_KEY = pubResponse[this.RSA_PUB_KEY_IDENTIFIER] + logger.info('RSA keys have been initialized') + } +} + +export default new Config(); diff --git a/dev/local-backend/adapters/signing/local.patch b/dev/local-backend/adapters/signing/local.patch new file mode 100644 index 0000000000..d13580b53a --- /dev/null +++ b/dev/local-backend/adapters/signing/local.patch @@ -0,0 +1,132 @@ +diff --git a/src/databases/dbV2.ts b/src/databases/dbV2.ts +index dc661dc..31b47a9 100644 +--- a/src/databases/dbV2.ts ++++ b/src/databases/dbV2.ts +@@ -269,6 +269,13 @@ class DatabaseV2 { + } + + public initializeConnection = async () => { ++ if (config.LOCAL_DEV) { ++ this.connection = mongoose.createConnection(process.env.LOCAL_DATABASE_URL, { ++ dbName: "keeper_signing_local", autoIndex: true, ++ }); ++ await this.connection.asPromise(); ++ return; ++ } + const [response] = await fetchSecrets( + [config.DATABASE_SECRET_IDENTIFIER_V2], + true +@@ -288,6 +295,8 @@ class DatabaseV2 { + }); + }; + ++ public isReady = () => this.connection?.readyState === 1; ++ + public getSignerV2Model = (): mongoose.Model => { + return this.connection.model("Signer", this.signerV2); + }; +diff --git a/src/index.ts b/src/index.ts +index 7e3a325..bee0b07 100644 +--- a/src/index.ts ++++ b/src/index.ts +@@ -3,6 +3,7 @@ import express, { Express } from "express"; + import morgan from "morgan"; + + import config from "./config"; ++import dbV2 from "./databases/dbV2"; + import { logger, unhandledLogger} from "./utilities/logger" + import { initializeCrons } from "./utilities/crons"; + import { initializeRoutes } from "./routes/router"; +@@ -14,7 +15,7 @@ class SigningServer { + this.app = express(); + this.configure(); + this.invoke(); +- initializeCrons(); ++ if (!config.LOCAL_DEV) initializeCrons(); + config.initRSAKeys(); + } + +@@ -24,6 +25,13 @@ class SigningServer { + this.app.use(morgan("combined", { stream: { write: message => logger.info(message.trim()) } })); + this.app.use(bodyParser.json()); + this.app.use(bodyParser.urlencoded({ extended: true })); ++ if (config.LOCAL_DEV) { ++ this.app.get("/health", (_req, res) => { ++ const ready = dbV2.isReady() && !!config.RSA_PUB_KEY; ++ res.status(ready ? 200 : 503).json({ ready, mode: "local", network: "TESTNET", ++ capabilities: { signing: ready, emailDelivery: false, pushDelivery: false, scheduledJobs: false } }); ++ }); ++ } + this.app.use(initializeRoutes(this.app)); + } + +diff --git a/src/services/mailing/mailer.ts b/src/services/mailing/mailer.ts +index 9ab6b1d..3995234 100644 +--- a/src/services/mailing/mailer.ts ++++ b/src/services/mailing/mailer.ts +@@ -1,5 +1,6 @@ + import config from "../../config"; + import moment from "moment"; ++import { appendFileSync } from "fs"; + import AWS from "aws-sdk"; + import { EMAIL_TEMPLATES } from "./templates"; + +@@ -65,7 +66,7 @@ const fetchEmailContentByType = ( + ) + .replace( + "{{server_url}}", +- config.ENVIRONMENT === "MAIN" ++ config.LOCAL_DEV ? "http://localhost:3003" : config.ENVIRONMENT === "MAIN" + ? "https://sign.bithyve.com" + : "https://dev-sign.bithyve.com" + ) +@@ -109,5 +110,9 @@ export const sendEmails = ( + }, + }, + }; ++ if (config.LOCAL_DEV) { ++ appendFileSync("/local-data/outbox.jsonl", JSON.stringify({ capturedAt: new Date().toISOString(), ...params }) + "\n", { mode: 0o600 }); ++ return Promise.resolve({ MessageId: "local-captured-not-delivered" }); ++ } + return AWS_SES.sendEmail(params).promise(); + }; +diff --git a/src/services/notifications/pushNotification.ts b/src/services/notifications/pushNotification.ts +index 87e9d5c..477681d 100644 +--- a/src/services/notifications/pushNotification.ts ++++ b/src/services/notifications/pushNotification.ts +@@ -85,6 +85,7 @@ export const pushIKNotification = async ( + requestAutoApprovesIn?: number; + } + ) => { ++ if (config.LOCAL_DEV) { logger.info("Local mode: push delivery disabled"); return; } + try { + const requestData = { + FCMs, +@@ -118,6 +119,7 @@ export const pushServerKeyNotification = async ( + signedTx?: string; + } + ) => { ++ if (config.LOCAL_DEV) { logger.info("Local mode: push delivery disabled"); return; } + try { + let title; + let body; +diff --git a/src/utilities/secretManager.ts b/src/utilities/secretManager.ts +index e6bfd49..3b3b732 100644 +--- a/src/utilities/secretManager.ts ++++ b/src/utilities/secretManager.ts +@@ -1,7 +1,15 @@ + import { SecretManagerServiceClient } from '@google-cloud/secret-manager'; + import config from '../config'; ++import { readFileSync } from 'fs'; + + export const fetchSecrets = async (secretIdentifiers: string[], shouldParse: Boolean = false) => { ++ if (config.LOCAL_DEV) { ++ const secrets = JSON.parse(readFileSync("/local-data/secrets.json", "utf8")); ++ return secretIdentifiers.map(identifier => { ++ if (!Object.prototype.hasOwnProperty.call(secrets, identifier)) throw new Error("Unknown local secret identifier"); ++ return { [identifier]: shouldParse ? JSON.parse(secrets[identifier]) : secrets[identifier] }; ++ }); ++ } + const client = new SecretManagerServiceClient(); + const projectId = config.PROJECT_ID; + diff --git a/dev/local-backend/app.env.local.example b/dev/local-backend/app.env.local.example new file mode 100644 index 0000000000..0121ab915d --- /dev/null +++ b/dev/local-backend/app.env.local.example @@ -0,0 +1,10 @@ +# Disposable local development only. Copy to app repo .env.local. +ENVIRONMENT=DEVELOPMENT +RELAY=http://localhost:3000/ +CHANNEL_URL=http://localhost:4002/ +SIGNING_SERVER_TESTNET=http://localhost:3003/ +SIGNING_SERVER_MAINNET=http://localhost:3003/mainnet-disabled/ +HEXA_ID_TESTNET=keeper-local-only +HEXA_ID_MAINNET=keeper-local-mainnet-disabled +ENC_KEY_STORAGE_IDENTIFIER=KEEPER-LOCAL-DEV +SENTRY_DNS=http://local@localhost:3000/1 diff --git a/dev/local-backend/compose.yaml b/dev/local-backend/compose.yaml new file mode 100644 index 0000000000..e26754b4c7 --- /dev/null +++ b/dev/local-backend/compose.yaml @@ -0,0 +1,98 @@ +name: ${COMPOSE_PROJECT_NAME:-keeper-contributor} +services: + mongo: + image: mongo:7.0@sha256:9854f7139445d766a9523571d6f047530c45547460ffcf8259eb2bf4264632ca + volumes: + - mongo-data:/data/db + networks: [local-only] + healthcheck: + test: [CMD, mongosh, --quiet, --eval, "quit(db.adminCommand('ping').ok ? 0 : 1)"] + interval: 5s + timeout: 5s + retries: 20 + relay: + build: + context: ./.sources/relay + dockerfile: Dockerfile.local + environment: + LOCAL_DEV: "true" + ENVIRONMENT: DEVELOPMENT + BITCOIN_NETWORK: TESTNET + VERSION: local-development + DATABASE_URL: mongodb://mongo:27017/keeper_local + PORT: "3000" + WS_PORT: "4002" + HEXA_ID: keeper-local-only + ADMIN_KEY: keeper-local-admin-only + CHANNEL_URL: http://relay:4002/ + FAUCET_MNEMONIC: "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about" + networks: [local-only] + depends_on: + mongo: + condition: service_healthy + healthcheck: + test: [CMD, node, -e, "fetch('http://localhost:3000/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"] + interval: 5s + timeout: 5s + retries: 20 + signing: + build: + context: ./.sources/signing + dockerfile: Dockerfile.local + environment: + LOCAL_DEV: "true" + ENVIRONMENT: TEST + DB_MODE: DEV + PORT: "3003" + VERSION: local-development + HEXA_ID: keeper-local-only + BIT_ADMIN_KEY: keeper-local-admin-only + LOCAL_DATABASE_URL: mongodb://mongo:27017/keeper_signing_local + RELAY: http://relay:3000/ + MNEMONIC_IDENTIFIER_V2: local-signer-v2 + MNEMONIC_IDENTIFIER_V3: local-signer-v3 + INHERITANCE_MNEMONIC_IDENTIFIER_V2: local-inheritance-v2 + INHERITANCE_MNEMONIC_IDENTIFIER_V3: local-inheritance-v3 + RSA_PRV_KEY_IDENTIFIER: local-rsa-private + RSA_PUB_KEY_IDENTIFIER: local-rsa-public + SES_REGION: us-east-1 + SES_SOURCE_EMAIL: local@example.invalid + volumes: + - signing-data:/local-data + networks: [local-only] + depends_on: + mongo: + condition: service_healthy + healthcheck: + test: [CMD, node, -e, "fetch('http://localhost:3003/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"] + interval: 5s + timeout: 5s + retries: 20 + gateway: + healthcheck: + test: [CMD-SHELL, "wget -q -O /dev/null http://127.0.0.1:3000/health && wget -q -O /dev/null http://127.0.0.1:3003/health"] + interval: 5s + timeout: 5s + retries: 20 + image: nginx:1.28-alpine@sha256:a8b39bd9cf0f83869a2162827a0caf6137ddf759d50a171451b335cecc87d236 + volumes: + - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro + ports: + - "127.0.0.1:${KEEPER_RELAY_PORT:-3000}:3000" + - "127.0.0.1:${KEEPER_CHANNEL_PORT:-4002}:4002" + - "127.0.0.1:${KEEPER_SIGNING_PORT:-3003}:3003" + networks: [local-only, host-access] + depends_on: + relay: + condition: service_healthy + restart: true + signing: + condition: service_healthy + restart: true +networks: + local-only: + internal: true + host-access: +volumes: + mongo-data: + signing-data: diff --git a/dev/local-backend/dev b/dev/local-backend/dev new file mode 100755 index 0000000000..52a7cab783 --- /dev/null +++ b/dev/local-backend/dev @@ -0,0 +1,3 @@ +#!/bin/sh +set -eu +exec python3 "$(dirname "$0")/keeper.py" "$@" diff --git a/dev/local-backend/keeper.py b/dev/local-backend/keeper.py new file mode 100644 index 0000000000..ffed894485 --- /dev/null +++ b/dev/local-backend/keeper.py @@ -0,0 +1,181 @@ +#!/usr/bin/env python3 +"""Contributor setup using only Python's standard library, Git and Compose.""" +import argparse +import hashlib +import json +import os +from pathlib import Path +import re +import shutil +import subprocess +import sys +import tempfile + +HERE = Path(__file__).resolve().parent +APP = HERE.parent.parent + + +def run(args, **kwargs): + return subprocess.run([str(a) for a in args], check=True, **kwargs) + + +def output(args, **kwargs): + return subprocess.check_output([str(a) for a in args], text=True, **kwargs).strip() + + +def settings(): + values = {} + envfile = HERE / '.env' + if envfile.exists(): + for line in envfile.read_text().splitlines(): + if line.strip() and not line.lstrip().startswith('#'): + key, sep, value = line.partition('=') + if not sep: + raise ValueError('Use KEY=value lines in dev/local-backend/.env') + values[key.strip()] = value.strip() + defaults = {'COMPOSE_PROJECT_NAME': 'keeper-contributor', + 'KEEPER_RELAY_PORT': '3000', 'KEEPER_CHANNEL_PORT': '4002', + 'KEEPER_SIGNING_PORT': '3003'} + for key, default in defaults.items(): + values[key] = os.environ.get(key, values.get(key, default)) + if not re.fullmatch(r'[a-z0-9][a-z0-9_-]*', values['COMPOSE_PROJECT_NAME']): + raise ValueError('COMPOSE_PROJECT_NAME must contain lowercase letters, digits, _ or -') + ports = [int(values[k]) for k in defaults if k.endswith('_PORT')] + if len(set(ports)) != 3 or any(p < 1024 or p > 65535 for p in ports): + raise ValueError('Choose three distinct ports between 1024 and 65535') + return {k: values[k] for k in defaults} + + +def compose(*args, **kwargs): + env = dict(os.environ, **settings()) + return run(['docker', 'compose', '--env-file', HERE / '.env.example', + '-f', HERE / 'compose.yaml', *args], env=env, **kwargs) + + +def prepare(only=None): + lock = json.loads((HERE / 'sources.lock.json').read_text()) + sources = HERE / '.sources' + sources.mkdir(exist_ok=True) + for name, spec in lock.items(): + if only is not None and name != only: + continue + adapter = HERE / 'adapters' / name + for asset, digest in spec['assets'].items(): + if hashlib.sha256((adapter / asset).read_bytes()).hexdigest() != digest: + raise ValueError(f'{name}: adapter checksum mismatch: {asset}') + fingerprint = hashlib.sha256(json.dumps(spec, sort_keys=True).encode()).hexdigest() + target = sources / name + marker = target / '.keeper-source.json' + if target.exists(): + if not marker.exists() or json.loads(marker.read_text()) != spec: + raise ValueError(f'{target}: existing checkout does not match this setup. ' + 'Move it aside after saving your edits, then retry; it was not overwritten.') + if output(['git', '-C', target, 'rev-parse', 'HEAD']) != spec['revision']: + raise ValueError(f'{target}: HEAD changed; save your work and move this checkout aside.') + print(f'{name}: already prepared; preserving local backend edits ({fingerprint[:12]})') + continue + with tempfile.TemporaryDirectory(prefix=f'.{name}-', dir=sources) as temp: + checkout = Path(temp) / 'checkout' + run(['git', 'init', '--quiet', checkout]) + run(['git', '-C', checkout, 'remote', 'add', 'origin', spec['url']]) + print(f'{name}: fetching {spec["revision"]}', flush=True) + try: + run(['git', '-C', checkout, 'fetch', '--quiet', '--depth=1', 'origin', spec['revision']]) + except subprocess.CalledProcessError as error: + raise ValueError(f'{name}: cannot fetch the pinned public backend revision. ' + 'Check the revision and network connection. ' + 'No existing checkout was replaced.') from error + run(['git', '-C', checkout, 'checkout', '--quiet', '--detach', spec['revision']]) + if spec['assets']: + run(['git', '-C', checkout, 'apply', '--check', adapter / 'local.patch']) + run(['git', '-C', checkout, 'apply', adapter / 'local.patch']) + for asset in (adapter / 'files').rglob('*'): + if asset.is_file(): + dest = checkout / asset.relative_to(adapter / 'files') + dest.parent.mkdir(parents=True, exist_ok=True) + shutil.copyfile(asset, dest) + (checkout / '.keeper-source.json').write_text(json.dumps(spec, indent=2) + '\n') + checkout.rename(target) + + +def app_env(): + config = settings() + template = (HERE / 'app.env.local.example').read_text() + for port, name in [('3000', 'RELAY'), ('4002', 'CHANNEL'), ('3003', 'SIGNING')]: + template = template.replace(f':{port}/', f':{config[f"KEEPER_{name}_PORT"]}/') + dest = APP / '.env.local' + if dest.exists(): + if dest.read_text() != template: + raise ValueError('.env.local already exists with different settings. Compare it with ' + 'dev/local-backend/app.env.local.example; no file was overwritten.') + print('.env.local already matches this setup') + return + fd = os.open(dest, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) + with os.fdopen(fd, 'w') as stream: + stream.write(template) + print('Created .env.local (local test settings only)') + + +def doctor(): + failed = False + for label, args in [('Git', ['git', '--version']), ('Docker Engine', ['docker', 'info', '--format', '{{.ServerVersion}}']), + ('Docker Compose', ['docker', 'compose', 'version']), ('Node', ['node', '--version']), + ('Yarn', ['yarn', '--version'])]: + try: + print(f'{label}: {output(args, stderr=subprocess.DEVNULL)}') + except (OSError, subprocess.CalledProcessError): + print(f'MISSING: {label}') + failed = True + print('Python:', sys.version.split()[0]) + print('Android SDK:', os.environ.get('ANDROID_HOME', 'set ANDROID_HOME before Android builds')) + print('JAVA_HOME:', os.environ.get('JAVA_HOME', 'set JAVA_HOME to JDK 17 before Android builds')) + if sys.platform == 'darwin': + for label, args in [('Xcode', ['xcodebuild', '-version']), ('Ruby', ['ruby', '--version']), + ('Bundler', ['bundle', '--version'])]: + try: + print(f'{label}: {output(args, stderr=subprocess.DEVNULL)}') + except (OSError, subprocess.CalledProcessError): + print(f'MISSING for iOS: {label}') + print('See README.md for required native tool versions; this checks availability, not native builds.') + if failed: + raise ValueError('Install/start the missing prerequisites and rerun doctor.') + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument('command', choices=['doctor', 'prepare', 'prepare-signing', 'up', 'stop', 'status', 'logs', 'verify', 'env', 'android-forward']) + parser.add_argument('--serial', help='Android emulator/device serial for android-forward') + args = parser.parse_args() + if args.command == 'doctor': + doctor() + elif args.command == 'prepare': + prepare() + elif args.command == 'prepare-signing': + prepare(only='signing') + elif args.command == 'up': + prepare() + compose('up', '-d', '--build', '--wait', '--wait-timeout', '180') + run([sys.executable, HERE / 'verify.py']) + elif args.command == 'stop': + compose('down') # Retain both databases and signing keys. No implicit data reset. + elif args.command == 'status': + compose('ps') + elif args.command == 'logs': + compose('logs', '--tail', '100') + elif args.command == 'verify': + run([sys.executable, HERE / 'verify.py']) + elif args.command == 'env': + app_env() + elif args.command == 'android-forward': + if not args.serial: + parser.error('android-forward requires --serial; use adb devices to choose one') + for port in ['8081'] + [v for k, v in settings().items() if k.endswith('_PORT')]: + run(['adb', '-s', args.serial, 'reverse', f'tcp:{port}', f'tcp:{port}']) + + +if __name__ == '__main__': + try: + main() + except (OSError, ValueError, subprocess.CalledProcessError) as error: + print(f'Setup failed: {error}', file=sys.stderr) + sys.exit(1) diff --git a/dev/local-backend/nginx.conf b/dev/local-backend/nginx.conf new file mode 100644 index 0000000000..bcd9481514 --- /dev/null +++ b/dev/local-backend/nginx.conf @@ -0,0 +1,22 @@ +server { + listen 3000; + client_max_body_size 50m; + location / { + proxy_pass http://relay:3000; + } +} +server { + listen 4002; + location / { + proxy_pass http://relay:4002; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + } +} +server { + listen 3003; + location / { + proxy_pass http://signing:3003; + } +} diff --git a/dev/local-backend/sources.lock.json b/dev/local-backend/sources.lock.json new file mode 100644 index 0000000000..231f141db1 --- /dev/null +++ b/dev/local-backend/sources.lock.json @@ -0,0 +1,18 @@ +{ + "relay": { + "url": "https://github.com/KeeperCommunity/Relay.git", + "revision": "3e1a01bd2fd5381d8546229922c431ce50bedad4", + "assets": {} + }, + "signing": { + "url": "https://github.com/KeeperCommunity/SigningServer.git", + "revision": "b82dc4f4a8f75676b70b12545d59c7906556a92b", + "assets": { + "files/.dockerignore": "78d9a1e03c57cfc1c7fb79ff2335aa2393bb075d0ac4a23feae81371728190be", + "files/Dockerfile.local": "04a0bfca3903eb1363f8804b7c181424747c949aed543a89fe7a02316ccafa3d", + "files/scripts/local-entry.cjs": "7e0d39965fd8d4a880ab68b5ff9e7b75595c33cbdb106bb5ec0b42d505b1827b", + "files/src/config.ts": "606fdeb4717e98ab95e5a6918a0c8a8b9b3427697d27bba263b9ec566a91438e", + "local.patch": "a592f37900215a5f013a0d349983f7a1d937206fbf1670c07fc9a37e457d743f" + } + } +} diff --git a/dev/local-backend/test_keeper.py b/dev/local-backend/test_keeper.py new file mode 100644 index 0000000000..3c80fd9d0c --- /dev/null +++ b/dev/local-backend/test_keeper.py @@ -0,0 +1,92 @@ +"""Regression checks for setup operations that must preserve developer work.""" +import hashlib +import json +import subprocess +from pathlib import Path +import tempfile +import unittest +from unittest.mock import patch + +import keeper + + +class PreserveDeveloperWork(unittest.TestCase): + def setUp(self): + self.temp = tempfile.TemporaryDirectory() + self.addCleanup(self.temp.cleanup) + self.app = Path(self.temp.name) + self.here = self.app / 'dev/local-backend' + self.here.mkdir(parents=True) + self.contexts = [patch.object(keeper, 'HERE', self.here), patch.object(keeper, 'APP', self.app), + patch.dict('os.environ', {}, clear=True)] + for context in self.contexts: + context.start() + self.addCleanup(context.stop) + + def test_environment_is_exclusive_and_preserves_production(self): + (self.here / 'app.env.local.example').write_text('RELAY=http://localhost:3000/\n') + production = self.app / '.env.production' + production.write_text('existing-production-sentinel\n') + keeper.app_env() + self.assertEqual((self.app / '.env.local').stat().st_mode & 0o777, 0o600) + keeper.app_env() # Same configuration is repeatable. + (self.app / '.env.local').write_text('developer-settings\n') + with self.assertRaisesRegex(ValueError, 'already exists'): + keeper.app_env() + self.assertEqual((self.app / '.env.local').read_text(), 'developer-settings\n') + self.assertEqual(production.read_text(), 'existing-production-sentinel\n') + + def test_adapter_tampering_is_rejected_before_fetch(self): + adapter = self.here / 'adapters/relay' + adapter.mkdir(parents=True) + (adapter / 'local.patch').write_text('changed') + (self.here / 'sources.lock.json').write_text(json.dumps({'relay': { + 'assets': {'local.patch': hashlib.sha256(b'original').hexdigest()}}})) + with patch.object(keeper, 'run') as command: + with self.assertRaisesRegex(ValueError, 'checksum mismatch'): + keeper.prepare() + command.assert_not_called() + + def test_unknown_existing_checkout_is_not_overwritten(self): + source = self.here / '.sources/relay' + source.mkdir(parents=True) + edit = source / 'my-work.ts' + edit.write_text('keep this') + (self.here / 'sources.lock.json').write_text(json.dumps({'relay': {'assets': {}}})) + with patch.object(keeper, 'run') as command: + with self.assertRaisesRegex(ValueError, 'not overwritten'): + keeper.prepare() + command.assert_not_called() + self.assertEqual(edit.read_text(), 'keep this') + + def test_port_collision_is_rejected(self): + (self.here / '.env').write_text('KEEPER_RELAY_PORT=3003\n') + with self.assertRaisesRegex(ValueError, 'distinct ports'): + keeper.settings() + + def test_fetch_failure_explains_public_revision_and_cleans_temporary_checkout(self): + (self.here / 'sources.lock.json').write_text(json.dumps({'relay': { + 'assets': {}, 'url': 'https://github.com/example/private-backend.git', + 'revision': 'a' * 40}})) + with patch.object(keeper, 'run', side_effect=[ + None, None, subprocess.CalledProcessError(128, ['git', 'fetch'])]): + with self.assertRaisesRegex(ValueError, 'pinned public backend revision'): + keeper.prepare() + self.assertEqual(list((self.here / '.sources').iterdir()), []) + + def test_signing_prepare_does_not_fetch_relay(self): + (self.here / 'sources.lock.json').write_text(json.dumps({ + 'relay': {'assets': {}, 'url': 'https://github.com/example/private-relay.git', 'revision': 'a' * 40}, + 'signing': {'assets': {}, 'url': 'https://github.com/example/public-signing.git', 'revision': 'b' * 40}, + })) + with patch.object(keeper, 'run', side_effect=[ + None, None, subprocess.CalledProcessError(128, ['git', 'fetch'])]) as command: + with self.assertRaisesRegex(ValueError, 'pinned public backend revision'): + keeper.prepare(only='signing') + self.assertEqual(command.call_count, 3) + self.assertIn('https://github.com/example/public-signing.git', command.call_args_list[1].args[0]) + self.assertEqual(list((self.here / '.sources').iterdir()), []) + + +if __name__ == '__main__': + unittest.main() diff --git a/dev/local-backend/verify-local.sh b/dev/local-backend/verify-local.sh new file mode 100755 index 0000000000..04dc216dfb --- /dev/null +++ b/dev/local-backend/verify-local.sh @@ -0,0 +1,3 @@ +#!/bin/sh +set -eu +exec python3 "$(dirname "$0")/verify.py" "$@" diff --git a/dev/local-backend/verify.py b/dev/local-backend/verify.py new file mode 100644 index 0000000000..e81932aaf6 --- /dev/null +++ b/dev/local-backend/verify.py @@ -0,0 +1,151 @@ +#!/usr/bin/env python3 +"""Exercise disposable local fixtures, never a hosted backend or real wallet.""" +import argparse +import base64 +import hashlib +import hmac +import json +import struct +import subprocess +import sys +import time +import urllib.error +import urllib.request +import uuid + +from keeper import compose, settings + + +def require(condition, description): + if not condition: + raise RuntimeError(description) + + +class NoRedirect(urllib.request.HTTPRedirectHandler): + def redirect_request(self, *args, **kwargs): + raise RuntimeError('Local check refused an HTTP redirect') + + +def request(port, path, data=None, expected=200): + req = urllib.request.Request(f'http://127.0.0.1:{port}{path}', + data=None if data is None else json.dumps(data).encode(), + headers={'Content-Type': 'application/json', 'appversion': '2.5.15', + 'os': 'ANDROID', 'HEXA-ID': 'keeper-local-only'}) + try: + response = urllib.request.build_opener(urllib.request.ProxyHandler({}), NoRedirect()).open(req, timeout=20) + except urllib.error.HTTPError as error: + response = error + with response: + statuses = expected if isinstance(expected, tuple) else (expected,) + require(response.code in statuses, f'{path}: expected HTTP {expected}, got {response.code}') + body = response.read().decode() + return body if path.startswith('/socket.io/') else json.loads(body) + + +def token(secret): + key = base64.b32decode(secret + '=' * (-len(secret) % 8)) + digest = hmac.new(key, struct.pack('>Q', int(time.time()) // 30), hashlib.sha1).digest() + offset = digest[-1] & 15 + return str((struct.unpack('>I', digest[offset:offset + 4])[0] & 0x7fffffff) % 1000000).zfill(6) + + +def health(relay, signing): + for port in (relay, signing): + result = request(port, '/health') + require(result.get('ready') is True and result.get('mode') == 'local' and + result.get('network') == 'TESTNET', 'Expected healthy local TESTNET service') + require(result['capabilities']['pushDelivery'] is False, 'Push must be disabled') + require(request(signing, '/health')['capabilities']['scheduledJobs'] is False, 'Scheduled jobs must be disabled') + print('PASS local/testnet health and disabled cloud capabilities') + + +def boundaries(): + cases = [('relay', 'BITCOIN_NETWORK=MAINNET', 'LOCAL_DEV requires'), + ('relay', 'DATABASE_URL=mongodb://example.invalid/keeper_local', 'LOCAL_DEV requires'), + ('signing', 'ENVIRONMENT=MAIN', 'Local signing requires'), + ('signing', 'LOCAL_DATABASE_URL=mongodb://example.invalid/keeper_signing_local', 'Local signing requires')] + for service, override, message in cases: + try: + compose('run', '--rm', '--no-deps', '-e', override, service, 'node', '-e', + "require('./dist/config')", capture_output=True, text=True) + except subprocess.CalledProcessError as error: + require(message in error.stdout + error.stderr, f'{service}: failed for an unexpected reason') + else: + raise RuntimeError(f'{service}: unsafe configuration was accepted') + print('PASS mainnet and hosted database configuration rejected') + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument('--persistence', action='store_true', help='Recreate this Compose stack, retaining volumes, and recheck fixtures') + parser.add_argument('--boundaries', action='store_true', help='Check startup rejection of mainnet and external databases') + args = parser.parse_args() + config = settings() + relay, channel, signing = (config[f'KEEPER_{key}_PORT'] for key in ('RELAY', 'CHANNEL', 'SIGNING')) + health(relay, signing) # Must pass before any mutations. + handshake = request(channel, '/socket.io/?EIO=4&transport=polling') + require(handshake.startswith('0') and json.loads(handshake[1:]).get('sid'), 'Socket.IO handshake failed') + print('PASS Socket.IO handshake') + unavailable = request(relay, '/local-unavailable-probe', {}, expected=503) + require(unavailable.get('error') == 'LOCAL_INTEGRATION_UNAVAILABLE', 'Unavailable route silently succeeded') + print('PASS unsupported integration fails explicitly') + fixture = 'contributor-smoke-' + uuid.uuid4().hex + created = request(relay, '/createNewApp', {'publicId': fixture, 'appID': fixture}) + require(created.get('created') is True, 'App record creation failed') + # Existing relay acknowledges creation before its app save callback completes. + # Poll the non-throwing subscription endpoint before retrieving the app image. + for attempt in range(20): + subscription = request(relay, '/getSubscriptionDetails', {'id': fixture, 'appID': fixture}) + if subscription.get('currentSubscription'): + break + time.sleep(0.25) + else: + raise RuntimeError('Created app did not become readable within 5 seconds') + app = request(relay, '/getAppImage', {'appId': fixture}) + require(app.get('appImage', {}).get('appId') == fixture and + app['appImage'].get('publicId') == fixture and app['appImage'].get('_id'), + 'Persisted app record round trip failed') + print('PASS relay app record create/read') + rejected = request(signing, '/v3/setupSigner', {'HEXA_ID': 'invalid'}, expected=400) + require(rejected.get('err') == 'Unauthorized request', 'Signing authorization failed') + result = request(signing, '/v3/setupSigner', {'HEXA_ID': 'keeper-local-only', 'policy': {'verification': {'method': 'TWO_FA'}, + 'restrictions': {'none': True, 'maxTransactionAmount': None, 'timeWindow': None}, + 'signingDelay': None}}) + require(result.get('setupSuccessful') is True, 'Signer setup failed') + data = result['setupData'] + require(data['bhXpub'].startswith('tpub'), 'Signer must use testnet public key') + secret = data['verification']['verifier'] # Disposable fixture; never print or write to source. + auth = {'HEXA_ID': 'keeper-local-only', 'id': data['id'], 'verificationToken': token(secret)} + # Pinned backend uses a save callback here too; wait only for record visibility. + for attempt in range(20): + result = request(signing, '/v3/validateSingerSetup', auth, expected=(200, 400)) + if result.get('valid') is True: + break + require(result.get('err', '').startswith('Singer not found'), 'Valid 2FA token rejected') + time.sleep(0.25) + auth['verificationToken'] = token(secret) + else: + raise RuntimeError('Created signer did not become readable within 5 seconds') + invalid = dict(auth, verificationToken='abcdef') + request(signing, '/v3/validateSingerSetup', invalid, expected=400) + print('PASS testnet signer setup, authorization and valid/invalid 2FA') + if args.persistence: + compose('down') + compose('up', '-d', '--wait', '--wait-timeout', '180') + health(relay, signing) + require(request(relay, '/getAppImage', {'appId': fixture}) == app, 'App data changed after recreation') + auth['verificationToken'] = token(secret) + restored = request(signing, '/v3/fetchSignerSetup', auth) + require(restored.get('valid') is True and restored.get('xpub') == data['bhXpub'], 'Signing identity changed after recreation') + print('PASS database and signing identity persist after container recreation') + if args.boundaries: + boundaries() + print('Local backend checks passed. Disposable records retained in this project\'s local volumes.') + + +if __name__ == '__main__': + try: + main() + except Exception as error: + print(f'FAIL: {error}', file=sys.stderr) + sys.exit(1) diff --git a/setup.sh b/setup.sh index 2013fb9bd3..3135bb8cbb 100755 --- a/setup.sh +++ b/setup.sh @@ -1,9 +1,6 @@ -# enabling node core modules -# adding node core modules support in react-native -rn-nodeify --install buffer,events,process,stream,inherits,path,assert,crypto --hack --yarn - -# ios dependency installation -cd ios && RCT_NEW_ARCH_ENABLED=1 pod install +#!/bin/sh +set -eu -# android SDK location configuration -cd ../android && touch local.properties && echo "sdk.dir = /Users/$(whoami)/Library/Android/sdk" >local.properties +# Yarn's prepare hook runs on Android-only machines too. Keep it platform neutral; +# CocoaPods and the Android SDK are configured explicitly in dev/local-backend/README.md. +rn-nodeify --install buffer,events,process,stream,inherits,path,assert,crypto --hack --yarn From fb2dc41ea2df5568de5b92606fd484e53858e3c1 Mon Sep 17 00:00:00 2001 From: Anant Date: Wed, 7 Oct 2026 09:00:52 +0530 Subject: [PATCH 02/15] Document shared sprint and release branch flow --- CONTRIBUTING.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 569fc61460..6fff79d405 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -56,6 +56,11 @@ not prerequisites for contributing. [Android](android/fastlane/README.md) and [iOS](ios/fastlane/README.md) release workflows separately from local development. +`sprint` is the shared integration branch. Maintainers may use a temporary +release branch while a specific app version is stabilized. Carry fixes made on +that branch back into `sprint` so the shared development line stays current; +then follow the reviewed `dev` to `main` release promotion used by the project. + For backend development, bootstrap creates ignored checkouts under `dev/local-backend/.sources/`. Save backend work in a branch/patch and submit it to the appropriate backend repository; an app PR does not include those ignored From cc3f16f01cb737b6e28375ffa90ce40a40b84547 Mon Sep 17 00:00:00 2001 From: Anant Date: Wed, 7 Oct 2026 17:10:48 +0530 Subject: [PATCH 03/15] Document Copilot triage and product signoff --- CONTRIBUTING.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6fff79d405..171c3812fd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -104,6 +104,13 @@ and test evidence. They may request revisions or additional tests, and decide whether a change is accepted. Only authorized maintainers merge and release official builds. Contributors do not need release permissions to participate. +Copilot code review is requested automatically for pull requests targeting +`sprint`. Read its actual comments and check each claim against the changed code +and relevant tests. Fix valid findings or explain why a comment does not apply +before requesting final human review. A developer's approval remains the code +review gate. The product owner may record product signoff in the PR discussion; +signoff from the PR author does not count as GitHub's required approval. + Some existing CI checks use maintainer-managed services or secrets. If a check is unavailable on a fork PR, report it in the PR so maintainers can arrange review; do not request production secrets or treat an unavailable check as passing. From c80b4e747314812616978347c5759ab18ff04a0d Mon Sep 17 00:00:00 2001 From: Anant Date: Wed, 7 Oct 2026 17:25:10 +0530 Subject: [PATCH 04/15] Address Copilot findings in public contributor bootstrap --- dev/local-backend/README.md | 4 ++-- .../adapters/relay/files/Dockerfile.local | 12 +++++++++++ dev/local-backend/keeper.py | 17 ++++++++++++---- dev/local-backend/sources.lock.json | 4 +++- dev/local-backend/test_keeper.py | 20 +++++++++++++++++++ 5 files changed, 50 insertions(+), 7 deletions(-) create mode 100644 dev/local-backend/adapters/relay/files/Dockerfile.local diff --git a/dev/local-backend/README.md b/dev/local-backend/README.md index 0968bf0885..f74eb4c29a 100644 --- a/dev/local-backend/README.md +++ b/dev/local-backend/README.md @@ -152,9 +152,9 @@ The relay health field `signing: false` describes the relay, not the separate si ## Sources, data and network boundaries -`sources.lock.json` pins both public backend revisions and the SigningServer adapter SHA-256 checksums. Relay's public source already includes local mode, so it needs no app-side adapter. The Node, Mongo and nginx base images are pinned by digest. Backend dependency installs use frozen Yarn / npm lockfiles; OS packages in the relay build still use Debian repositories, so this is a reproducible development workflow, not a bit-for-bit reproducible image build. +`sources.lock.json` pins both public backend revisions and all local adapter SHA-256 checksums. Relay's public source includes local mode; its local Dockerfile adapter pins the Node base image. The Node, Mongo and nginx base images are pinned by digest. Backend dependency installs use frozen Yarn / npm lockfiles; OS packages in the relay build still use Debian repositories, so this is a reproducible development workflow, not a bit-for-bit reproducible image build. -`adapters/signing/` contains the local-mode modifications for the pinned public SigningServer source. `.sources/` is generated and ignored. Bootstrap never overwrites an existing checkout; reruns preserve local backend edits. After editing a backend, rerun `up` to rebuild. To change pins/adapters, save your backend edits and move the generated checkout aside first. Do not deploy the development adapter to production. +`adapters/signing/` contains the local-mode modifications for the pinned public SigningServer source; `adapters/relay/` pins its local build image. `.sources/` is generated and ignored. Bootstrap never overwrites an existing checkout; reruns preserve local backend edits. After editing a backend, rerun `up` to rebuild. To change pins/adapters, save your backend edits and move the generated checkout aside first. Do not deploy the development adapters to production. Only the gateway publishes host ports, all on `127.0.0.1`. Mongo, relay and signing share an internal network with no external egress; the gateway also has a host-access network. Compose waits on service health, following [Docker's startup ordering](https://docs.docker.com/compose/how-tos/startup-order/). Build-time dependency downloads still use the internet. Mobile native integrations are outside Docker; this is not a fully offline mobile mode. diff --git a/dev/local-backend/adapters/relay/files/Dockerfile.local b/dev/local-backend/adapters/relay/files/Dockerfile.local new file mode 100644 index 0000000000..285e1e8e18 --- /dev/null +++ b/dev/local-backend/adapters/relay/files/Dockerfile.local @@ -0,0 +1,12 @@ +FROM node:22-bookworm-slim@sha256:43ac6c60b8f89723f746e8a92ce91abd5017e627ce1ddfe4238355d3a30b772c +WORKDIR /app +RUN apt-get update && apt-get install -y --no-install-recommends git ca-certificates python3 make g++ && rm -rf /var/lib/apt/lists/* +COPY package.json yarn.lock ./ +RUN yarn install --frozen-lockfile --non-interactive --ignore-scripts +COPY tsconfig.json ./ +COPY src ./src +COPY public ./public +RUN yarn compile +ENV NODE_ENV=development +USER node +CMD ["node", "dist/index.js"] diff --git a/dev/local-backend/keeper.py b/dev/local-backend/keeper.py index ffed894485..15dd7b245c 100644 --- a/dev/local-backend/keeper.py +++ b/dev/local-backend/keeper.py @@ -60,6 +60,12 @@ def prepare(only=None): if only is not None and name != only: continue adapter = HERE / 'adapters' / name + adapter_files = [path for path in adapter.rglob('*') if path.is_file() or path.is_symlink()] + if any(path.is_symlink() for path in adapter_files): + raise ValueError(f'{name}: adapter symlinks are not allowed') + actual_assets = {path.relative_to(adapter).as_posix() for path in adapter_files} + if actual_assets != set(spec['assets']): + raise ValueError(f'{name}: adapter file set does not match source lock') for asset, digest in spec['assets'].items(): if hashlib.sha256((adapter / asset).read_bytes()).hexdigest() != digest: raise ValueError(f'{name}: adapter checksum mismatch: {asset}') @@ -87,8 +93,9 @@ def prepare(only=None): 'No existing checkout was replaced.') from error run(['git', '-C', checkout, 'checkout', '--quiet', '--detach', spec['revision']]) if spec['assets']: - run(['git', '-C', checkout, 'apply', '--check', adapter / 'local.patch']) - run(['git', '-C', checkout, 'apply', adapter / 'local.patch']) + if (adapter / 'local.patch').exists(): + run(['git', '-C', checkout, 'apply', '--check', adapter / 'local.patch']) + run(['git', '-C', checkout, 'apply', adapter / 'local.patch']) for asset in (adapter / 'files').rglob('*'): if asset.is_file(): dest = checkout / asset.relative_to(adapter / 'files') @@ -101,8 +108,10 @@ def prepare(only=None): def app_env(): config = settings() template = (HERE / 'app.env.local.example').read_text() - for port, name in [('3000', 'RELAY'), ('4002', 'CHANNEL'), ('3003', 'SIGNING')]: - template = template.replace(f':{port}/', f':{config[f"KEEPER_{name}_PORT"]}/') + ports = {'3000': config['KEEPER_RELAY_PORT'], + '4002': config['KEEPER_CHANNEL_PORT'], + '3003': config['KEEPER_SIGNING_PORT']} + template = re.sub(r':(3000|4002|3003)/', lambda match: f':{ports[match.group(1)]}/', template) dest = APP / '.env.local' if dest.exists(): if dest.read_text() != template: diff --git a/dev/local-backend/sources.lock.json b/dev/local-backend/sources.lock.json index 231f141db1..863f3168b1 100644 --- a/dev/local-backend/sources.lock.json +++ b/dev/local-backend/sources.lock.json @@ -2,7 +2,9 @@ "relay": { "url": "https://github.com/KeeperCommunity/Relay.git", "revision": "3e1a01bd2fd5381d8546229922c431ce50bedad4", - "assets": {} + "assets": { + "files/Dockerfile.local": "6dde6c692430b1a91a10cdd82e6f1562023cc5974ffd4d4f58fe57fa1994407a" + } }, "signing": { "url": "https://github.com/KeeperCommunity/SigningServer.git", diff --git a/dev/local-backend/test_keeper.py b/dev/local-backend/test_keeper.py index 3c80fd9d0c..d8874ad721 100644 --- a/dev/local-backend/test_keeper.py +++ b/dev/local-backend/test_keeper.py @@ -36,6 +36,16 @@ def test_environment_is_exclusive_and_preserves_production(self): self.assertEqual((self.app / '.env.local').read_text(), 'developer-settings\n') self.assertEqual(production.read_text(), 'existing-production-sentinel\n') + def test_swapped_ports_do_not_rewrite_each_other(self): + (self.here / 'app.env.local.example').write_text( + 'RELAY=http://localhost:3000/\nCHANNEL=http://localhost:4002/\n' + 'SIGNING=http://localhost:3003/\n') + (self.here / '.env').write_text('KEEPER_RELAY_PORT=4002\nKEEPER_CHANNEL_PORT=3000\n') + keeper.app_env() + self.assertEqual((self.app / '.env.local').read_text(), + 'RELAY=http://localhost:4002/\nCHANNEL=http://localhost:3000/\n' + 'SIGNING=http://localhost:3003/\n') + def test_adapter_tampering_is_rejected_before_fetch(self): adapter = self.here / 'adapters/relay' adapter.mkdir(parents=True) @@ -47,6 +57,16 @@ def test_adapter_tampering_is_rejected_before_fetch(self): keeper.prepare() command.assert_not_called() + def test_unlisted_adapter_file_is_rejected_before_fetch(self): + adapter = self.here / 'adapters/relay/files' + adapter.mkdir(parents=True) + (adapter / 'unlisted.js').write_text('unexpected') + (self.here / 'sources.lock.json').write_text(json.dumps({'relay': {'assets': {}}})) + with patch.object(keeper, 'run') as command: + with self.assertRaisesRegex(ValueError, 'file set does not match'): + keeper.prepare() + command.assert_not_called() + def test_unknown_existing_checkout_is_not_overwritten(self): source = self.here / '.sources/relay' source.mkdir(parents=True) From 2214d589472f9e161f35b24cfb76d45dc208f30b Mon Sep 17 00:00:00 2001 From: Anant Date: Wed, 7 Oct 2026 17:30:40 +0530 Subject: [PATCH 05/15] Record product signoff separately from developer review --- .github/pull_request_template.md | 6 ++++++ CONTRIBUTING.md | 7 ++++--- 2 files changed, 10 insertions(+), 3 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 45f51ccc3d..91cd9f43e4 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -27,3 +27,9 @@ Target branch: Keeper maintainers own security review, acceptance, merging and official releases. Passing checks does not constitute approval. + +## Signoff + +- Copilot review findings: +- Developer approval: +- Product owner signoff: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 171c3812fd..473f17740f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -107,9 +107,10 @@ official builds. Contributors do not need release permissions to participate. Copilot code review is requested automatically for pull requests targeting `sprint`. Read its actual comments and check each claim against the changed code and relevant tests. Fix valid findings or explain why a comment does not apply -before requesting final human review. A developer's approval remains the code -review gate. The product owner may record product signoff in the PR discussion; -signoff from the PR author does not count as GitHub's required approval. +before requesting final human review. One developer approval remains the code +review gate. For changes to product behavior, UX, or copy, the product owner +records separate product signoff in the PR discussion. A PR author's product +signoff does not count as GitHub's required developer approval. Some existing CI checks use maintainer-managed services or secrets. If a check is unavailable on a fork PR, report it in the PR so maintainers can arrange review; From 90d2e24ecf6e4216f52db1d10d78a5cf24cf1e8c Mon Sep 17 00:00:00 2001 From: Anant Date: Wed, 7 Oct 2026 17:51:42 +0530 Subject: [PATCH 06/15] Request Ben and Utkarsh as sprint code owners --- .github/CODEOWNERS | 2 ++ CONTRIBUTING.md | 4 +++- 2 files changed, 5 insertions(+), 1 deletion(-) create mode 100644 .github/CODEOWNERS diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000000..3dbbb97c58 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,2 @@ +# Request both developers for changes targeting sprint; one approval is required. +* @ben-kaufman @cakesoft-utkarsh diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 473f17740f..2be9cd61d7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -108,7 +108,9 @@ Copilot code review is requested automatically for pull requests targeting `sprint`. Read its actual comments and check each claim against the changed code and relevant tests. Fix valid findings or explain why a comment does not apply before requesting final human review. One developer approval remains the code -review gate. For changes to product behavior, UX, or copy, the product owner +review gate. GitHub requests Ben and Utkarsh when a PR is ready for review; +either developer can provide that approval. For changes to product behavior, +UX, or copy, the product owner records separate product signoff in the PR discussion. A PR author's product signoff does not count as GitHub's required developer approval. From 934f71275d5306af3129c483dcc7948ac0271c42 Mon Sep 17 00:00:00 2001 From: Anant Date: Wed, 7 Oct 2026 18:01:33 +0530 Subject: [PATCH 07/15] Include Parsh in developer review requests --- .github/CODEOWNERS | 4 ++-- CONTRIBUTING.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 3dbbb97c58..f1f3d0d712 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1,2 +1,2 @@ -# Request both developers for changes targeting sprint; one approval is required. -* @ben-kaufman @cakesoft-utkarsh +# Request the three developers for changes targeting sprint; one approval is required. +* @ben-kaufman @cakesoft-utkarsh @Parsh diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2be9cd61d7..d7cec89098 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -108,8 +108,8 @@ Copilot code review is requested automatically for pull requests targeting `sprint`. Read its actual comments and check each claim against the changed code and relevant tests. Fix valid findings or explain why a comment does not apply before requesting final human review. One developer approval remains the code -review gate. GitHub requests Ben and Utkarsh when a PR is ready for review; -either developer can provide that approval. For changes to product behavior, +review gate. GitHub requests Ben, Utkarsh, and Parsh when a PR is ready for review; +any one can provide that approval. For changes to product behavior, UX, or copy, the product owner records separate product signoff in the PR discussion. A PR author's product signoff does not count as GitHub's required developer approval. From 4c5e3353371b15dca6c1c04aabf6dd17b5f84f5e Mon Sep 17 00:00:00 2001 From: Anant Date: Wed, 7 Oct 2026 18:33:14 +0530 Subject: [PATCH 08/15] Verify revisioned backups with audited public backend sources --- dev/local-backend/README.md | 4 +++- dev/local-backend/compose.yaml | 7 ++++--- dev/local-backend/sources.lock.json | 4 ++-- dev/local-backend/verify.py | 30 +++++++++++++++++++++++++++++ 4 files changed, 39 insertions(+), 6 deletions(-) diff --git a/dev/local-backend/README.md b/dev/local-backend/README.md index f74eb4c29a..a373452171 100644 --- a/dev/local-backend/README.md +++ b/dev/local-backend/README.md @@ -131,7 +131,7 @@ Skip `simctl boot` if already booted. Keep simulator signing enabled so the app ./dev/local-backend/verify-local.sh --persistence --boundaries ``` -This recreates only the selected Compose project's containers, retains its volumes, and compares the same app record and testnet signing public key. It also checks startup rejection of mainnet and hosted databases. Run when no other test is using that project. Ordinary `verify` does not restart containers. Every verify run adds a disposable app/signer fixture to the local database; no testnet coins are needed and no transaction is sent. Tokens and private keys are not printed. +This recreates only the selected Compose project's containers, retains its volumes, and compares the same app record, revisioned backup and testnet signing public key. It verifies backup snapshot reads, transactional repair and rejection of stale revisions, and checks startup rejection of mainnet and hosted databases. Run when no other test is using that project. Ordinary `verify` does not restart containers. Every verify run adds a disposable app/signer fixture and synthetic encrypted backup records to the local database; no testnet coins are needed and no transaction is sent. Tokens and private keys are not printed. For native smoke testing: launch the development app, complete onboarding with a disposable wallet, unlock, open Wallets and More Options, and select testnet before testing network functionality. An API smoke pass does not prove wallet backup/recovery or a real signing transaction. @@ -158,6 +158,8 @@ The relay health field `signing: false` describes the relay, not the separate si Only the gateway publishes host ports, all on `127.0.0.1`. Mongo, relay and signing share an internal network with no external egress; the gateway also has a host-access network. Compose waits on service health, following [Docker's startup ordering](https://docs.docker.com/compose/how-tos/startup-order/). Build-time dependency downloads still use the internet. Mobile native integrations are outside Docker; this is not a fully offline mobile mode. +Mongo starts as the single-member `keeper-local` replica set required by the backup API's transactions. Its idempotent health check initializes a new local volume and waits for a writable primary. Existing local data volumes are retained; a standalone Mongo server cannot exercise transactional backup repair. + Signing identities are randomly generated per signing volume and stored with restricted permissions. Use disposable test wallets. Keep the Mongo and signing volumes together: deleting signing keys invalidates their stored Server Key records. There is deliberately no automatic reset/delete command. `docker compose down --volumes` is destructive and not part of normal setup. Do not distribute databases, keys, email captures, `.env` files or native signing credentials with the source. ## Troubleshooting diff --git a/dev/local-backend/compose.yaml b/dev/local-backend/compose.yaml index e26754b4c7..be79d65d3a 100644 --- a/dev/local-backend/compose.yaml +++ b/dev/local-backend/compose.yaml @@ -2,11 +2,12 @@ name: ${COMPOSE_PROJECT_NAME:-keeper-contributor} services: mongo: image: mongo:7.0@sha256:9854f7139445d766a9523571d6f047530c45547460ffcf8259eb2bf4264632ca + command: [mongod, --replSet, keeper-local, --bind_ip_all] volumes: - mongo-data:/data/db networks: [local-only] healthcheck: - test: [CMD, mongosh, --quiet, --eval, "quit(db.adminCommand('ping').ok ? 0 : 1)"] + test: [CMD, mongosh, --quiet, --eval, "try { rs.status(); } catch (e) { if (e.code !== 94) throw e; rs.initiate({_id: 'keeper-local', members: [{_id: 0, host: 'mongo:27017'}]}); } quit(db.hello().isWritablePrimary ? 0 : 1)"] interval: 5s timeout: 5s retries: 20 @@ -19,7 +20,7 @@ services: ENVIRONMENT: DEVELOPMENT BITCOIN_NETWORK: TESTNET VERSION: local-development - DATABASE_URL: mongodb://mongo:27017/keeper_local + DATABASE_URL: mongodb://mongo:27017/keeper_local?replicaSet=keeper-local PORT: "3000" WS_PORT: "4002" HEXA_ID: keeper-local-only @@ -47,7 +48,7 @@ services: VERSION: local-development HEXA_ID: keeper-local-only BIT_ADMIN_KEY: keeper-local-admin-only - LOCAL_DATABASE_URL: mongodb://mongo:27017/keeper_signing_local + LOCAL_DATABASE_URL: mongodb://mongo:27017/keeper_signing_local?replicaSet=keeper-local RELAY: http://relay:3000/ MNEMONIC_IDENTIFIER_V2: local-signer-v2 MNEMONIC_IDENTIFIER_V3: local-signer-v3 diff --git a/dev/local-backend/sources.lock.json b/dev/local-backend/sources.lock.json index 863f3168b1..f9a926960d 100644 --- a/dev/local-backend/sources.lock.json +++ b/dev/local-backend/sources.lock.json @@ -1,14 +1,14 @@ { "relay": { "url": "https://github.com/KeeperCommunity/Relay.git", - "revision": "3e1a01bd2fd5381d8546229922c431ce50bedad4", + "revision": "af3248acb9548a6e03eb3d1ee13b2f24d8a47651", "assets": { "files/Dockerfile.local": "6dde6c692430b1a91a10cdd82e6f1562023cc5974ffd4d4f58fe57fa1994407a" } }, "signing": { "url": "https://github.com/KeeperCommunity/SigningServer.git", - "revision": "b82dc4f4a8f75676b70b12545d59c7906556a92b", + "revision": "3cc7728c27328e7b0358d1f91a32d8d13feba90a", "assets": { "files/.dockerignore": "78d9a1e03c57cfc1c7fb79ff2335aa2393bb075d0ac4a23feae81371728190be", "files/Dockerfile.local": "04a0bfca3903eb1363f8804b7c181424747c949aed543a89fe7a02316ccafa3d", diff --git a/dev/local-backend/verify.py b/dev/local-backend/verify.py index e81932aaf6..2595ba02eb 100644 --- a/dev/local-backend/verify.py +++ b/dev/local-backend/verify.py @@ -5,6 +5,7 @@ import hashlib import hmac import json +import re import struct import subprocess import sys @@ -75,6 +76,31 @@ def boundaries(): print('PASS mainnet and hosted database configuration rejected') +def backup_roundtrip(relay, fixture): + snapshot = request(relay, '/getBackupSnapshot', {'appId': fixture}) + require(snapshot.get('exists') is True and + re.fullmatch(r'[a-f0-9]{64}', snapshot.get('revision', '')), + 'Created app backup snapshot unavailable') + replacement = {'appId': fixture, 'publicId': fixture, 'version': '2.6.3', + 'expectedRevision': snapshot['revision'], + 'walletObject': {'qa': 'synthetic-encrypted-wallet'}, + 'signersObject': {}, 'vaultObject': {}, 'nodes': [], 'labels': []} + result = request(relay, '/repairAppBackup', replacement) + require(result.get('updated') is True, 'Revisioned backup repair failed') + repaired = request(relay, '/getBackupSnapshot', {'appId': fixture}) + require(repaired.get('revision') != snapshot['revision'] and + repaired.get('appImage', {}).get('wallets', {}).get('qa') == + replacement['walletObject']['qa'], 'Backup repair did not persist its image') + stale = dict(replacement, walletObject={'qa': 'stale-replacement-must-not-persist'}) + result = request(relay, '/repairAppBackup', stale, expected=409) + require(result.get('updated') is False and result.get('error') == 'BACKUP_CHANGED', + 'Stale backup revision was accepted') + require(request(relay, '/getBackupSnapshot', {'appId': fixture}) == repaired, + 'Rejected stale repair changed the backup') + print('PASS revisioned backup create/read and stale-revision preservation') + return repaired + + def main(): parser = argparse.ArgumentParser(description=__doc__) parser.add_argument('--persistence', action='store_true', help='Recreate this Compose stack, retaining volumes, and recheck fixtures') @@ -106,6 +132,8 @@ def main(): app['appImage'].get('publicId') == fixture and app['appImage'].get('_id'), 'Persisted app record round trip failed') print('PASS relay app record create/read') + backup = backup_roundtrip(relay, fixture) + app = request(relay, '/getAppImage', {'appId': fixture}) rejected = request(signing, '/v3/setupSigner', {'HEXA_ID': 'invalid'}, expected=400) require(rejected.get('err') == 'Unauthorized request', 'Signing authorization failed') result = request(signing, '/v3/setupSigner', {'HEXA_ID': 'keeper-local-only', 'policy': {'verification': {'method': 'TWO_FA'}, @@ -134,6 +162,8 @@ def main(): compose('up', '-d', '--wait', '--wait-timeout', '180') health(relay, signing) require(request(relay, '/getAppImage', {'appId': fixture}) == app, 'App data changed after recreation') + require(request(relay, '/getBackupSnapshot', {'appId': fixture}) == backup, + 'Revisioned backup changed after recreation') auth['verificationToken'] = token(secret) restored = request(signing, '/v3/fetchSignerSetup', auth) require(restored.get('valid') is True and restored.get('xpub') == data['bhXpub'], 'Signing identity changed after recreation') From 19e079ae4486dacf1f79bf5e527384e608872977 Mon Sep 17 00:00:00 2001 From: Anant Date: Wed, 7 Oct 2026 18:50:25 +0530 Subject: [PATCH 09/15] Check stale backup revisions after content restoration --- dev/local-backend/sources.lock.json | 2 +- dev/local-backend/verify.py | 20 +++++++++++++++++++- 2 files changed, 20 insertions(+), 2 deletions(-) diff --git a/dev/local-backend/sources.lock.json b/dev/local-backend/sources.lock.json index f9a926960d..5917d3086f 100644 --- a/dev/local-backend/sources.lock.json +++ b/dev/local-backend/sources.lock.json @@ -1,7 +1,7 @@ { "relay": { "url": "https://github.com/KeeperCommunity/Relay.git", - "revision": "af3248acb9548a6e03eb3d1ee13b2f24d8a47651", + "revision": "4c54e28738815546718775dbbdb39f0342c1b646", "assets": { "files/Dockerfile.local": "6dde6c692430b1a91a10cdd82e6f1562023cc5974ffd4d4f58fe57fa1994407a" } diff --git a/dev/local-backend/verify.py b/dev/local-backend/verify.py index 2595ba02eb..21a2c3a03c 100644 --- a/dev/local-backend/verify.py +++ b/dev/local-backend/verify.py @@ -98,7 +98,25 @@ def backup_roundtrip(relay, fixture): require(request(relay, '/getBackupSnapshot', {'appId': fixture}) == repaired, 'Rejected stale repair changed the backup') print('PASS revisioned backup create/read and stale-revision preservation') - return repaired + changed = dict(replacement, expectedRevision=repaired['revision'], + walletObject={'qa': 'second-synthetic-encrypted-wallet'}) + require(request(relay, '/repairAppBackup', changed).get('updated') is True, + 'Second disposable backup image was not saved') + second = request(relay, '/getBackupSnapshot', {'appId': fixture}) + restored = dict(replacement, expectedRevision=second['revision']) + require(request(relay, '/repairAppBackup', restored).get('updated') is True, + 'Restoring disposable backup content failed') + final = request(relay, '/getBackupSnapshot', {'appId': fixture}) + require(len({repaired['revision'], second['revision'], final['revision']}) == 3 and + final['appImage']['wallets'] == repaired['appImage']['wallets'], + 'A backup revision repeated after its content changed and returned') + obsolete = dict(changed, expectedRevision=repaired['revision']) + require(request(relay, '/repairAppBackup', obsolete, expected=409).get('error') == + 'BACKUP_CHANGED', 'An obsolete revision was accepted after content returned') + require(request(relay, '/getBackupSnapshot', {'appId': fixture}) == final, + 'Rejected obsolete repair changed the restored backup') + print('PASS restored content retains a new revision and rejects obsolete repairs') + return final def main(): From 1fab43c15ae5a2a3675d0cf5f7605474f25b04f2 Mon Sep 17 00:00:00 2001 From: Anant Date: Wed, 7 Oct 2026 19:03:43 +0530 Subject: [PATCH 10/15] Address contributor review findings and verify 2FA rejection --- .github/CODEOWNERS | 2 +- dev/local-backend/README.md | 2 +- dev/local-backend/VERIFICATION.md | 27 ++++++++++++++++++--------- dev/local-backend/keeper.py | 2 ++ dev/local-backend/test_keeper.py | 19 +++++++++++++++++++ dev/local-backend/verify.py | 11 +++++++++-- 6 files changed, 50 insertions(+), 13 deletions(-) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index f1f3d0d712..baadc36f3e 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1,2 +1,2 @@ -# Request the three developers for changes targeting sprint; one approval is required. +# Request the three developers for all changes; one approval is required. * @ben-kaufman @cakesoft-utkarsh @Parsh diff --git a/dev/local-backend/README.md b/dev/local-backend/README.md index a373452171..445707f9d3 100644 --- a/dev/local-backend/README.md +++ b/dev/local-backend/README.md @@ -70,7 +70,7 @@ app setup use the public Relay source. The JavaScript install hook only installs the repo's Node compatibility shims. Native dependencies are separate explicit steps below. It no longer runs CocoaPods on Android-only machines or rewrites `android/local.properties` with a Mac-specific path. -If default ports 3000/4002/3003 are occupied, copy `dev/local-backend/.env.example` to `dev/local-backend/.env`, set distinct ports and a unique project name, then run the commands above. Use the same settings for every invocation. Multiple copies using the same Compose project name share containers and volumes; give each independent environment a unique name. `.env.local` must match those ports. Commands work from any directory except the native/Yarn commands, which assume the app root. +If default ports 3000/4002/3003 are occupied, copy `dev/local-backend/.env.example` to `dev/local-backend/.env`, set distinct ports and a unique project name, then run the commands above. Port 8081 is reserved for Metro and cannot be assigned to a backend service. Use the same settings for every invocation. Multiple copies using the same Compose project name share containers and volumes; give each independent environment a unique name. `.env.local` must match those ports. Commands work from any directory except the native/Yarn commands, which assume the app root. ## Android diff --git a/dev/local-backend/VERIFICATION.md b/dev/local-backend/VERIFICATION.md index 1205569afc..0283aeac80 100644 --- a/dev/local-backend/VERIFICATION.md +++ b/dev/local-backend/VERIFICATION.md @@ -2,15 +2,24 @@ ## Sprint contributor package — 7 October 2026 -This focused `sprint` contributor package uses the same public backend pins and -adapter digests as the earlier sprint PR #7014 and main PR #7026. It changes the -developer setup hook and adds contributor/security documentation and a -public-backend CI workflow; it does not modify mobile, dependency or release -files. Backend/bootstrap verification for this exact branch is recorded with -its PR checks. Native app builds must be assessed against the selected app -branch and platform separately. -The dated sections below preserve earlier sprint and public-source evidence; -historical private-source failures are not the current public backend result. +The current contributor package pins public Relay +`4c54e28738815546718775dbbdb39f0342c1b646` and public SigningServer +`3cc7728c27328e7b0358d1f91a32d8d13feba90a`, with local adapter checksums in +`sources.lock.json`. These are newer revisions than the earlier sprint PR #7014 +and main PR #7026. The source locks include Relay snapshot/repair and revision +guards, compatible SigningServer dependency fixes, and digest-pinned image adapters. + +At app commit `19e079ae4486dacf1f79bf5e527384e608872977`, the +[public-backend CI](https://github.com/KeeperCommunity/bitcoin-keeper/actions/runs/37627727798) +passed both the SigningServer adapter and full local backend/bootstrap jobs. +Those checks used these backend pins and exercised local snapshot/repair, +A → B → A revisions, stale-repair rejection and persistence. Subsequent contributor +changes have their own PR check results. Native app builds must be assessed +against the selected app branch and platform separately. + +All dated sections below are historical evidence for the exact revisions named +in those sections. They do not verify the current pins or attribute earlier +private-source failures to the current public backend. ## Public Relay transition — 7 October 2026 diff --git a/dev/local-backend/keeper.py b/dev/local-backend/keeper.py index 15dd7b245c..fbb93a8dca 100644 --- a/dev/local-backend/keeper.py +++ b/dev/local-backend/keeper.py @@ -41,6 +41,8 @@ def settings(): if not re.fullmatch(r'[a-z0-9][a-z0-9_-]*', values['COMPOSE_PROJECT_NAME']): raise ValueError('COMPOSE_PROJECT_NAME must contain lowercase letters, digits, _ or -') ports = [int(values[k]) for k in defaults if k.endswith('_PORT')] + if 8081 in ports: + raise ValueError('Port 8081 is reserved for Metro; choose another backend port') if len(set(ports)) != 3 or any(p < 1024 or p > 65535 for p in ports): raise ValueError('Choose three distinct ports between 1024 and 65535') return {k: values[k] for k in defaults} diff --git a/dev/local-backend/test_keeper.py b/dev/local-backend/test_keeper.py index d8874ad721..c401eedeed 100644 --- a/dev/local-backend/test_keeper.py +++ b/dev/local-backend/test_keeper.py @@ -8,6 +8,7 @@ from unittest.mock import patch import keeper +import verify class PreserveDeveloperWork(unittest.TestCase): @@ -84,6 +85,24 @@ def test_port_collision_is_rejected(self): with self.assertRaisesRegex(ValueError, 'distinct ports'): keeper.settings() + def test_metro_port_is_reserved_for_each_backend_service(self): + for service in ('RELAY', 'CHANNEL', 'SIGNING'): + with self.subTest(service=service): + (self.here / '.env').write_text(f'KEEPER_{service}_PORT=8081\n') + with self.assertRaisesRegex(ValueError, 'reserved for Metro'): + keeper.settings() + + def test_invalid_two_fa_requires_the_pinned_token_failure(self): + with patch.object(verify, 'request', return_value={ + 'err': 'Validation failed: verification token is either invalid or has expired'}): + verify.verify_invalid_two_fa('3003', {'id': 'disposable-signer'}) + for unrelated in ({'err': 'Unauthorized request'}, {'err': 'Invalid request schema'}, + {'valid': False}, {'valid': True}): + with self.subTest(response=unrelated): + with patch.object(verify, 'request', return_value=unrelated): + with self.assertRaisesRegex(RuntimeError, 'unrelated error'): + verify.verify_invalid_two_fa('3003', {'id': 'disposable-signer'}) + def test_fetch_failure_explains_public_revision_and_cleans_temporary_checkout(self): (self.here / 'sources.lock.json').write_text(json.dumps({'relay': { 'assets': {}, 'url': 'https://github.com/example/private-backend.git', diff --git a/dev/local-backend/verify.py b/dev/local-backend/verify.py index 21a2c3a03c..00922ffea3 100644 --- a/dev/local-backend/verify.py +++ b/dev/local-backend/verify.py @@ -119,6 +119,14 @@ def backup_roundtrip(relay, fixture): return final +def verify_invalid_two_fa(signing, auth): + rejected = request(signing, '/v3/validateSingerSetup', + dict(auth, verificationToken='abcdef'), expected=400) + require(rejected.get('err') == + 'Validation failed: verification token is either invalid or has expired', + 'Invalid 2FA check returned an unrelated error') + + def main(): parser = argparse.ArgumentParser(description=__doc__) parser.add_argument('--persistence', action='store_true', help='Recreate this Compose stack, retaining volumes, and recheck fixtures') @@ -172,8 +180,7 @@ def main(): auth['verificationToken'] = token(secret) else: raise RuntimeError('Created signer did not become readable within 5 seconds') - invalid = dict(auth, verificationToken='abcdef') - request(signing, '/v3/validateSingerSetup', invalid, expected=400) + verify_invalid_two_fa(signing, auth) print('PASS testnet signer setup, authorization and valid/invalid 2FA') if args.persistence: compose('down') From b39b0a173b9021a31479e8c29fe858d4130beb7b Mon Sep 17 00:00:00 2001 From: Anant Date: Wed, 7 Oct 2026 19:14:25 +0530 Subject: [PATCH 11/15] Complete contributor setup docs and symlink integrity coverage --- Readme.md | 4 +++- dev/local-backend/VERIFICATION.md | 13 +++++++------ dev/local-backend/test_keeper.py | 15 +++++++++++++++ 3 files changed, 25 insertions(+), 7 deletions(-) diff --git a/Readme.md b/Readme.md index 70ed94e5c0..0db9aef789 100644 --- a/Readme.md +++ b/Readme.md @@ -55,7 +55,9 @@ Refer to platform-specific documentation for detailed setup requirements. cd bitcoin-keeper ``` 3. Install the project dependencies using Yarn: - The prepare scripts will automatically install pods and nodify crypto-related packages for react-native + The prepare script configures the crypto-related React Native packages. + CocoaPods is an explicit iOS setup step; follow [CONTRIBUTING.md](CONTRIBUTING.md) + after dependency installation. ```shell yarn install ``` diff --git a/dev/local-backend/VERIFICATION.md b/dev/local-backend/VERIFICATION.md index 0283aeac80..559fe2f687 100644 --- a/dev/local-backend/VERIFICATION.md +++ b/dev/local-backend/VERIFICATION.md @@ -89,8 +89,8 @@ private-source failures to the current public backend. - Removed the public contributor-access issue template. Access instructions now use private intake/internal tracking, matching the owner's policy. Added `HANDOFF.md` for independent-machine setup and separate pass/fail/untested reports. -- Five bootstrap regression tests, strict contributor OpenSpec validation, ten - local documentation links and diff whitespace checks: PASS. +- Five bootstrap regression tests, ten local documentation links and diff + whitespace checks: PASS. - Restarted this Mac's existing Colima profile and ran the documented `dev up` against the same pinned sources, existing disposable project/volumes and build caches. Health, Socket.IO, explicit unsupported-route failure, app create/read @@ -130,8 +130,8 @@ GitHub read access reused. Project `keeper-readiness-proof` used ports - V3 testnet Server Key setup, authorization and valid/invalid 2FA: PASS. - Container recreation preserves the same app record and derived signer public key: PASS. Mainnet/hosted database startup rejection: PASS. -- Five bootstrap regression tests: PASS. Active contributor OpenSpec validation: - PASS. Both backend test jobs and current-source scans pass in their own CI; +- Five bootstrap regression tests: PASS. Both backend test jobs and + current-source scans pass in their own CI; their history scans remain failing, tracked privately. - Updated native development builds: iOS PASS after replacing a stale local Node path; Android PASS after selecting the installed JDK 17 (976 tasks, 58 @@ -256,7 +256,6 @@ Apple Silicon Mac, macOS 26.6.2, Xcode 26.4/iOS 26.4 simulator, Node 25.9.0, Yar | iOS More Options | PASS, simulator navigation and screenshot inspected | | Node/Mongo/nginx pinned image manifests | PASS, each includes Linux amd64 and arm64 | | Existing release version consistency | PASS, unchanged 2.5.15 / Android 622 / iOS 615 | -| Strict OpenSpec validation | PASS | Native apps use a separate Metro process on port 8082 during this acceptance run, preserving the existing developer's Metro on 8081. Android's dev-server host is set to localhost with device port 8081 forwarded to host 8082. Ordinary single-checkout instructions use port 8081. @@ -272,11 +271,13 @@ Native apps use a separate Metro process on port 8082 during this acceptance run ## Reproduce checks +The earlier contributor OpenSpec change is not included in this checkout. Its +validation is not a reproducible acceptance check for this source package. + ```sh ./dev/local-backend/dev up ./dev/local-backend/verify-local.sh --persistence --boundaries python3 -B -m unittest discover -s dev/local-backend -p test_keeper.py -npx --no-install openspec validate package-contributor-development --strict ``` The acceptance logs and emulator fixtures remain on the maintainer's machine outside the source package. Do not include local databases, generated signing identities, recovery material or captured emails in a source review or handoff archive. diff --git a/dev/local-backend/test_keeper.py b/dev/local-backend/test_keeper.py index c401eedeed..b5bc059b51 100644 --- a/dev/local-backend/test_keeper.py +++ b/dev/local-backend/test_keeper.py @@ -68,6 +68,21 @@ def test_unlisted_adapter_file_is_rejected_before_fetch(self): keeper.prepare() command.assert_not_called() + def test_adapter_symlinks_are_rejected_before_fetch_even_when_listed(self): + adapter = self.here / 'adapters/relay/files' + adapter.mkdir(parents=True) + target = self.app / 'outside-adapter.js' + target.write_text('fixture') + (adapter / 'link.js').symlink_to(target) + for assets in ({}, {'files/link.js': hashlib.sha256(b'fixture').hexdigest()}): + with self.subTest(listed=bool(assets)): + (self.here / 'sources.lock.json').write_text(json.dumps({ + 'relay': {'assets': assets}})) + with patch.object(keeper, 'run') as command: + with self.assertRaisesRegex(ValueError, 'symlinks are not allowed'): + keeper.prepare() + command.assert_not_called() + def test_unknown_existing_checkout_is_not_overwritten(self): source = self.here / '.sources/relay' source.mkdir(parents=True) From 2ec20264f5486c7ce4ba657bf8250ce60f458817 Mon Sep 17 00:00:00 2001 From: Anant Date: Thu, 8 Oct 2026 17:47:47 +0530 Subject: [PATCH 12/15] Remove private backend revision IDs from public verification history --- dev/local-backend/VERIFICATION.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/dev/local-backend/VERIFICATION.md b/dev/local-backend/VERIFICATION.md index 559fe2f687..44a0d18ebe 100644 --- a/dev/local-backend/VERIFICATION.md +++ b/dev/local-backend/VERIFICATION.md @@ -118,10 +118,10 @@ Detailed findings remain private. ## Fresh backend readiness integration -Updated pins: relay `5f59876b43fba1be9091657a6bf3389ce43831d0`, signing -`5ad45119ab014ea58efecabd54702b488d8fd254`. New app worktree, newly fetched -backend sources and new Docker volumes; host image/package caches and existing -GitHub read access reused. Project `keeper-readiness-proof` used ports +This earlier private-backend readiness run used private Relay and SigningServer +revisions, separate from the current public source pins. New app worktree, newly +fetched backend sources and new Docker volumes; host image/package caches and +existing GitHub read access reused. Project `keeper-readiness-proof` used ports 23000/24002/23003, preserving other development projects. - Source fetch, adapter checksums/application and container builds: PASS. From 9c66b3527fa23b8bf20ea7164b06c771b9ba17a6 Mon Sep 17 00:00:00 2001 From: Anant Date: Fri, 9 Oct 2026 15:04:11 +0530 Subject: [PATCH 13/15] Pin Relay signer-map cleanup for public contributor setup --- dev/local-backend/VERIFICATION.md | 26 +++++++++++++++++++++++--- dev/local-backend/sources.lock.json | 2 +- 2 files changed, 24 insertions(+), 4 deletions(-) diff --git a/dev/local-backend/VERIFICATION.md b/dev/local-backend/VERIFICATION.md index 44a0d18ebe..7222bc86af 100644 --- a/dev/local-backend/VERIFICATION.md +++ b/dev/local-backend/VERIFICATION.md @@ -1,8 +1,28 @@ # Contributor setup verification +## R4 public Relay repin — 9 October 2026 + +The current source lock pins public Relay +`fb93c887631a6f567155a88f8e93d566f9d32a53` and public SigningServer +`3cc7728c27328e7b0358d1f91a32d8d13feba90a`. Compared with the previous +Relay pin, the follow-up changes signer lookup cleanup and its regression tests; +it does not change the mobile backup request or response shape or the app's local +Dockerfile adapter. Relay's exact-head build, disposable backup tests and source +scans passed in [PR #3](https://github.com/KeeperCommunity/Relay/pull/3). + +In the existing anonymous app checkout, with an isolated HOME, disabled +system/global Git configuration and interactive credential prompts, +`dev prepare` fetched the new Relay commit and applied the unchanged adapter. +It preserved the prepared public +SigningServer checkout. All 11 bootstrap fixtures and Compose configuration +validation passed. No local Docker build or native app run was repeated for this +new pin. The earlier full-stack acceptance in +[app PR #7030](https://github.com/KeeperCommunity/bitcoin-keeper/pull/7030) +used the previous Relay pin and is historical evidence for that revision. + ## Sprint contributor package — 7 October 2026 -The current contributor package pins public Relay +That sprint contributor package pinned public Relay `4c54e28738815546718775dbbdb39f0342c1b646` and public SigningServer `3cc7728c27328e7b0358d1f91a32d8d13feba90a`, with local adapter checksums in `sources.lock.json`. These are newer revisions than the earlier sprint PR #7014 @@ -18,8 +38,8 @@ changes have their own PR check results. Native app builds must be assessed against the selected app branch and platform separately. All dated sections below are historical evidence for the exact revisions named -in those sections. They do not verify the current pins or attribute earlier -private-source failures to the current public backend. +in those sections. They do not verify the 9 October source lock or attribute +earlier private-source failures to the current public backend. ## Public Relay transition — 7 October 2026 diff --git a/dev/local-backend/sources.lock.json b/dev/local-backend/sources.lock.json index 5917d3086f..420e19371b 100644 --- a/dev/local-backend/sources.lock.json +++ b/dev/local-backend/sources.lock.json @@ -1,7 +1,7 @@ { "relay": { "url": "https://github.com/KeeperCommunity/Relay.git", - "revision": "4c54e28738815546718775dbbdb39f0342c1b646", + "revision": "fb93c887631a6f567155a88f8e93d566f9d32a53", "assets": { "files/Dockerfile.local": "6dde6c692430b1a91a10cdd82e6f1562023cc5974ffd4d4f58fe57fa1994407a" } From ce2972b85ba8cd405b60ada06de00d6bd800bbef Mon Sep 17 00:00:00 2001 From: Anant Date: Fri, 9 Oct 2026 16:31:53 +0530 Subject: [PATCH 14/15] test: make Electrum suites deterministic for contributors --- dev/local-backend/sources.lock.json | 2 +- tests/services/client.test.ts | 145 +++++++++++++++++------- tests/services/electrumWalletFixture.ts | 79 +++++++++++++ tests/services/vault.test.ts | 9 ++ tests/services/wallet.test.ts | 5 + tsconfig.json | 2 +- 6 files changed, 200 insertions(+), 42 deletions(-) create mode 100644 tests/services/electrumWalletFixture.ts diff --git a/dev/local-backend/sources.lock.json b/dev/local-backend/sources.lock.json index 420e19371b..4d5d02b531 100644 --- a/dev/local-backend/sources.lock.json +++ b/dev/local-backend/sources.lock.json @@ -1,7 +1,7 @@ { "relay": { "url": "https://github.com/KeeperCommunity/Relay.git", - "revision": "fb93c887631a6f567155a88f8e93d566f9d32a53", + "revision": "ee935359f22ff7932ea0a62e9084d4b49801f4aa", "assets": { "files/Dockerfile.local": "6dde6c692430b1a91a10cdd82e6f1562023cc5974ffd4d4f58fe57fa1994407a" } diff --git a/tests/services/client.test.ts b/tests/services/client.test.ts index 7b1381530b..8a41f58689 100644 --- a/tests/services/client.test.ts +++ b/tests/services/client.test.ts @@ -3,24 +3,88 @@ import ElectrumClient from '../../src/services/electrum/client'; import { predefinedTestnetNodes } from '../../src/services/electrum/predefinedNodes'; import * as bitcoinJS from 'bitcoinjs-lib'; +const mockClients: any[] = []; +const mockTxid = '24913105c497b4bb4ccf81b03857c8306aba0e58ccde792d981f6c18efdb24b8'; + +// Exercise the real ElectrumClient facade against deterministic protocol replies. +// A public Electrum server is outside the control of CI. +jest.mock('electrum-client', () => ({ + __esModule: true, + default: jest.fn().mockImplementation((_net, _tls, _port, host) => { + const client = { + host, + initElectrum: jest.fn(async () => { + if (host === 'blackie.c3-soft.com') { + throw new Error('connect ECONNREFUSED 127.0.0.1:50002'); + } + return ['fixture-server', '1.4']; + }), + close: jest.fn(), + onError: null, + server_ping: jest.fn(async () => undefined), + server_features: jest.fn(async () => ({ + server_version: 'fixture-server', + protocol_min: '1.4', + protocol_max: '1.4.3', + })), + blockchainScripthash_listunspentBatch: jest.fn(async (hashes) => + hashes.map((param, index) => ({ + param, + result: index === 0 ? [{ tx_hash: mockTxid, tx_pos: 1, value: 12345, height: 100 }] : [], + })) + ), + blockchainScripthash_getHistoryBatch: jest.fn(async (hashes) => + hashes.map((param, index) => ({ + param, + result: index === 0 ? [{ tx_hash: mockTxid, height: 100 }] : [], + })) + ), + blockchainEstimatefee: jest.fn(async () => 0.00002), + blockchainTransaction_getBatch: jest.fn(async (txids) => + txids.map((param) => ({ + param, + result: { + txid: param, + hex: 'fixture-hex', + vout: [{ scriptPubKey: { address: 'tb1qfixture' } }], + }, + })) + ), + }; + mockClients.push(client); + return client; + }), +})); + jest.mock('src/store/store', () => ({ store: { getState: () => ({ - settings: { - bitcoinNetwork: 'testnet', - }, + settings: { bitcoinNetworkType: 'TESTNET' }, }), }, })); -beforeAll(async () => { - try { - ElectrumClient.setActivePeer(predefinedTestnetNodes); - await ElectrumClient.connect(); - } catch (err) { - console.log('failed to connect to Electrum:', err); - process.exit(1); - } +const onlineNode = { + ...predefinedTestnetNodes[0], + id: 337, + host: 'electrum-fixture.test', + isConnected: true, +}; +const offlineNode = { + ...predefinedTestnetNodes[0], + isConnected: true, +}; +const addresses = [ + 'tb1qd2u9tvuqzadgeh02vppd33e7u2fatuwrw7h4q5', + 'tb1qwdm8hdyvv5jn05qq858lgnk50heucvxvqtl4sx', +]; + +beforeEach(async () => { + mockClients.length = 0; + ElectrumClient.setActivePeer([onlineNode], onlineNode); + ElectrumClient.resetCurrentPeerIndex(); + const connection = await ElectrumClient.connect(); + assert.ok(connection.connected); }); afterAll(() => { @@ -30,23 +94,25 @@ afterAll(() => { describe('ElectrumClient', () => { describe('Connection Tests', () => { it('should test connection successfully', async () => { - const result = await ElectrumClient.testConnection(predefinedTestnetNodes[0]); + const result = await ElectrumClient.testConnection(onlineNode); assert.ok(result.connected); }); it('should fail connection when node is unreachable', async () => { - const unreachableNode = { ...predefinedTestnetNodes[0], host: 'invalid.host' }; - const result = await ElectrumClient.testConnection(unreachableNode); + const result = await ElectrumClient.testConnection(offlineNode); assert.ok(!result.connected); assert.ok(result.error); + assert.strictEqual(result.errorType, 'network'); }); it('should reconnect to the next peer when connection fails', async () => { - ElectrumClient.setActivePeer(predefinedTestnetNodes); - ElectrumClient.forceDisconnect(); - const result = await ElectrumClient.reconnect(); + ElectrumClient.setActivePeer([offlineNode, onlineNode], offlineNode); + ElectrumClient.resetCurrentPeerIndex(); + const result = await ElectrumClient.connect(); assert.ok(result.connected); - assert.ok(result.connectedTo); + assert.strictEqual(result.connectedTo, onlineNode.host); + assert.strictEqual(ElectrumClient.getActivePeer()?.host, onlineNode.host); + assert.ok(mockClients.some((client) => client.host === offlineNode.host)); }); }); @@ -60,51 +126,50 @@ describe('ElectrumClient', () => { describe('Feature Tests', () => { it('should retrieve server features', async () => { const features = await ElectrumClient.serverFeatures(); - assert.ok(features.server_version); - assert.ok(features.protocol_min); - assert.ok(features.protocol_max); + assert.strictEqual(features.server_version, 'fixture-server'); + assert.strictEqual(features.protocol_min, '1.4'); + assert.strictEqual(features.protocol_max, '1.4.3'); }); }); describe('UTXO and History Tests', () => { it('should sync UTXOs by address', async () => { - const addresses = [ - 'tb1qd2u9tvuqzadgeh02vppd33e7u2fatuwrw7h4q5', - 'tb1qwdm8hdyvv5jn05qq858lgnk50heucvxvqtl4sx', - ]; const utxos = await ElectrumClient.syncUTXOByAddress(addresses, bitcoinJS.networks.testnet); - assert.ok(Object.keys(utxos).length > 0); + assert.deepStrictEqual(utxos[addresses[0]], [ + { txId: mockTxid, vout: 1, value: 12345, height: 100, address: addresses[0] }, + ]); + assert.deepStrictEqual(utxos[addresses[1]], []); }); it('should sync history by address', async () => { - const addresses = [ - 'tb1qd2u9tvuqzadgeh02vppd33e7u2fatuwrw7h4q5', - 'tb1qwdm8hdyvv5jn05qq858lgnk50heucvxvqtl4sx', - ]; const history = await ElectrumClient.syncHistoryByAddress( addresses, bitcoinJS.networks.testnet ); - assert.ok(Object.keys(history.historyByAddress).length > 0); - assert.ok(history.txids.length > 0); + assert.deepStrictEqual(history.historyByAddress[addresses[0]], [ + { tx_hash: mockTxid, height: 100 }, + ]); + assert.deepStrictEqual(history.historyByAddress[addresses[1]], []); + assert.deepStrictEqual(history.txids, [mockTxid]); + assert.strictEqual(history.txidToAddress[mockTxid], addresses[0]); }); }); describe('Transaction Tests', () => { it('should estimate fee', async () => { const fee = await ElectrumClient.estimateFee(1); - assert.ok(fee > 0); + assert.strictEqual(fee, 2); }); it('should fetch transactions by ID', async () => { - const txids = [ - '24913105c497b4bb4ccf81b03857c8306aba0e58ccde792d981f6c18efdb24b8', - '9a15008af30580039bc7a07d36c3544902a2e1618ad31f4dda94fe0044a8dcce', - ]; + const txids = [mockTxid, '9a15008af30580039bc7a07d36c3544902a2e1618ad31f4dda94fe0044a8dcce']; const transactions = await ElectrumClient.getTransactionsById(txids); - assert.ok(Object.keys(transactions).length === txids.length); - assert.deepStrictEqual(transactions[txids[0]].txid, txids[0]); - assert.deepStrictEqual(transactions[txids[1]].txid, txids[1]); + assert.deepStrictEqual(Object.keys(transactions), txids); + for (const txid of txids) { + assert.strictEqual(transactions[txid].txid, txid); + assert.strictEqual(transactions[txid].hex, undefined); + assert.deepStrictEqual(transactions[txid].vout[0].scriptPubKey.addresses, ['tb1qfixture']); + } }); }); }); diff --git a/tests/services/electrumWalletFixture.ts b/tests/services/electrumWalletFixture.ts new file mode 100644 index 0000000000..466523c6ed --- /dev/null +++ b/tests/services/electrumWalletFixture.ts @@ -0,0 +1,79 @@ +import ElectrumClient from 'src/services/electrum/client'; +import WalletOperations from 'src/services/wallets/operations'; + +const fundingTxid = '608710eb040d935dedb6c4d6321369382b2bd45533a7442a6fa98add3860d46b'; +const previousTxid = '89b193b61f7681ee588939932219f3d92e54a1873a9fb823647038f3879fba00'; +const externalAddress = 'tb1ql7w62elx9ucw4pj5lgw4l028hmuw80sndtntxt'; + +// The wallet and vault suites exercise address scanning, transaction parsing, coin selection, +// and PSBT signing. Give each generated wallet one funded testnet address without using a +// public Electrum server or a mutable public wallet balance. +export const installElectrumWalletFixture = () => { + let fundedAddress: string | null = null; + const syncWallets = WalletOperations.syncWalletsViaElectrumClient; + + jest.spyOn(WalletOperations, 'syncWalletsViaElectrumClient').mockImplementation((...args) => { + fundedAddress = null; + return syncWallets(...args); + }); + jest.spyOn(WalletOperations, 'fetchFeeRatesByPriority').mockImplementation(async () => + WalletOperations.mockFeeRates() + ); + + jest.spyOn(ElectrumClient, 'setActivePeer').mockImplementation(() => undefined); + jest.spyOn(ElectrumClient, 'connect').mockResolvedValue({ + connected: true, + connectedTo: 'fixture.electrum.test', + }); + jest.spyOn(ElectrumClient, 'forceDisconnect').mockImplementation(() => undefined); + jest.spyOn(ElectrumClient, 'getBlockchainHeaders').mockResolvedValue({ height: 85172, hex: '00' }); + jest.spyOn(ElectrumClient, 'syncUTXOByAddress').mockImplementation(async (addresses) => { + if (!fundedAddress) fundedAddress = addresses[0]; + return Object.fromEntries( + addresses.map((address) => [ + address, + address === fundedAddress + ? [{ txId: fundingTxid, vout: 1, value: 6000, height: 85000, address }] + : [], + ]) + ); + }); + jest.spyOn(ElectrumClient, 'syncHistoryByAddress').mockImplementation(async (addresses) => { + const hasFunding = addresses.includes(fundedAddress); + return { + historyByAddress: Object.fromEntries( + addresses.map((address) => [ + address, + hasFunding && address === fundedAddress ? [{ tx_hash: fundingTxid, height: 85000 }] : [], + ]) + ), + txids: hasFunding ? [fundingTxid] : [], + txidToAddress: hasFunding ? { [fundingTxid]: fundedAddress } : {}, + }; + }); + jest.spyOn(ElectrumClient, 'getTransactionsById').mockImplementation(async (txids) => { + const transactions: Record = {}; + for (const txid of txids) { + if (txid === fundingTxid) { + transactions[txid] = { + txid, + vin: [{ txid: previousTxid, vout: 0 }], + vout: [ + { value: 0.00001, scriptPubKey: { addresses: [externalAddress] } }, + { value: 0.00006, scriptPubKey: { addresses: [fundedAddress] } }, + ], + confirmations: 12, + time: 1700000000, + blocktime: 1700000000, + }; + } else if (txid === previousTxid) { + transactions[txid] = { + txid, + vin: [], + vout: [{ value: 0.0001, scriptPubKey: { addresses: [externalAddress] } }], + }; + } + } + return transactions; + }); +}; diff --git a/tests/services/vault.test.ts b/tests/services/vault.test.ts index ed6cf6f13b..7b102a7917 100644 --- a/tests/services/vault.test.ts +++ b/tests/services/vault.test.ts @@ -43,6 +43,7 @@ import { generateOutputDescriptors, parseTextforVaultConfig, } from 'src/utils/service-utilities/utils'; +import { installElectrumWalletFixture } from './electrumWalletFixture'; jest.mock('src/store/store', () => ({ store: { @@ -56,6 +57,10 @@ jest.mock('src/store/store', () => ({ jest.mock('realm', () => ({})); +beforeAll(() => { + installElectrumWalletFixture(); +}); + const connectToElectrumClient = async () => { try { ElectrumClient.setActivePeer(predefinedTestnetNodes); @@ -67,6 +72,10 @@ const connectToElectrumClient = async () => { } }; +afterAll(() => { + ElectrumClient.forceDisconnect(); +}); + describe('Vault: Single-Sig(1-of-1)', () => { let primaryMnemonic: string; let vault: Vault; diff --git a/tests/services/wallet.test.ts b/tests/services/wallet.test.ts index dc92142d4f..b366993e46 100644 --- a/tests/services/wallet.test.ts +++ b/tests/services/wallet.test.ts @@ -12,6 +12,7 @@ import { TransactionPrerequisite, } from 'src/services/wallets/interfaces'; import { Wallet } from 'src/services/wallets/interfaces/wallet'; +import { installElectrumWalletFixture } from './electrumWalletFixture'; jest.mock('src/store/store', () => ({ store: { @@ -25,6 +26,10 @@ jest.mock('src/store/store', () => ({ jest.mock('realm', () => ({})); +beforeAll(() => { + installElectrumWalletFixture(); +}); + describe('Wallet Functionality Tests', () => { let primaryMnemonic: string; let wallet: Wallet; diff --git a/tsconfig.json b/tsconfig.json index a6af06ae6d..7e143716c9 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -18,5 +18,5 @@ "resolveJsonModule": true /* Allows importing modules with a ‘.json’ extension, which is a common practice in node projects. */, "baseUrl": "." }, - "exclude": ["node_modules", "babel.config.js", "metro.config.js", "jest.config.js"] + "exclude": ["node_modules", "dev/local-backend", "babel.config.js", "metro.config.js", "jest.config.js"] } From 58208450c88c0aabd4a44df52630c35843c16484 Mon Sep 17 00:00:00 2001 From: Anant Date: Fri, 9 Oct 2026 16:34:40 +0530 Subject: [PATCH 15/15] docs: align contributor install with sprint lock state --- dev/local-backend/README.md | 2 +- dev/local-backend/VERIFICATION.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/dev/local-backend/README.md b/dev/local-backend/README.md index 445707f9d3..eb69147c6a 100644 --- a/dev/local-backend/README.md +++ b/dev/local-backend/README.md @@ -41,7 +41,7 @@ From this app checkout's root: ./dev/local-backend/dev doctor ./dev/local-backend/dev up ./dev/local-backend/dev env -yarn install --frozen-lockfile --non-interactive +yarn install --non-interactive ``` `up` fetches the exact backend Git revisions, applies the local development adapters, builds containers, waits for readiness and runs real disposable API checks. `env` creates `.env.local` with restrictive permissions; it refuses to overwrite an existing different configuration. Existing `.env` and production files are not used or modified. diff --git a/dev/local-backend/VERIFICATION.md b/dev/local-backend/VERIFICATION.md index 7222bc86af..3279a7f36f 100644 --- a/dev/local-backend/VERIFICATION.md +++ b/dev/local-backend/VERIFICATION.md @@ -263,7 +263,7 @@ Apple Silicon Mac, macOS 26.6.2, Xcode 26.4/iOS 26.4 simulator, Node 25.9.0, Yar | Mainnet and hosted Mongo configuration rejection | PASS for relay and signing | | Actual container network/port inspection | PASS, backend network internal, no database port published, gateway bound only to loopback | | Rerun setup, existing env preservation, adapter tampering, unknown checkout preservation, duplicate ports | PASS, four regression tests plus real repeated bootstrap | -| Fresh `yarn install --frozen-lockfile --non-interactive` | PASS; no tracked dependency version changes | +| Fresh mobile Yarn install on the historical v2.5.15 acceptance tag | PASS with frozen mode at that source state; current `sprint` has unmatched lint-plugin lock selectors, so the README uses CI's non-frozen install command | | Fresh CocoaPods installation | PASS, 142 pods; see path-dependent checksum note below | | Fresh Android `assembleDevelopmentDebug` | PASS, 976 tasks executed, 5m17s | | Android installed local configuration | PASS, development environment and alternate local backend ports verified in generated BuildConfig |