QR Secret Transfer (QRST)

Move a secret from one device to another by scanning a QR code. One device shows a code, the other scans it, a person checks five digits across the two screens, and only then does the secret travel, sealed, over public relays that neither device runs and that cannot read it.

Live demo: https://sybenx.github.io/qr-secret-transfer/ · Specification · Profiles

Questions or breakage reports: Nostr: npub175rn…sef5g

This repository is three things:

• The specification, QR_SECRET_TRANSFER.md, with the profiles that say what kinds of secret it carries (a Nostr key, a FROST share, or an app's own, such as a sync key for a game) and its test vectors. The core mechanism knows nothing about what it moves; a new kind of secret is a new profile, never a change to the specification.
• A live demo and landing page (docs/, built from src/demo/). It moves a short piece of text between two devices. It is a static page: no server of its own, no analytics, nothing loaded from anywhere else, and no network activity until a transfer is started.
• A protocol core (src/core/) with no I/O, no DOM and no timers, plus the browser adapters that run it over relays (src/web/).
• The same core and relay layer in Kotlin (kotlin/), a port line for line, for Android and JVM apps. QRST Signer and Cosign build on it.

Status: a draft protocol and unaudited code. Use made-up values, not real secrets. The event kinds are provisional and interoperability is not promised.

Try it

npm install
npm run build        # writes docs/
npm run relay        # a local relay on ws://localhost:7777
npm run serve        # the page on http://localhost:8080

Open the page in two browser windows (or on two devices that can both reach the relay). In each, open This device: relays and past transfers and add ws://localhost:7777. Then choose Receive a secret in one and Send a secret in the other.

On the public internet no setup is needed: the page finds relays itself (see Relays).

Put it online

docs/ is the whole site. On GitHub: Settings → Pages → Deploy from a branch → main / docs. Any static host works; the page uses only relative paths, so it can live at a domain root or under a path. This repository's copy is live at https://sybenx.github.io/qr-secret-transfer/.

The page is its own bounce page (spec §11.2a): the QR codes it shows point back at whatever address it is served from, with every parameter in the fragment, so nothing about a pairing ever reaches the host.

Three <meta> tags in src/demo/index.html are the configuration:

Tag	Meaning
qrst:relays	Relays you supply, tried first. content="wss://relay.example.com"
qrst:seeds	Replaces the starting relays this build ships. content="none" ships none.
qrst:discovery	Relays to ask for NIP-66 discovery events. content="none" asks nobody extra.

Before publishing a copy elsewhere, set a canonical URL in src/demo/index.html, and its GitHub links if your copy of the specification lives somewhere else.

What it implements

The wire protocol of QR_SECRET_TRANSFER.md 1.6-draft:

• the commit-then-reveal exchange and five-digit code of §6, reproducing the specification's own vectors (vectors/qrst-sas.json);
• Flow A and Flow B (§7, §8), with the roles never inferred from who showed the code;
• sealing and gift-wrapping (§11.4) as an ephemeral gift wrap, kind 21059 (NIP-59 §4), which relays do not store, over NIP-44 v2, with true timestamps and the attribution check, checked against the official NIP-44 vectors and against nostr-tools in both directions;
• the pairing link (§11.2), the bounce page (§11.2a), how a code is presented (§11.2b), and the qrst: handoff to an installed app (§11.2c), which the bounce page offers and the paste field accepts;
• the release prompt, the three levels of checking the code, and the restart throttle (§9), as far as code can enforce them, and the acceptance confirmation;
• the one-time token in every pairing link (§11.2, §11.4);
• relay selection by loopback test (§11.3a): see Relays;
• multiple responders (§13) and the local transfer record (§14);
• relay subscription, re-sending each message in a fresh wrap until the peer answers it, rumor-level deduplication, and NIP-42 with the burner (§11.5).

1.6-draft moved the wrap from kind 1059 to 21059 because of this implementation: relays treat kind 1059 as a stored direct message and were seen serving one long after its NIP-40 expiry. A 1.5 client, which uses 1059, cannot pair with this one.

The three levels of §9.2 are chosen on each device with a slider, and the stricter of the two devices' settings applies:

Level	Sender	Receiver	For
Type digits (high)	types the digits shown on the Receiver	shows five digits	what cannot be taken back
Compare digits (medium, default)	shows five digits, the user confirms they match	shows five digits	most things
Confirm only (low)	consent only; a second responder ends the session	shows nothing	what can be revoked

Not implemented: the offline tier (§10), the local network path (§11.7, which a browser cannot do), profile URI schemes such as frost:// (§12.3), reading the code by camera (§9.2 "capture"), and the published profiles. The demo carries only its own text profile, qrst-demo-text (src/core/profile.ts).

This is the beginning of the README. Read the rest at the original. Read the full README ↗