@bsv/expo-android-wallet-bridge
v0.1.0
Published
Loopback HTTP server, launch trampoline, foreground service and Expo module that let a page in Android Chrome use the app as its BRC-100 wallet.
Keywords
Readme
@bsv/expo-android-wallet-bridge
Lets a page in Android Chrome use an Expo app as its BRC-100 wallet over BRC-185's loopback HTTP transport. A Kotlin
loopback server, a launch trampoline, a foreground service and an Expo module form the transport; a TypeScript
controller wires them to @bsv/expo-wallet-toolbox's core/bridge (consent, dispatcher, Connect sheet) and a config
plugin does the manifest work. Foreground mode (milestone 1) is the supported mode. The sheet over Chrome (overlay,
milestone 2) is experimental and not shippable until the owner device gates in SPIKES.md pass.
Install: npm install @bsv/expo-android-wallet-bridge beside @bsv/expo-wallet-toolbox 0.23 or later, then add
['@bsv/expo-android-wallet-bridge', { scheme: '<your scheme>' }] to the app config's plugins.
Design: docs/superpowers/specs/2026-10-28-browser-bridge-android-design.md (revision 3). BRC-185 profile choices and
what is not claimed: CONFORMANCE.md. Spike results, emulator evidence, device gates and release gates: SPIKES.md.
How it works, in one paragraph
The page shows an intent://launch?... link. Chrome hands it to the app's exported trampoline, which stores the launch
secret in process memory and raises the wallet; the foreground service keeps the process. JS opens the loopback server
(127.0.0.1 and [::1], ports 3321 up to 3384) only for that session. The page finds the port, reads a signed
descriptor, proves it holds the launch secret in the connect, and the wallet shows its Connect sheet. Every Android site
is "Unverified" (the origin is not attested). The server closes when the last binding ends.
What the host does
Requires Chrome 142 or newer on the phone (the loopback permission), and an Android-only entry.
Plugin entry in
app.config.js:;['@bsv/expo-android-wallet-bridge', { scheme: 'bsv-wallet-bridge' }]android.packagemust be set.schemedefaults to<android.package>.bridge; it must be lowercase RFC 3986 syntax, nothttp,https,intent,file,content,javascriptordata, and not a scheme the host or another activity already handles (the prebuild fails with a namedAndroidWalletBridge:error). The plugin adds one exportedLaunchTrampolineActivitywith a singleVIEW/DEFAULT/BROWSABLEfilter on<scheme>://launch. It warns when the host declaresSYSTEM_ALERT_WINDOW(the kit draws no overlay; block it) orallowBackupis true.Entry file (
index.js): after the native crypto bootstrap and beforeexpo-router/entry, on Android only:require('@bsv/expo-android-wallet-bridge').setupAndroidBridge({ appName: 'Bitcoin SV Wallet', // shown to the page as the descriptor's instance label (never the device name) vendor: 'org.bsvblockchain.wallet', allowLocalhostHttp: __DEV__ // can only switch the feature off, see below })It must run before the wallet is first built: the unverified permissions manager exists only if an unattested transport was registered at build time, and a late registration makes every Android dispatch fail
PROVIDER_CHANGED. It registers theandroid-loopbacktransport, drains the launch record of a cold start, and opens no port.Mount
<AndroidBridgeHost />beside<PermissionSheet />insideBrowserBridgeProvider, inside the toolbox theme, wallet, exchange-rate and user providers (it publishes those contexts to the overlay's second React root, and above any of them it would publish defaults). Wrap the main tree's<PermissionSheet />in<AndroidBridgeSheetGate>so that only onePermissionSheetexists across the two roots. It feeds the wallet-in-front signal, asks forPOST_NOTIFICATIONSonce at the first accepted launch, asks native to go back to the browser after the last pending item clears, and renders the notices (notifications off, ports exhausted, wallet not ready). It renders nothing off Android or before setup.app/+native-intent.ts:redirectSystemPathreturns'/'for any URL beginning with the bridge scheme. The launch never reaches the router (the trampoline consumes it); this is defence in depth.Plain-HTTP origins in development. The host states
configureToolbox({ browserBridge: { allowLocalhostHttp: __DEV__ } })itself; the kit never callsconfigureToolbox(it would replace the host's whole toolbox configuration). The router asks the same flag at request time, sosetupAndroidBridge's option can only switch the feature off.R8: the kit's
android/consumer-rules.prokeeps the module, the trampoline and the service; the host'sCodedExceptionrule covers the error classes. Verify a release build withdexdump(seeSPIKES.md, release gates).Play Console: a
specialUseforeground-service declaration and a data-safety line (release gate).package.jsongets the dependency when a release is cut; until thenscripts/link-kit.sh <host-dir>packs this package and the toolbox into the host'snode_modules.
Public API: setupAndroidBridge, AndroidBridgeHost, AndroidBridgeNotices, resetAndroidBridge, getAndroidBridge,
getBsvAndroidBridge, createSecureStoreContinuity, ANDROID_TRANSPORT_ID ('android-loopback'). createLoopbackPageClient
(src/testing) is the stand-in page client.
What the user sees, and the way back
The wallet comes forward on the page's launch click, shows the Connect sheet, and returns to Chrome by itself 600 ms after the last pending item clears, when the bridge raised it. If Chrome is in front when a later request needs approval, a private notification ("A website wants to continue. Tap to review.", no site named) is posted; with notifications denied the request waits and the wallet shows a notice when opened. When the wallet was opened by the user, the way back is the system Back gesture or the app switcher; the kit never forces it. Disconnect is an action on the service notification.
Overlay mode (milestone 2, experimental)
Overlay mode is experimental until the owner device gates pass (see "Ship gate" below); until then ship foreground mode only.
- When it appears. On the page's launch click, when the wallet process is already running, unlocked and has its React
host attached and ready, and
MainActivityis alive and not in front, the launch raisesBridgeSheetActivity: a translucent sheet (about 90 percent scrim) over Chrome, which stays visible and running behind it. Every other state (cold start, locked, unknown, the tracker not caught up yet) uses foreground mode exactly as before. - Finishing. The sheet shows the same permission sheets as the wallet screen on a second React root of the same host. When the last pending item clears it finishes, and Android returns to the task below it, which is Chrome.
- Back and Home. Back finishes the sheet natively (button and predictive back), never through JS, and never answers the prompt: the request stays parked and the attention notification follows. Home (or any leave) finishes the sheet when it stops; the next launch starts a fresh sheet. A screen-off does not finish it.
- The idle sheet. A launch with nothing pending shows an empty sheet whose window is non-touchable and paints no scrim, and which finishes by itself after about 5 s. In the emulator idle-window run (O15) a tap did reach Chrome, but S3 row (i) found taps swallowed under the translucent non-idle sheet, so real-phone tap behaviour is open (owner gate 6).
- The second tap. While the sheet is up, a second "Open wallet" tap on the page does not reach the wallet (Chrome withholds external-intent launches while its Activity is paused; cause not isolated, S3 row g). Finish the sheet first.
- Notification fallback. A prompt that arrives later, while the wallet is in the background, is not forced onto the screen
(Android blocks background Activity starts, S6). The M1 notification is posted (no site named); its tap opens
BridgeSheetActivity, which shows the sheet when the wallet is warm and forwards to the wallet when it is not.showSheetis deliberately not implemented: there is no owner decision to force background sheets. - Protections.
FLAG_SECUREon every sheet; on API 31+setHideOverlayWindows(true)(the sheet finishes and forwards to the wallet if the platform refuses); touches carrying an obscured flag are dropped, and after 3 dropped touches the sheet is replaced by the in-wallet sheet, so another app drawing over the sheet (including a benign screen filter) sends the user to the wallet screen instead of leaving a prompt that cannot be answered. Approve keeps its 700 ms tap protection. An outside tap or a swipe down never answers the prompt. The activity isexported="false"and takes only a sequence number. - Host adoption.
AndroidBridgeSheetGatearound the main tree'sPermissionSheet, andAndroidBridgeHostinside the four toolbox providers (step 3 above).setupAndroidBridgeregisters theBsvBridgeSheetroot. - Ship gate. Not shippable until the owner records device gates 1, 2, 6 and 7 as passed (
SPIKES.md, "Device gates for the owner (M2)"). The emulator run (cases O1 to O21) is inSPIKES.md.
Limits
- Chrome only, 142 or newer; other browsers are untested. Incognito tabs do not launch (Chrome does not hand
intent://to an app from Incognito). - A launch on every connect, even for a returning site. Sessions live only while
MainActivity's React tree is mounted. - Process death drops every binding; a request in flight is
unknownto the page. Bindings idle for 30 minutes are closed. - No port is open outside a session. At most 4 parked connects, 32 connections, 32 live launch records.
- The overlay is experimental and shows only at the launch click with a warm wallet; later prompts use the notification. See
CONFORMANCE.mdand spec section 12 for the full list.
The two test paths
- Stand-in demo page (never shipped):
NODE_PATH=<dir with esbuild> node demo/build.mjs, thennode demo/serve.mjs 3001,adb reverse tcp:3001 tcp:3001, openhttp://localhost:3001in Chrome on the emulator or a USB-connected phone. A debug host build withallowLocalhostHttpaccepts that origin without a Chrome prompt (BRC-325 exempt). The page has the fast.brc.dev BRC-100 conformance panel (vendored, see the iOS kit'sdemo/conformance/SOURCE.md); spending cards are never part of Run all. - Emulator end-to-end driver:
node scripts/e2e/run.mjs [--only 1,4] [--keep-chrome]drives 17 cases on the Pixel_9 AVD with Chrome over CDP, uiautomator and adb. Preconditions and results:SPIKES.md(Task 24); evidence indocs/superpowers/evidence/android-kit/. The https path (https://deggen.ngrok.app) needs its own tunnel and a Chrome permission prompt: a device gate.
Developing
- Toolbox pure modules:
packages/expo-wallet-toolbox/core/bridge/loopback/, tests in__tests__/bridge/loopback. - Kit tests:
npx jest --ci packages/expo-android-wallet-bridgefrom the repo root (no--forceExit). - Kotlin pure-JVM suite:
android/jvmtest(check-pure.shfirst, then Gradle 9.3.1test; recipe inSPIKES.md). Kotlin that needs Android (module, service, trampoline, server threads) is compiled by the host build and exercised on the emulator. - Never log
k, the epoch, the launch URI, proofs, acks, binding secrets, tokens, bodies or theBRC-185-KeyandBRC-185-Android-Bindingheaders.
