mirror of
https://github.com/block/buzz.git
synced 2026-08-18 06:50:31 +02:00
d99ad131f1
Signed-off-by: Will Pfleger <pfleger.will@gmail.com> Signed-off-by: Will Pfleger <wpfleger@block.xyz> Signed-off-by: Will Pfleger <wpfleger@squareup.com> Signed-off-by: Will Pfleger <wpfleger96@gmail.com> Co-authored-by: npub1mn7jgtj4w2pd0g0zeuhxsa6jy6p0rewxz4kujt98my82ahfmp72sxjexk7 <dcfd242e557282d7a1e2cf2e6877522682f1e5c6156dc92ca7d90eaedd3b0f95@sprout-oss.stage.blox.sqprod.co> Co-authored-by: npub1fgdl5qqnh3k3f2xkqrvt7cujalhm623x4s7fdjdj5yrtp5fzjl9qrjpucw <4a1bfa0013bc6d14a8d600d8bf6392efefbd2a26ac3c96c9b2a106b0d12297ca@sprout-oss.stage.blox.sqprod.co> Co-authored-by: npub16v54tttfqacx9ycvc3k0ut0npj564ahcuajzy6qjvh57ntmsf4uq4806j2 <d32955ad69077062930cc46cfe2df30ca9aaf6f8e76422681265e9e9af704d78@sprout-oss.stage.blox.sqprod.co> Co-authored-by: Will Pfleger <wpfleger96@gmail.com>
129 lines
4.9 KiB
Markdown
129 lines
4.9 KiB
Markdown
# buzz-pair
|
|
|
|
CLI tool for testing the [NIP-AB device pairing protocol](../buzz-core/src/pairing/NIP-AB.md) end-to-end. Exercises the full protocol over a live Nostr relay — designed for interop testing and NIP submission, not production use.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
cargo build --release -p buzz-pairing-cli
|
|
|
|
# Terminal 1 — source (holds the secret)
|
|
./target/release/buzz-pair source --relay wss://relay.damus.io
|
|
|
|
# Terminal 2 — target (receives the secret)
|
|
./target/release/buzz-pair target --show-secret
|
|
# paste the QR URI from terminal 1 when prompted
|
|
```
|
|
|
|
Both sides display a 6-digit SAS code. Confirm they match on each side, and the key transfers.
|
|
|
|
## Subcommands
|
|
|
|
### `source`
|
|
|
|
Acts as the device holding the secret. Generates an ephemeral keypair and session secret, displays a `nostrpair://` QR URI, waits for a target to connect, performs SAS verification, and sends the payload.
|
|
|
|
```
|
|
buzz-pair source --relay <RELAY_URL> [--nsec <BECH32_NSEC>]
|
|
```
|
|
|
|
- `--relay` — WebSocket relay URL (default: `wss://relay.damus.io`)
|
|
- `--nsec` — bech32 nsec to transfer. If omitted, generates a throwaway test key.
|
|
|
|
### `target`
|
|
|
|
Acts as the receiving device. Reads a `nostrpair://` URI from stdin, connects to the relay encoded in the URI, sends an offer, verifies SAS, and receives the payload.
|
|
|
|
```
|
|
buzz-pair target [--relay <OVERRIDE_URL>] [--show-secret]
|
|
```
|
|
|
|
- `--relay` — Override the relay URL from the QR code
|
|
- `--show-secret` — Print the received secret to stdout (off by default for safety)
|
|
|
|
### `test-vectors`
|
|
|
|
Prints all derived cryptographic values from the NIP-AB spec's fixed test keys. Useful for verifying implementations against the spec.
|
|
|
|
```
|
|
buzz-pair test-vectors
|
|
```
|
|
|
|
## Testing Against a Local Buzz Relay
|
|
|
|
The CLI supports NIP-42 authentication, so it works with Buzz relays out of the box.
|
|
|
|
### Prerequisites
|
|
|
|
- Docker running (for Postgres, Redis, etc.)
|
|
- Buzz relay built: `cargo build --release -p buzz-relay`
|
|
|
|
### Start the relay
|
|
|
|
```bash
|
|
just setup # Docker services + schema
|
|
cargo build --release --workspace
|
|
screen -dmS relay bash -c "./target/release/buzz-relay 2>&1 | tee /tmp/buzz-relay.log"
|
|
sleep 3 && curl -s http://localhost:3000/health # → "ok"
|
|
```
|
|
|
|
### Run the E2E test
|
|
|
|
An automated test script using `expect` is provided:
|
|
|
|
```bash
|
|
.scratch/e2e-pair-local.sh
|
|
```
|
|
|
|
This spawns source and target as PTY-driven subprocesses, feeds the QR URI between them, waits for both SAS codes to appear, delays to ensure relay subscriptions are registered, then confirms SAS on both sides. Prints `PASS` or `FAIL` with the SAS codes.
|
|
|
|
**Requirements:** `expect` (macOS: built-in at `/usr/bin/expect`)
|
|
|
|
**Environment variables:**
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `RELAY_URL` | `ws://localhost:3000` | Relay to test against |
|
|
| `TEST_TIMEOUT` | `45` | Per-step timeout in seconds |
|
|
| `SOURCE_CONFIRM_DELAY_MS` | `3000` | Delay after SAS display before confirming (lets relay register subscriptions) |
|
|
|
|
### Manual two-terminal test
|
|
|
|
```bash
|
|
# Terminal 1
|
|
./target/release/buzz-pair source --relay ws://localhost:3000
|
|
|
|
# Terminal 2
|
|
./target/release/buzz-pair target --show-secret
|
|
# paste the nostrpair:// URI, confirm SAS on both sides
|
|
```
|
|
|
|
## Protocol Overview
|
|
|
|
```
|
|
Source Relay Target
|
|
────── ───── ──────
|
|
Generate ephemeral keys
|
|
Display QR (pubkey+secret+relay)
|
|
Subscribe kind:24134 Scan QR
|
|
Generate ephemeral keys
|
|
Subscribe kind:24134
|
|
Wait for EOSE
|
|
◄─────────────────────── Send offer
|
|
Verify session_id
|
|
Compute SAS ◄──────────────────────────────────────────► Compute SAS
|
|
Display: "047291" Display: "047291"
|
|
|
|
[User confirms codes match]
|
|
|
|
Send sas-confirm ──────────────►─────────────────────►
|
|
Verify transcript_hash
|
|
[User confirms]
|
|
Send payload ──────────────────►─────────────────────►
|
|
Decrypt + import
|
|
◄─────────────────────── Send complete
|
|
Done Done
|
|
```
|
|
|
|
All events are NIP-44 encrypted, signed with ephemeral keys, and addressed via `p` tags. The relay sees only opaque ciphertext between throwaway pubkeys.
|