From c0e42f9ac47990871dce42b98b65a8ebcaae4ba5 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 22 Jul 2026 22:32:44 +0100 Subject: [PATCH 1/3] docs: add SECURITY.md with a real vulnerability disclosure process MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PR #246 (kcw-grunt-patch-1) added SECURITY.md but left it as GitHub's unedited default template — placeholder version numbers (5.1.x/5.0.x) that don't match any real Brainwallet release, and instructional placeholder text ("Use this section to tell people...") never filled in with actual content. Replaced with a real policy: reporting instructions pointing at the verified support channel (brainwallet.co/support, from BWConstants.SUPPORT_WEB_LINK — there's no dedicated security@ email anywhere in this repo, and GitHub's private vulnerability reporting is not enabled for this repo, confirmed via the API), explicit scope (wallet/key-management code in scope, third-party deps and social engineering out of scope), a supported-versions policy matching how this app actually ships (continuous release, latest version only), and a safe harbor statement — all relevant for a wallet app handling real user funds and seed phrases. Co-Authored-By: Claude Sonnet 5 --- SECURITY.md | 68 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 SECURITY.md diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 00000000..dd25a622 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,68 @@ +# Security Policy + +Brainwallet is a self-custodial Litecoin wallet. A vulnerability here can put +users' funds or seed phrases at direct risk, so we treat security reports +with priority and ask that they be disclosed to us privately first. + +## Reporting a Vulnerability + +**Please do not open a public GitHub issue for security vulnerabilities.** +Public issues are indexed and searchable, and a wallet vulnerability +disclosed that way can be exploited before we're able to ship a fix. + +To report a vulnerability, contact us at [brainwallet.co/support](https://www.brainwallet.co/support) +and clearly mark your message as a **security report**. + +When reporting, please include: +- A description of the vulnerability and its potential impact +- Steps to reproduce, or a proof of concept if you have one +- The affected version (or commit hash) and platform (Android/iOS) +- Any suggested severity or CVSS score, if you have one + +**What to expect:** +- We aim to acknowledge new reports within a few business days. +- We'll work with you to confirm the issue, keep you updated as we + investigate and remediate it, and let you know once a fix has shipped. +- With your permission, we're happy to credit you for the report once it's + resolved. + +## Scope + +**In scope:** +- The Brainwallet Android app in this repository — key management, + transaction signing and broadcast, wallet backup/recovery (seed phrase), + PIN/biometric authentication, and secure local storage + (`app/src/main/jni/core`, `app/src/main/secp/secp256k1`) +- Companion modules pulled in as git submodules: `bw-gdlib`, + `android-private-general-purpose`, `android-build-logic` + +**Out of scope:** +- Vulnerabilities in third-party dependencies with their own upstream + disclosure process — please report to the upstream project (we'd + appreciate a copy of the report too, but it isn't required) +- Social engineering, phishing, or attacks requiring physical access to an + unlocked device +- Issues that only reproduce on a rooted/jailbroken device or a device + already compromised by other malware +- Denial-of-service against our backend/infrastructure rather than the app + itself +- Missing security best-practices with no demonstrated, concrete impact + +## Supported Versions + +Brainwallet ships continuously through the Play Store, and we only support +the most recently published release — please make sure you can reproduce an +issue on the latest version before reporting it. + +| Version | Supported | +| -------------- | :-------: | +| Latest release | ✅ | +| Older releases | ❌ | + +## Safe Harbor + +We consider security research conducted in good faith and in line with this +policy to be authorized. We will not pursue legal action against researchers +who make a genuine effort to avoid privacy violations, data destruction, and +service disruption, and who report vulnerabilities to us privately as +described above before any public disclosure. From 5a9e3559dd3b976d0f7ba1ae531e81f7d44f909d Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 22 Jul 2026 22:32:54 +0100 Subject: [PATCH 2/3] docs: restructure README with a real front page for new visitors/contributors MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The README opened straight into CI badges followed by a raw dump of release notes in inconsistent order (v4.9.0, then v4.8.3, then a jump back to v3.9.0-v3.9.1, v3.6.0, v3.3.1) — no description of what the app actually does beyond the title, no download links, no build/setup instructions, no contributing/security/license pointers. For an actively-developed open-source wallet repo, that's a poor front door for anyone landing here from GitHub search or the Play Store listing. Added, all verified against the actual repo/app rather than assumed: - A real description and feature list - Download links (Play Store id ltd.grunt.brainwallet, verified live; the gruntsoftware/ios sibling repo; brainwallet.co) - Clone/build instructions grounded in the actual submodule setup and local.properties/google-services.json requirements from .circleci/config.yml - Architecture summary (Koin, Compose, Coroutines, native wallet core) matching the real module layout - Testing, Security (linking the new SECURITY.md), Contributing (linking the existing PR template), and License sections Preserved the full existing release-notes content underneath a "Release Notes" heading rather than deleting project history, with a pointer to GitHub Releases/compare views for the current changelog going forward. Co-Authored-By: Claude Sonnet 5 --- README.md | 158 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 112 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index c92a651c..ab5d3a2c 100644 --- a/README.md +++ b/README.md @@ -1,32 +1,106 @@ - # Brainwallet: Android -The open source code of Brainwallet Android -## CI/CD Status -**main**: [![CircleCI](https://dl.circleci.com/status-badge/img/gh/gruntsoftware/android/tree/main.svg?style=svg)](https://dl.circleci.com/status-badge/redirect/gh/gruntsoftware/android/tree/main) +**Brainwallet** is a free, open-source, self-custodial [Litecoin](https://litecoin.org) wallet for Android. Your seed phrase and keys stay on your device — Brainwallet never has custody of your funds. + +[![CircleCI](https://dl.circleci.com/status-badge/img/gh/gruntsoftware/android/tree/main.svg?style=svg)](https://dl.circleci.com/status-badge/redirect/gh/gruntsoftware/android/tree/main) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) +[![Website](https://img.shields.io/badge/website-brainwallet.co-blue)](https://brainwallet.co) + +**CI status** — [main](https://dl.circleci.com/status-badge/redirect/gh/gruntsoftware/android/tree/main) · [develop](https://dl.circleci.com/status-badge/redirect/gh/gruntsoftware/android/tree/develop) + +## Download + +- **Play Store**: [ltd.grunt.brainwallet](https://play.google.com/store/apps/details?id=ltd.grunt.brainwallet) +- **iOS**: [gruntsoftware/ios](https://github.com/gruntsoftware/ios) +- **Website**: [brainwallet.co](https://brainwallet.co) +- **Support**: [brainwallet.co/support](https://www.brainwallet.co/support) + +## Features + +- Self-custodial Litecoin wallet — your seed phrase never leaves your device +- Send/receive LTC with real-time fee estimation and fiat conversion +- PIN and biometric app lock +- Buy/sell LTC and gift cards via in-app widgets +- In-app mini-games (built on a shared LibGDX library, [`bw-gdlib`](https://github.com/gruntsoftware/bw-gdlib)) +- Modern Jetpack Compose UI, with a legacy Java/UIKit-era codebase still being progressively migrated + +## Getting Started + +### Prerequisites +- Android Studio (current stable) with SDK 36 installed, NDK `25.1.8937393`, CMake `3.22.1` +- `minSdk 29`, `targetSdk 35` + +### Clone with submodules + +This repo pulls in several git submodules (`android-build-logic`, `bw-gdlib`, `modules/private-general-purpose`, native wallet code under `app/src/main/jni/core` and `app/src/main/secp/secp256k1`). Clone with: + +```bash +git clone --recurse-submodules https://github.com/gruntsoftware/android.git +# or, if already cloned: +git submodule update --init --recursive +``` + +### Local configuration + +Some values (signing keystores, Firebase config) are pulled from `local.properties`, which is gitignored and not included in this repo. On CI these are materialized from encrypted environment variables at build time (see `.circleci/config.yml`). To build locally you'll need to supply your own debug keystore and a `local.properties` with matching `DEBUG_STORE_FILE`/`DEBUG_STORE_PASSWORD`/`DEBUG_KEY_ALIAS`/`DEBUG_KEY_PASSWORD` entries, plus your own `app/google-services.json` from a Firebase project. + +### Build & run + +```bash +./gradlew assembleDebug # build a debug APK +./gradlew installDebug # install on a connected device/emulator +./gradlew test # run unit tests +./gradlew detekt # static analysis +``` + +## Architecture -**develop**: [![CircleCI](https://dl.circleci.com/status-badge/img/gh/gruntsoftware/android/tree/develop.svg?style=svg)](https://dl.circleci.com/status-badge/redirect/gh/gruntsoftware/android/tree/develop) +- **Language/UI**: Kotlin, Jetpack Compose (legacy screens still in Java/`View`-based UIKit-era code under `presenter/`, being migrated incrementally) +- **DI**: [Koin](https://insert-koin.io/) +- **Concurrency**: Kotlin Coroutines & `StateFlow` +- **Wallet core**: native C/C++ (`app/src/main/jni/core`), elliptic curve crypto via [`secp256k1`](https://github.com/bitcoin-core/secp256k1) +- **Modules**: `app` (main app), `bw-gdlib` (mini-games, LibGDX, composite build), `modules/private-general-purpose` (in-app purchases + general-purpose features), `android-build-logic` (shared Gradle convention plugins) +## Testing + +Unit tests live under `app/src/test/{java,kotlin}`. Run them with `./gradlew test`, or a specific variant with `./gradlew testBrainwalletDebugUnitTest`. CI runs on CircleCI (`.circleci/config.yml`). + +## Security + +Found a security vulnerability? Please **do not** open a public issue — see [SECURITY.md](SECURITY.md) for how to report it privately. + +## Contributing + +Pull requests are welcome — please target the `develop` branch. The [PR template](.github/PULL_REQUEST_TEMPLATE.md) will guide you through what to include (platform, type of change, tests, etc.). + +## License + +Brainwallet Android is released under the [MIT License](LICENSE). + +--- + +## Release Notes + +For the full, up-to-date changelog see [GitHub Releases](https://github.com/gruntsoftware/android/releases) and the [compare view](https://github.com/gruntsoftware/android/compare). Highlights from recent versions: -# 🚀 Brainwallet Android — Release Notes ### v4.9.0 -### ✨ New Features +#### ✨ New Features -#### 📋 Copy Transaction Details to Clipboard +##### 📋 Copy Transaction Details to Clipboard Transaction details can now be copied directly to the clipboard from the transaction detail view. A new `BRClipboardManager.putDetailsClipboard()` method handles the copy action with full analytics tracking, making it easy to share or reference transaction information outside the app. -#### 📊 Analytics Tracking for Key Interactions +##### 📊 Analytics Tracking for Key Interactions Firebase analytics events are now fired for core user interactions — fiat/LTC toggle, balance visibility toggle, and transaction detail copy — giving the team better insight into how users engage with the wallet's main screens. --- -### 🎨 UI / Design System +#### 🎨 UI / Design System -#### 🧱 Unified `bentoSurface` Design System -A new `bentoSurface()` modifier in `BentoModifiers.kt` consolidates gradient and border styling across the entire bento UI. Previously hardcoded values like `1.dp` borders are now driven by shared constants (`bentoBorderWidth`, `bentoCornerRadius`, `bentoCornerRadius`, `bentoSpacer`, `transactionActionHt`, `transactionDetailHt`), making the visual system consistent and easy to maintain going forward. +##### 🧱 Unified `bentoSurface` Design System +A new `bentoSurface()` modifier in `BentoModifiers.kt` consolidates gradient and border styling across the entire bento UI. Previously hardcoded values like `1.dp` borders are now driven by shared constants (`bentoBorderWidth`, `bentoCornerRadius`, `bentoSpacer`, `transactionActionHt`, `transactionDetailHt`), making the visual system consistent and easy to maintain going forward. -#### 🃏 Bento Section Refactors +##### 🃏 Bento Section Refactors - **GameHub** — migrated from `Card` to `Box` with `bentoSurface()`, with a `clickable` modifier added - **Favourites** — refactored to `bentoSurface()` with improved `Spacer` layout - **LTC Picker** — label repositioned to top, spacing and item heights adjusted @@ -35,66 +109,58 @@ A new `bentoSurface()` modifier in `BentoModifiers.kt` consolidates gradient and --- -### 🔧 Technical Changes +#### 🔧 Technical Changes - `MainScreen`, `MainScreenEvent`, and `MainViewModel` updated for new event handling and state management - `NoWifiBalanceAlertScreen` and `ReceiveDialog` border widths replaced with `bentoBorderWidth` constant - `strings.xml` updated with new/updated string resources - `gradle/libs.versions.toml` and `app/build.gradle.kts` dependencies updated - `detekt-app-baseline.xml` baseline updated -- Version bumped: **v4.8.4 (202506314) → v4.9.0 (202506315)** +- Version bumped: **v4.8.4 (202506314) → v4.9.0 (202506315)** - Release/v4.7.2 202506296 by @kcw-grunt in https://github.com/gruntsoftware/android/pull/134 - Release/v4.8.0 by @kcw-grunt in https://github.com/gruntsoftware/android/pull/145 **Full Changelog**: https://github.com/gruntsoftware/android/compare/v4.7.2...v4.9.0 + ### v4.8.3 -## ✨ New UI — Favourites & Tutorials Bento Sections +#### ✨ New UI — Favourites & Tutorials Bento Sections **PR [#191](https://github.com/gruntsoftware/android/pull/191)** The main screen now features two new purpose-built bento panels replacing the generic placeholder container. The **Favourites** panel displays a set of coloured circular indicators using the app's design theme colours (affirm, info, warn, error) with full dark/light mode support. The **Tutorials** panel shows a "Coming Soon" placeholder consistent with the broader bento design language. The old `HomeBentoContainer` has been removed. String resources for both sections have been translated across 19 locales including Arabic, Chinese (Traditional & Simplified), French, German, Farsi, Hindi, Indonesian, Italian, Japanese, Korean, Polish, Punjabi, Brazilian Portuguese, Russian, Spanish, Swedish, Turkish, and Ukrainian. -## 🔧 Send Screen Overhaul & Financial Precision +#### 🔧 Send Screen Overhaul & Financial Precision **PR [#182](https://github.com/gruntsoftware/android/pull/182)** The send transaction flow has been fully redesigned as a multi-step paged screen (Pre-send → Confirm → Authenticate). All monetary values have been migrated from `Float` to `BigDecimal` with explicit rounding modes, eliminating floating-point precision issues in fiat/LTC conversions. Transaction fees are now calculated dynamically using `getFeePerKb()` rather than a static default. The pre-send composable has been broken into focused sub-components (`PreSendAddressRow`, `PreSendAmountRow`, `PreSendMemoRow`), and passcode UI components have been extracted into a dedicated package. QR code scanning is now wired into the send flow via an `EventBus` event. A `BWSender` class handles transaction preparation with proper error handling and activity context management. -## 🧪 Test Coverage Expanded to 309 Tests +#### 🧪 Test Coverage Expanded to 309 Tests **PR [#182](https://github.com/gruntsoftware/android/pull/182)** - Unit test coverage has been significantly expanded alongside the send screen work, bringing the total suite to **309 tests**. New test classes include `AppModuleTest`, `SendStateTest`, and `BrainwalletAppTest`, covering the Koin DI module wiring, send state logic, and core app initialisation paths. - - -### v3.9.0 - v3.9.1 Latest -Update README for improved description by @kcw-grunt in #78 -Beta Release [ 🚀 ] Merge Develop into Main by @kcw-grunt in #81 - -#### Fixes and Changes: +### v3.9.0 – v3.9.1 +- Update README for improved description by @kcw-grunt in #78 +- Beta Release [ 🚀 ] Merge Develop into Main by @kcw-grunt in #81 - Current fiat preference from Settings needs to be reset if set in the TickerBento - Localizations are covered to 100% - Mini game FALLINMOJI is present in the Welcome and Game Hub -- When setting the theme from the Settings and the Lock Screen and the Main screen is not consistently applied -- In general the fonts in the app are not consistent and need to be managed properly for consistency -- Mini game sounds set a nominal level -- Layout for iPhone 8 - iPhone 17 Pro Max is set for: Welcome Screen -- Support.brainwallet.co link is fixed - -### v3.6.0 Latest - -#### What's Changed -🚀[Release v3.5.0] Merge into Main by @kcw-grunt in #51 -Full Changelog: v3.4.2...v3.6.0\ - -#### Updates: -- using bundle exec fastlane single_unit_test_all -- downgrade firebase to 11.12.0 -- polsih ci config +- Theme applied from Settings/Lock Screen/Main screen made consistent +- Fonts made consistent across the app +- Mini game sounds set to a nominal level +- Layout fixes for iPhone 8 – iPhone 17 Pro Max on the Welcome Screen +- Support.brainwallet.co link fixed + +### v3.6.0 +- 🚀 [Release v3.5.0] merged into Main by @kcw-grunt in #51 +- Full Changelog: v3.4.2...v3.6.0 +- Switched to `bundle exec fastlane single_unit_test_all` +- Downgraded Firebase to 11.12.0 +- CI config polish - 🦾 Chore/migrate ready onboarding - Fix/login view crash -- 🧰 fix: Removed the thread blocking seen in the lock screen trx. loading +- 🧰 Fix: removed thread blocking in the lock screen transaction loading - Epic/settings migration (#50) -- Chore/refactor firebase analytics +- Chore/refactor Firebase analytics - Chore/activate test coverage ### v3.3.1 - Added locale filter -- Made improvements to UI -- Fixes +- UI improvements +- Various fixes From 0ec44e8a5305dc142955e938272ebe903a7630ce Mon Sep 17 00:00:00 2001 From: kcw-grunt Date: Wed, 22 Jul 2026 22:41:11 +0100 Subject: [PATCH 3/3] updated the README.md --- README.md | 32 +++----------------------------- 1 file changed, 3 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index ab5d3a2c..ce2ed228 100644 --- a/README.md +++ b/README.md @@ -19,40 +19,17 @@ - Self-custodial Litecoin wallet — your seed phrase never leaves your device - Send/receive LTC with real-time fee estimation and fiat conversion -- PIN and biometric app lock +- Games to help you memorize your seed phrase (Check out Fallinmoji!) +- PIN app lock - Buy/sell LTC and gift cards via in-app widgets -- In-app mini-games (built on a shared LibGDX library, [`bw-gdlib`](https://github.com/gruntsoftware/bw-gdlib)) - Modern Jetpack Compose UI, with a legacy Java/UIKit-era codebase still being progressively migrated -## Getting Started +## Auditing code ### Prerequisites - Android Studio (current stable) with SDK 36 installed, NDK `25.1.8937393`, CMake `3.22.1` - `minSdk 29`, `targetSdk 35` -### Clone with submodules - -This repo pulls in several git submodules (`android-build-logic`, `bw-gdlib`, `modules/private-general-purpose`, native wallet code under `app/src/main/jni/core` and `app/src/main/secp/secp256k1`). Clone with: - -```bash -git clone --recurse-submodules https://github.com/gruntsoftware/android.git -# or, if already cloned: -git submodule update --init --recursive -``` - -### Local configuration - -Some values (signing keystores, Firebase config) are pulled from `local.properties`, which is gitignored and not included in this repo. On CI these are materialized from encrypted environment variables at build time (see `.circleci/config.yml`). To build locally you'll need to supply your own debug keystore and a `local.properties` with matching `DEBUG_STORE_FILE`/`DEBUG_STORE_PASSWORD`/`DEBUG_KEY_ALIAS`/`DEBUG_KEY_PASSWORD` entries, plus your own `app/google-services.json` from a Firebase project. - -### Build & run - -```bash -./gradlew assembleDebug # build a debug APK -./gradlew installDebug # install on a connected device/emulator -./gradlew test # run unit tests -./gradlew detekt # static analysis -``` - ## Architecture - **Language/UI**: Kotlin, Jetpack Compose (legacy screens still in Java/`View`-based UIKit-era code under `presenter/`, being migrated incrementally) @@ -69,9 +46,6 @@ Unit tests live under `app/src/test/{java,kotlin}`. Run them with `./gradlew tes Found a security vulnerability? Please **do not** open a public issue — see [SECURITY.md](SECURITY.md) for how to report it privately. -## Contributing - -Pull requests are welcome — please target the `develop` branch. The [PR template](.github/PULL_REQUEST_TEMPLATE.md) will guide you through what to include (platform, type of change, tests, etc.). ## License