Lessons from building a QR-paired browser handoff tool

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 product constraint

The first design choice was to avoid public file links.

Public links are convenient, but they also create a bigger surface area:

• someone can forward the link;
• the sender has to think about expiry;
• the product needs a clear answer for offline recipients;
• a shared URL can be copied into logs, chat history, browser history, and previews.

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:

• no account;
• no inbox;
• no public download page;
• no stored file queue;
• no long-lived share link.

Pairing with a short session id

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.

Browser-generated ECDH

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:

• waiting for the second browser;
• connected to the expected peer;
• disconnected or unable to verify the peer, in which case the user should pair again.

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.

File transfer is not just bigger text

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:

• no folder sync semantics;
• no resumable offline queue;
• no public archive;
• no multi-recipient fan-out;
• no account-based file history.

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.

Metadata does not disappear

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:

• connection timing;
• approximate client/network information;
• pair/session control identifiers;
• file name;
• file size;
• MIME or browser-provided type hint;
• encrypted wire size;
• chunk counts or chunk timing.

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."

UX lessons from QR pairing

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:

• show the QR code immediately;
• keep the fallback link short;
• make the connected state obvious;
• avoid hidden multi-step setup;
• keep file transfer to one clear action;
• keep privacy copy specific and close to the action;
• test with phone-to-laptop and laptop-to-phone flows, not only desktop browser tabs.

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.

What I monitor after launch

For a tiny product, analytics can easily become more invasive than the product itself. I try to focus on aggregate operational signals:

• page requests;
• successful pairings;
• completed file transfers;
• broad country distribution;
• obvious diagnostics or client errors.

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:

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.

Open questions

I am still watching a few design questions:

• Is "one file" too narrow, or does it keep the tool understandable?
• Should filename metadata be hidden or transformed, even if that makes the receiving UX worse?
• Is the privacy copy clear enough for non-technical users?
• Is QR pairing obvious enough when the first device is a phone rather than a laptop?

If you want to see the specific flow that prompted these notes, the project is here:

https://icyzip.com/

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.