WhatsApp phone-number linking on passkey-protected accounts (companion WebAuthn)

[MaxGhenis]

Split out from #77 / PR #78, which shipped phone-number pairing but hit this on a real account.

What happens

On an account with a WhatsApp passkey, code linking gets all the way through registration — the phone accepts the typed code and companion_finish returns ok — and then the server sends passkey_prologue_request with a WebAuthn challenge (rpId whatsapp.com, 10-minute timeout). The companion must answer with a real WebAuthn assertion. We can't produce one: the passkey lives in the user's phone/keychain, and platform WebAuthn APIs (rightly) won't let a third-party app assert for someone else's rpId. The bridge now surfaces this clearly ("account is protected by a passkey — scan the QR code instead") instead of idling silently.

whatsmeow gained the protocol plumbing on 2026-06-30 (pair: add support for passkeys: events.PairPasskeyRequest, SendPasskeyResponse, SendPasskeyConfirmation) — we're on that version. What's missing is the authenticator side.

Options to investigate

1. Native macOS ceremony via the Swift app — AuthenticationServices can do cross-site passkey assertions only for associated domains; whatsapp.com won't associate us. Likely dead end, but worth confirming whether the hybrid (phone-scan QR / CTAP2 hybrid transport) flow is reachable from a non-associated app.
2. Hand off to the browser — open a local page that runs navigator.credentials.get with the challenge... same rpId restriction applies (page origin must match rpId). Dead end unless WhatsApp's own web flow can be leveraged.
3. Track upstream — watch how mautrix-whatsapp / Beeper wire PairPasskeyRequest in practice; if they find a supported handoff (e.g. the pairing_handoff_proof path pushing the ceremony to the primary phone), mirror it.
4. Documented workaround (current state): QR linking is unaffected by the passkey step; failing that, temporarily remove the passkey (WhatsApp → Settings → Account → Passkeys), link, re-add.

Until resolved, the UI error message + runbook guidance are the mitigation.

[Ramatweb]

Hi Max, I found this issue while looking into WhatsApp companion pairing. I understand the blocker is the WebAuthn assertion for whatsapp.com rather than the protocol plumbing itself. If you're looking for someone to help investigate possible pairing handoff flows, test implementations, or prototype around the new PairPasskeyRequest events, I'd be happy to contribute. Let me know if additional development support would be useful.

You can contact me here;
oseniramat123@gmail.com

[MaxGhenis]

Live confirmation (2026-07-05) — this is a hard block, not a bug we can fix

Reproduced against the real account after the user removed their WhatsApp passkey:

• QR scan now succeeds and advances to the passkey ceremony (previously it died earlier with "couldn't link device").
• The phone shows "Continue on your other device" — the WebAuthn cross-device/hybrid prompt.
• whatsmeow's QR channel surfaces a passkey-request event; our bridge sets last_error: "passkey-request" and stops, so nothing appears in the app.

Why we're stuck, definitively: completing the ceremony requires calling SendPasskeyResponse(ctx, *types.WebAuthnResponse) with a valid WebAuthn assertion (clientDataJSON + authenticatorData + signature) for rpId = whatsapp.com. There is no handoff variant in the API that skips the assertion — even the pairing_handoff_proof branch still marshals and sends webauthn_assertion. To produce that assertion we'd need either (a) a whatsapp.com passkey credential we can access (we don't have one, and platform WebAuthn won't let a non-associated app assert for someone else's rpId), or (b) a hybrid/caBLE transport to relay the ceremony to the user's phone — which whatsmeow does not implement. "Continue on your other device" is the phone offering to be that roaming authenticator, but there's no client-side WebAuthn stack here to receive the result.

Also key: the official WhatsApp Desktop app fails to link this same account too — and the passkey step is still demanded after the user removed their stored passkey. So this is a server-side / account-state escalation (very likely triggered by ~10+ failed link attempts over two days), not something a better companion implementation would solve.

Conclusion: no code change in OpenMessage (or any whatsmeow-based bridge) can link this account while WhatsApp mandates passkey device-verification. The path is account-side recovery (get official WhatsApp Web/Desktop linking without a passkey prompt first). Keeping this open to track whether whatsmeow ever adds a hybrid-transport authenticator path.

Follow-up: fix the now-misleading in-app error string (it says "protected by a passkey / scan the QR instead", but it fires on QR too and after passkey removal).