Lessons from building a QR-paired browser handoff tool

A developer built a QR-paired browser handoff tool that transfers text or files between devices without accounts or cloud storage. The tool uses browser-generated ECDH key pairs and AES-GCM encryption, with separate derivation contexts for text and file transfers. The pairing model avoids public file links and distinguishes session states to handle reconnections securely.

I have been working on a small browser handoff tool. The use case is intentionally narrow: open a page on one device, scan a QR code with another device, then move live text or one selected file between the two browsers without creating an account, installing an app, or using a cloud drive. This post is less a launch announcement and more a build note. The interesting part was not drawing a QR code. It was deciding what the pairing model should promise, what it should not promise, and how to keep the browser UX understandable while avoiding privacy claims that are too broad. Disclosure: I used AI editorial assistance while preparing this article draft. The technical claims are based on the implementation I worked on and should be checked against the live code before publishing. The first design choice was to avoid public file links. Public links are convenient, but they also create a bigger surface area: For this tool I wanted a live, pair-only workflow instead. Both browsers are present at the same time. One browser shows a QR code, the second browser scans it, and the session exists for that pair. That constraint makes the product less flexible, but it also makes the mental model simpler: The QR code does not need to contain a secret payload. It can contain a short pairing URL such as: https://example.com/?i=<pair-id The pair id is a rendezvous handle and a short-lived join handle, not an encryption key. It tells the service which WebSocket clients should be connected. Someone who sees it while the pair is open may be able to attempt joining as the other browser, so the QR code still deserves normal care. What the pair id does not do is decrypt an already-derived browser-to-browser ciphertext by itself. That distinction matters because QR codes are visible. They can be captured by a camera, screenshot, screen share, or browser history. If the QR code itself is the secret, then the UI needs to treat it as secret material. If the QR code is just a rendezvous id, the encryption story can move into browser-generated keys. For text and file bytes, the current implementation uses browser-generated P-256 ECDH key pairs through the Web Crypto API. Each browser creates its own key pair. The public keys are exchanged through the pairing channel. The shared secret is then used as input material for derived AES-GCM keys. At a high level: Browser A creates ECDH key pair Browser B creates ECDH key pair Both exchange public keys through the pairing service Both derive shared key material Browser A encrypts before sending Browser B decrypts after receiving For text and file transfer, separate derivation context strings are useful. They keep the implementation honest about key separation: icyzip/text/ecdh/v2 icyzip/file/ecdh/v1 The exact labels are implementation details, and they can change as the design evolves. The useful part is treating text and file encryption as separate contexts, so a future change in one path does not accidentally depend on assumptions from the other. One mistake I wanted to avoid was treating "paired" as equivalent to "trusted forever." The browser context can disappear, the phone can suspend the tab, and the network can reconnect through a fresh WebSocket. The key and session state need explicit rules for those lifecycle events. Otherwise a reconnect path can accidentally look like a hostile peer or a broken key exchange even when the user only switched apps for a moment. That means the UI should not just say "failed." It should distinguish at least three cases: The cryptographic state machine and the product copy need to agree. If a mismatch means "scan a new QR code," the UI should say that directly. The file path needs different thinking than the text path. Text messages are small. They can be encrypted as a single payload and rendered into a shared field. Files are bigger, need progress, need cancellation behavior, and should avoid buffering everything in memory where practical. The current file design is still deliberately limited: one selected file in a live session. That avoids a lot of product and security questions: The sender encrypts file chunks in the browser, then the service routes encrypted bytes to the paired browser. The receiver decrypts in the browser. If decryption fails, the transfer should fail closed rather than trying to show partial content as if it succeeded. The browser APIs also shape the product more than I expected. A desktop browser, Android Chrome, Android Firefox, and embedded WebView-like browsers do not all behave the same around backgrounding, clipboard access, file inputs, downloads, and memory pressure. A feature that looks finished in two desktop tabs may still be brittle in the actual phone-to-laptop path. For this kind of tool I now prefer proving the narrow path on real devices before adding broader features. Multiple files, background retries, cross-session history, or resumable transfers all sound useful, but each one expands the set of states the user has to understand. This is the part that is easy to overstate in marketing copy. Browser-side encryption for text and file bytes does not mean the service sees nothing. The routing service still has operational visibility. Depending on the implementation, it may see metadata such as: Some of those can be reduced or changed, but they do not vanish just because payload bytes are encrypted. I have found it healthier to write the product copy around that limitation instead of trying to sound more private than the system really is. The claim I am comfortable with is narrow: Current browser clients encrypt live text and file bytes before they leave the browser. The service still handles routing and can see metadata. That is less catchy than "the server sees nothing", but it is much easier to defend. There is also a difference between payload confidentiality and abuse resistance. A relay that cannot read file bytes may still need enough operational signal to rate-limit, debug broken sessions, or understand whether a launch channel is producing real pairings instead of empty traffic. The tradeoff should be explicit, because "collect nothing" is often not the same thing as "operate responsibly." A QR-paired browser tool lives or dies on tiny UI details. The user should not need to understand ECDH, AES-GCM, metadata, or relay behavior. They need to know which device is waiting, which device should scan, whether the pair is connected, and whether the transfer finished. Practical things that helped: The mobile flow is especially important. A QR tool can look good on a desktop screenshot and still be awkward if the phone view makes the user scroll past the action they need. For a tiny product, analytics can easily become more invasive than the product itself. I try to focus on aggregate operational signals: For promotion channels, I care more about whether real pairings happen than raw clicks. A directory listing or launch post that brings a small number of people who actually pair two devices is more useful than a large number of passive page views. This also changes how I read advertising or launch-page numbers. A click is not a success event. For this product the useful signal is closer to: php page view - second device joins - pair connected - file or text transfer completes The exact funnel does not need invasive tracking to be useful. Aggregate counters can still reveal whether people understand the pairing flow. I am still watching a few design questions: If you want to see the specific flow that prompted these notes, the project is here: I am especially interested in technical feedback on the mobile lifecycle edge cases: backgrounded tabs, reconnects, and how explicit the UI should be when a new QR scan is required.