SeedSigner simulator
Real SeedSigner firmware, the actual Python off the
device, running in a browser tab. The screen is a canvas, the buttons are your
keyboard, the camera is your webcam.
Insecure by design
Never type in a seed phrase you rely on. Use a published test seed.
Nothing makes this safe: not running it offline, not a private window, not a
clean laptop. See below.
Why it cannot be made safe
A SeedSigner is a signing device because of what surrounds the software. None of
that is here. Only the software is.
| A real SeedSigner | This page |
|---|
| No wifi, no bluetooth, no port | A computer that has all three |
| Runs one program and nothing else | Runs beside extensions, other tabs, devtools, every process on the machine |
| Loses everything at power-off | A JavaScript heap, copied by the garbage collector into swap and hibernation files |
| A real smartcard holds the key | A JavaScript object pretending to be a smartcard |
| A screen only you see | A canvas any script or screen recorder can read |
Offline does not help. It changes one row and leaves the rest. The seed is
still typed into a general-purpose computer with an OS, a clipboard, a swap file
and a network connection it will use again later. Anything there that can read
memory or the screen can read the seed. Having no network is a property of the
page, not of the computer, and a tab is a sandbox against other websites, not
against the machine it runs on.
Mainnet works, which is the dangerous part. The page boots on Testnet, but
Mainnet is still in Settings, deriving real keys and signing real transactions
(test/test_mainnet.py checks them against BIP32, BIP143 and ECDSA). Treat
everything it shows you as public: seeds, passphrases, xpubs, descriptors,
signatures.
If you already entered a real seed here, move the funds to a seed generated
on a device you trust. SECURITY.md.
Good for learning the menus, rehearsing a flow, teaching multisig, testing a
fork's screens. Anything involving money belongs on hardware.
Three firmwares
| On the page | What it is | URL |
|---|
| SeedSigner | Stock, what a plain SeedSigner runs. The default | ?firmware=stock |
| ShieldSigner | 3rdIteration/seedsigner, adds SeedKeeper and Satochip | ?firmware=smartcard |
| Doomsigner | Our fork of that fork: BIP-352 silent payments, and DOOM in front | ?firmware=doomsigner |
The Firmware control under the device switches. DOOM is off on the first two
unless ?doom is on the URL; on Doomsigner it always boots into the game, and
five taps on the top side button reach the wallet.
Try it
git clone https://github.com/bitsagarob/seedsigner-simulator.git
cd seedsigner-simulator
./build/fetch-assets.sh # Pyodide, pinned and hash-checked (~26 MB, once)
./build/build-wallet-zip.sh smartcard # wallet-smartcard.zip, from the pinned commit
./build/build-wallet-zip.sh stock # wallet-stock.zip, from the pinned commit
python3 test/serve.py --port 8770 src/web src/shims build/out
Then open http://127.0.0.1:8770/. Use test/serve.py, not
python3 -m http.server: without the two isolation headers it sends, the wallet
never starts. Nothing fetched is committed, so what you run is provably the
pinned commit, and both steps verify what they download.
Arrow keys move, Enter selects, 1 2 3 are the side buttons, and the drawn
buttons work too. The screen is not one of them: a SeedSigner has no touchscreen.
To run your own fork, SS_REPO and SS_COMMIT override the pin for one build
(CONTRIBUTING.md).
What you can verify
- It is the firmware, not a re-creation.
wallet-<firmware>.zip holds that
firmware's upstream Python tree and its own Controller.start() runs it.
Menus, seed handling, PSBT parsing, QR encoders: all theirs, unmodified.
- Nothing patches the wallet. Hardware is replaced from outside, by
src/shims/. Even Testnet-at-boot is a value in the
settings.json the device reads, not an edit.
- Pinned to release tags, not branch tips (
UPSTREAM, one
section per firmware). The fork's tag is the one the official pi0-smartcard
device image is built from, so this and that device run the same code.
- Rebuild and compare.
build/build-wallet-zip.sh reproduces a zip byte for
byte. CI re-derives the hashes on every push on a clean runner and GitHub signs
the result:
gh attestation verify wallet-smartcard.zip --repo bitsagarob/seedsigner-simulator.
- Upstream's own tests run against our pins
(
upstream-tests.yml): about 2,500
from the fork's suite, all of stock's. About 200 of the fork's skip themselves,
most for want of a jcardsim build, pyscard or SeedSigner OS's own tools.
- The webcam really is the camera. Same
DecodeQR, same SeedQR /
CompactSeedQR / PSBT / UR parsing; only the decoder is the browser's.
- One host. No backend, and the CSP names one other origin,
signet.bitsaga.be, for the faucet and read-only lookups.
The walkthroughs
Three guided ceremonies done in the page. The resting page is a plain
SeedSigner, so none of them starts on its own: open the wallet drawer and the
picker offers whichever ones the running firmware can do, or name one on the URL
as ?tutorial=single, ?tutorial=multi or ?tutorial=musig.
| Walkthrough | Firmwares | What it does |
|---|
| Single sig | SeedSigner, ShieldSigner, DoomSigner | makes a seed, backs it up, exports the key, funds it, signs and sends. A checkbox adds a passphrase |
| Multisig | SeedSigner, ShieldSigner, DoomSigner | a 2 of 3, from three cards on the forks and by QR on stock |
| MuSig2 | DoomSigner | a 2 of 3 MuSig2, nonces exchanged and both cards signing. DoomSigner boots into DOOM, so five taps on the top side button open the wallet first |
Three published test seeds, the real PIN ceremony where there are cards, the
faucet on Bitsaga Signet pays the wallet, and the spend confirms. Those
coins are not real bitcoin. Press play and it narrates itself, or take over
and press the buttons.
The coordinator is drawn as a phone beside the device, because that is what it
is: signet-coordinator.js builds the
descriptor, addresses, PSBT and final transaction in the browser, and
test/test_tutorial.py checks every value against the wallet's own embit. The QR
transfers are real modules read off real pixels by the wallet's own decoder, so
your webcam is never involved.
Holding three keys on one device is fine for a demo and wrong for real funds.
What works, and what does not
Cards are the fork's, so under stock there is no card tray at all.
Works, any firmware. The full menu tree, seed loading by QR or by hand,
passphrases, xpub export, PSBT signing, SeedQR backup, settings, every QR screen.
Works, ShieldSigner and Doomsigner. Three card slots, each a SeedKeeper or
a Satochip, both PIN-checked. Seed onto a SeedKeeper and back off. A 2 of 3
descriptor onto a SeedKeeper. Satochip holds a real BIP32 master key and
authentikey, and pysatochip verifies every answer it signs.
Does not, any firmware. No microSD, so settings reset on reload and firmware
update is gone. Nothing on a background thread: no spinner, no scrolling text, no
pulsing border, and thread-based work such as brute-force address verification
never completes (camera preview and animated QR are pumped by hand). No timing,
so no wipe timer, screensaver or battery reading.
Does not, the fork. Card-to-card secret copy (refused rather than done in the
clear), card signing, PIN change, 2FA, factory reset, and Satodime: the fork lists
it under Smartcard Tools, and the tray has no Satodime to offer. Cards forget on
reload, deliberately.
How it works
The wallet's Python runs under Pyodide (CPython on
WebAssembly) in a Web Worker. Four hardware seams are replaced, three under stock.
| Seam | Replaced by | Why |
|---|
| Display | browser_display.py | Swaps the panel driver under SeedSigner's unmodified Renderer; RGB frames go to a canvas. |
| Buttons | wallet-worker.js | The worker is blocked in the wallet's main loop and can never answer a postMessage, so keys cross on a SharedArrayBuffer. |
| Camera + QR | browser_camera.py + wallet-camera.js | pyzbar has no WebAssembly build, so the browser decodes and hands bytes to the unmodified decoder. |
| Smartcard | src/smartcard/ | Browsers have no smartcard API, so simulated cards answer real APDUs and pysatochip runs unchanged. |
A fifth, browser_qr.py, draws the QR screens, whose
drawing lives in a thread this environment cannot run.
That one constraint, a permanently blocked worker, explains most of the
architecture. docs/ARCHITECTURE.md is the long version,
including why BarcodeDetector is never trusted with a payload.
Self-hosting
Static files. Two things trip up every first attempt
(docs/SELF-HOSTING.md):
Cross-Origin-Opener-Policy: same-origin and
Cross-Origin-Embedder-Policy: require-corp are mandatory, or
SharedArrayBuffer does not exist and the wallet never starts.- The camera needs
https or localhost. Plain http on a LAN has no camera
API to ask.
Development
python3 test/run.py builds what is missing and runs everything in a real
browser. CONTRIBUTING.md covers the rest,
test/README.md says what each test proves, and ?debug=1 traces
every screen, thread and keypress. Security reports: SECURITY.md.
Licence and credits
MIT, see LICENSE. Almost none of this code was written here: the
wallet is upstream SeedSigner (MIT,
Copyright (c) 2021 SeedSigner), the smartcard build is pinned to
3rdIteration/seedsigner, and the
browser side rests on Pyodide and
jsQR. THIRD-PARTY.md lists
every dependency and how to check it.
Independent project, not affiliated with or endorsed by SeedSigner. Running it
proves nothing about a real device.
