Skip to content

README.md

Latest commit

 

History

History
109 lines (79 loc) · 4.88 KB

README.md

File metadata and controls

109 lines (79 loc) · 4.88 KB

Heartwood

CI GitHub Sponsors

Open-source Nostr signing software built on nsec-tree. Runs on a Raspberry Pi. Holds your master identity in hardware, derives unlimited unlinkable personas, signs events via NIP-46, reachable from anywhere via Tor. Private keys never leave the device.

What it does

  • One mnemonic, all identities. 12 words recover everything.
  • NIP-46 remote signing. Compatible with Nostr Connect clients across desktop and mobile.
  • Reachable over Tor by default. Hidden service configured during install. No port forwarding, no router configuration, no IP address exposed to clients.
  • Per-client permissions. Control which event kinds each paired app can sign.
  • Unlinkable personas. Derive separate identities for work, personal, anon. Nobody can link them unless you prove it.

How it compares

Heartwood nsecBunker Amber nsec.app LNbits NSD
Multi-identity from one seed Yes No No No No
Inbound Tor hidden service by default Yes No No No No
Per-client permissions Yes Yes No No No
Works from any device/OS Yes Yes Android only Browser only Desktop only
No server infrastructure Yes No (VPS) Yes Yes Yes
Hardware-isolated keys Yes No No No Yes

Hardware

Runs on any Raspberry Pi (Pi 4 for development, Pi Zero 2 W for dedicated deployment).

Item Price
Raspberry Pi Zero 2 W ~GBP 15
Micro SD card (8GB+) ~GBP 4
USB-C power supply ~GBP 5
Total ~GBP 24

No soldering. No custom hardware. Flash an SD card and go.

Quick start

On a Raspberry Pi running Raspberry Pi OS Lite (64-bit):

curl -sL https://github.com/forgesworn/heartwood/releases/latest/download/install.sh | sudo bash

Then open http://<hostname>.local:3000 in your browser and follow the setup wizard. See docs/QUICKSTART.md for the full walkthrough.

Build from source instead:

git clone https://github.com/forgesworn/heartwood && cd heartwood
cargo build --release -p heartwood-device
cd bunker && npm install && cd ..
cd pi && sudo bash setup.sh

Development

cargo test                    # Run all tests (55)
cargo test -p heartwood-core  # Core crypto tests only
cargo run -p heartwood-device # Run device binary (terminal mode)

Architecture

See ARCHITECTURE.md for the full internal architecture with diagrams.

heartwood-core     Pure crypto: nsec-tree derivation, signing, proofs, personas
heartwood-nip46    NIP-46 protocol: method dispatch, permissions, sessions
heartwood-device   Device binary: Tor, web UI, storage, OLED

Ecosystem

See docs/ECOSYSTEM.md for the full ecosystem overview with cross-cutting diagrams.

Part of the ForgeSworn open-source ecosystem:

  • nsec-tree -- Deterministic identity derivation (TypeScript reference)
  • shamir-words -- Mnemonic threshold backup
  • canary-kit -- Dead man's switch
  • toll-booth -- L402 API payments
  • bark -- Browser extension for NIP-07 signing via Heartwood
  • bray -- Nostr MCP server

Part of the ForgeSworn Toolkit

ForgeSworn builds open-source cryptographic identity, payments, and coordination tools for Nostr.

Library What it does
nsec-tree Deterministic sub-identity derivation
ring-sig SAG/LSAG ring signatures on secp256k1
range-proof Pedersen commitment range proofs
canary-kit Coercion-resistant spoken verification
spoken-token Human-speakable verification tokens
toll-booth L402 payment middleware
geohash-kit Geohash toolkit with polygon coverage
nostr-attestations NIP-VA verifiable attestations
dominion Epoch-based encrypted access control
nostr-veil Privacy-preserving Web of Trust

Licence

MIT