DEV Community: IcyZip

Recovering QR-paired browser sessions after Android sleep

IcyZip — Sat, 01 Aug 2026 04:29:39 +0000

A browser-to-browser handoff can look simple in a five-minute test: open one page, scan its QR code on a phone, connect two WebSockets, and move some text. The harder test is leaving both devices alone for a day.

That exposed an uncomfortable failure mode in a QR-paired tool I maintain. Android could remain on Connecting indefinitely, while the desktop still showed old text and neither side made useful progress. Reloading the phone was not a real recovery path either: an expired pair could become Disconnected or Pairing unavailable without producing the fresh QR code the user needed.

The problem was not just a dropped socket. It was a client state model that did not distinguish transport recovery from pairing recovery clearly enough.

Disclosure: this article was prepared with AI editorial assistance from implementation and test notes. The behavior described below was checked against the deployed client plus automated and physical-device evidence.

A WebSocket is not the session

There are at least three different things in this flow:

the current browser transport;
the server-side pairing record;
the browser-side text and encryption state.

A WebSocket can disappear while the pairing remains valid. A pairing can expire while the page still has a stale socket object. The browser can also preserve a useful local draft after both of those are gone.

Treating those conditions as one generic “disconnected” state creates dead ends. A reconnect loop may keep opening transports for an identifier the server no longer knows. Conversely, immediately throwing away the pairing whenever a socket closes destroys a session that could have resumed normally.

The recovery policy became:

explicit user disconnect
    -> clear the old pair and its local draft
    -> leave the disconnected peer terminal
    -> give the initiating primary browser a clean new QR code

transport lost, pairing still valid
    -> replace the stale transport
    -> resume the stored pair
    -> re-establish browser key state

pairing unavailable or expired
    -> stop retrying the old identifier
    -> create a fresh primary pair
    -> show a fresh QR code
    -> preserve the useful local draft

The important distinction is intent. If the user pressed Disconnect, the old pair should stay disconnected rather than silently resume. The primary browser can still offer a clean new pairing. If Android merely slept, changed networks, or restored a tab, recovery of the existing pair should be automatic.

Wake events need to replace stale transports

Mobile browsers do not promise that a backgrounded page will resume with a useful network object. The JavaScript object may still exist even though the underlying connection can no longer make progress.

The client now listens to several lifecycle signals:

the document becoming visible again;
an online event;
a restored page through pageshow;
connection states that remain stuck in connecting, opening, error, or peer-offline.

Those signals do not merely call send() again. They request a bounded lifecycle restart, which replaces the old transport and lets the normal pairing handshake run again. A small pending guard prevents several nearly simultaneous wake signals from starting competing reconnect attempts.

This is deliberately different from an unbounded timer that retries forever. The page first asks whether automatic recovery is still allowed. Terminal states such as an explicit disconnect, an expired cryptographic state, or a key mismatch do not silently reopen themselves.

An unavailable pair must lead somewhere useful

Reaching the server successfully does not prove that the old pairing still exists. The server can answer that the requested pair is unavailable.

For the primary browser, that response now triggers a fresh-pair transition:

discard the unavailable pairing identifier;
clear key material tied to that identifier;
remove the stale pair from the URL;
ask the server for a new primary pairing;
render the new QR code;
show an explicit “new pairing created” instruction;
keep the local text draft visible.

That last point matters. Pairing state and user-authored text have different lifetimes. The old cryptographic relationship must not leak into the new pairing, but the text the user typed locally is still their work. Preserving it avoids turning network recovery into data loss.

Put the scanner inside the recovery path

Telling a phone user to “scan the QR code again” is incomplete if scanning means leaving the web app, finding the operating system camera, and hoping it opens the correct browser tab.

The recovery UI therefore includes an in-page camera scanner. It uses BarcodeDetector when the browser supports QR detection and requests the rear-facing camera through getUserMedia().

The scanner accepts only the intended pairing URL shape:

HTTPS;
the current IcyZip origin or another managed icyzip.com origin;
the root path;
a non-empty pairing identifier;
no embedded username, password, or custom port.

Lookalike hostnames, insecure URLs, unrelated paths, and foreign QR codes are rejected. After a successful scan, cancellation, or connection-state change, the camera track is stopped and detached from the video element.

Unsupported detection and denied camera permission are normal product states, not exceptions to hide. In those cases the UI keeps the manual pairing path available and explains why the camera scanner cannot continue.

Capability beats user-agent guessing

The same investigation produced a related Android lesson around clipboard access.

One physical Android Firefox installation exposed navigator.clipboard, which made the feature look available. In practice it rejected the clipboard-read permission name and did not return clipboard text even from a direct user click after another Android application had populated the platform clipboard.

The correct response was not another browser-name exception. The Paste action is now exposed only when the browser can prove the required permission capability as prompt or granted. Missing or rejected permission-query support leaves the action hidden, while the rest of the connected text UI remains usable.

An API existing on window is not the same as an end-to-end capability. Product controls should follow the capability that was actually proven.

Recovery also has a cryptographic boundary

The pairing URL contains a rendezvous identifier, not the text or file encryption key. Current browser clients create P-256 ECDH key pairs and derive separate text and file keys with HKDF-SHA-256 for AES-GCM.

That means reconnect logic must preserve the right browser state for a valid pair, but must not carry derived trust across an unavailable pairing into a newly created one. A fresh QR code represents a fresh pairing and a fresh browser key exchange.

Payload encryption also does not erase metadata. The relay still handles routing and can observe operational information such as timing, connection details, message sizes, and file-offer metadata. Recovery copy and privacy copy have to describe the same system.

Test the state transitions, not just the labels

It would be easy to make the bug appear fixed by hiding Connecting and showing a QR code unconditionally. That would be a false green if valid sessions stopped resuming or text stopped moving afterward.

The recovery tests therefore assert forward progress as well as UI state. They cover:

replacement of a stale socket after a simulated Android wake;
automatic resume when the pairing remains valid;
creation of a different pairing identifier when the old one is unavailable;
removal of the stale identifier from the address bar;
preservation of the local text draft;
a visible fresh QR code and rescan instruction;
accepted and rejected QR-origin cases;
unsupported and camera-denied scanner fallbacks;
camera-track shutdown after a successful scan;
bidirectional text exchange after recovery;
explicit disconnect invalidating the old pair while the primary browser offers a fresh QR code.

The browser-emulated cases are supplemented by a real older Android phone because mobile lifecycle and clipboard behavior are exactly where desktop-only tests become overconfident.

The broader lesson

Connection recovery is not one retry function. It is a product state machine spanning transport state, server pairing state, browser-local work, cryptographic identity, and explicit user intent.

Once those are modeled separately, the UI decisions become clearer:

retry a transport when the session is still valid;
create and explain a fresh pairing when it is not;
preserve user-authored work without preserving stale trust;
offer an in-context scanner, but keep a non-camera fallback;
prove that recovered sessions can still move data.

The current behavior and its security/metadata boundaries are live in IcyZip's implementation notes.

Lessons from building a QR-paired browser handoff tool

IcyZip — Thu, 25 Jun 2026 19:50:00 +0000

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.