fix(pair-code): correct link_code_pairing_nonce byte and close WA Web stage-2 gaps

[jlucaso1]

What

Makes phone-number pair-code linking (link_code_companion_reg) behave against the WhatsApp server, cross-checked against the captured WhatsApp Web bundle (WAWeb/Alt/DeviceLinking*.js, WA/Smax/*CompanionHello/Finish/RefreshCode*.js).

The full crypto path (PBKDF2 2<<16, AES-CTR ephemeral wrap, HKDF arg order for the bundle key + adv_secret, GCM tag placement, the pair-success HMAC) was audited against the bundle and already matched WA Web — the changes below cover the deviations and the hardening found in an adversarial review.

1. link_code_pairing_nonce wire byte

companion_hello sent the nonce as b"0" (ASCII 0x30). WA Web's Alt/DeviceLinkingIq.js sends new Uint8Array(1) — a single 0x00 byte — and whatsmeow sends []byte{0}. Now emits the zero byte.

2. Stage-2 notification handling

handle_pair_code_notification assumed every notification was a primary_hello and marked the flow Completed after the first. Brought in line with WA Web DeviceLinkingApi.handlePrimaryHelloInternal / handleAltDeviceLinkingNotification:

Gap	WA Web ref	Now
Dispatch by child stage	routes on t[0].attrs.stage	dispatches primary_hello vs refresh_code (unknown → ignore)
Verify link_code_pairing_ref	InvalidRefError	rejects a primary_hello whose ref ≠ the ref cached from companion_hello
~180s code validity	OldCodeError (I=180)	stamps code_generation_ts (before companion_hello, matching startAltLinkingFlow) and drops an out-of-window primary_hello
≤3 attempts per code	MaxPrimaryHelloError (T=3)	counts only genuine (ref-matching, in-window) attempts, checked before the bump so stale/foreign notifications can't exhaust the budget; state retained for retries
refresh_code stage	refreshAltLinkingCode / forceManualRefresh	new Event::PairingCodeRefresh { force_manual } (ref-gated) + Bot::on_pair_code_refresh helper

3. Concurrency + event hardening (adversarial-review follow-ups)

• Serialize stage 2. The transport dispatches notification stanzas on concurrent detached tasks, so two primary_hello for the same code could each derive a different random adv_secret and race SetAdvSecretKey (last-write-wins), desyncing the persisted secret from the companion_finish the server acts on → pair-success HMAC failure. The pair_code_state lock is now held across the whole of stage 2 (derive → persist → send), making concurrent notifications sequential — matching WA Web's single-threaded model.
• Accurate code timeout. Because code_generation_ts now starts before stage 1, the PairingCode event advertises the remaining window (not the full code_validity()), so a consumer's countdown can't outlast the real expiry.

Testing

• Regression tests driving the top-level handle_pair_code_notification: ref mismatch (rejected, no retry slot spent, state preserved), expired code (rejected, no slot), over-cap 4th attempt (rejected, counter bounded at max), a valid in-window retry reaching stage 2, stale mismatches not blocking the valid one, refresh_code dispatch/ignore + absent-force_manual default, and unknown-stage ignore. The nonce byte is guarded by the wacore companion_hello_iq_shape test.
• cargo test -p whatsapp-rust --lib pair_code (11) and cargo test -p wacore --lib pair_code (40) green; cargo fmt --all --check and cargo clippy -p whatsapp-rust -p wacore --tests clean.

Not in scope

No replication of WA Web's QPL markers or telemetry pings; no change to the QR pairing path or the pair-success crypto.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds PairingCodeRefresh handling end to end: event types, pair-code state and stage-2 guards, bot registration, and the stage-1 nonce wire-format change with matching tests.

Changes

Pairing code refresh and stage-2 retry handling

Layer / File(s)	Summary
PairingCodeRefresh event definition wacore/src/types/events.rs	Adds EventKind::PairingCodeRefresh and Event::PairingCodeRefresh { force_manual }, and extends Event::kind() mapping.
Pair code state machine and nonce format updates wacore/src/pair_code.rs	Adds PAIR_CODE_MAX_PRIMARY_HELLO_ATTEMPTS and max_primary_hello_attempts(), extends WaitingForPhoneConfirmation with primary_hello_attempt_count, changes the stage-1 nonce to a single zero byte, and updates the related test.
Stage-2 notification handling with retry/refresh guards src/pair_code.rs	Persists code generation timestamp and attempt count on pair_with_code; restructures handle_pair_code_notification to dispatch by stage; adds ref/expiry/attempt guards in handle_primary_hello; adds handle_refresh_code dispatching Event::PairingCodeRefresh; expands regression tests.
Bot handler registration src/bot.rs	Adds BotBuilder::on_pair_code_refresh, wiring EventKind::PairingCodeRefresh into on_event_for.

Estimated code review effort: 4 (Complex) | ~60 minutes

Possibly related PRs

• oxidezap/whatsapp-rust#202: Introduces the pair-code stage-2 flow that this PR extends with refresh handling and retry guards.
• oxidezap/whatsapp-rust#852: Covers bot event-handler registration and dispatch plumbing that on_pair_code_refresh builds on.

Suggested labels: api-design, breaking-change

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly summarizes the main changes: nonce byte correction and stage-2 pair-code handling fixes.
Description check	✅ Passed	The description is directly related to the PR and accurately describes the pair-code linking changes and follow-up hardening.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/whatsapp-rust-pair-code-bugs-ezguso

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

This PR corrects the link_code_pairing_nonce wire byte from ASCII '0' (0x30) to a single 0x00 byte, matching WA Web's new Uint8Array(1) and whatsmeow's []byte{0}. It also brings the stage-2 primary_hello handler up to WA Web parity: ref validation, ~180 s expiry check, and a 3-attempt cap all gate the attempt counter correctly, while refresh_code notifications are dispatched as a new PairingCodeRefresh event only when the ref matches the outstanding flow.

• Nonce fix (wacore/src/pair_code.rs): single 0x00 byte replaces b"0"; guarded by the updated companion_hello_iq_shape test.
• Stage-2 gaps (src/pair_code.rs): handle_pair_code_notification now dispatches on stage; ref, expiry, and cap checks precede the counter bump so stale/foreign notifications cannot exhaust the retry budget; the state lock is held across the full stage-2 pipeline to serialise concurrent notifications and prevent adv-secret races.
• New event + helper (wacore/src/types/events.rs, src/bot.rs): Event::PairingCodeRefresh { force_manual } and BotBuilder::on_pair_code_refresh expose the refresh signal to consumers.

Confidence Score: 5/5

The two targeted fixes are narrow and well-tested; all validation gates precede the attempt counter bump, and the previous reviewer concern about counter contamination is covered by an explicit assertion in the regression suite.

Both changes are self-contained and cross-checked against the WA Web bundle. The critical ordering (ref → expiry → cap → bump) is confirmed by seven targeted regression tests covering mismatch, expiry, over-cap, valid retry, refresh dispatch, absent attribute default, and unknown-stage ignore.

No files require special attention; src/pair_code.rs carries the most logic but the tests provide thorough guard coverage.

Important Files Changed

Filename	Overview
src/pair_code.rs	Stage-2 dispatcher added; ref validation, expiry check, and attempt cap all gate before the counter bump; lock intentionally held across PBKDF2 + persist + send for serialisation; comprehensive regression tests added
wacore/src/pair_code.rs	Nonce corrected from ASCII '0' (0x30) to a single zero byte (0x00) and two new fields added to PairCodeState; well-tested in companion_hello_iq_shape
wacore/src/types/events.rs	New PairingCodeRefresh event and EventKind variant added; dispatch in Event::kind() wired correctly
src/bot.rs	on_pair_code_refresh builder helper added; follows the same on_event_for pattern as peer helpers

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant App
    participant Client
    participant WA Server
    participant Phone

    App->>Client: pair_with_code(phone, code)
    Note over Client: stamp code_generation_ts
    Client->>WA Server: companion_hello IQ (nonce=0x00)
    WA Server-->>Client: pairing_ref
    Client->>App: "Event::PairingCode { remaining timeout }"
    App->>Phone: User enters 8-char code

    alt "stage = primary_hello"
        WA Server->>Client: notification (stage=primary_hello, ref, wrapped_ephemeral)
        Note over Client: acquire pair_code_state lock
        Client->>Client: "check ref == pairing_ref"
        Client->>Client: "check age <= 180s"
        Client->>Client: "check attempt_count < 3, then bump"
        Client->>Client: PBKDF2 decrypt (spawn_blocking)
        Client->>Client: prepare_key_bundle + persist adv_secret
        Client->>WA Server: companion_finish IQ
        Note over Client: release lock
        WA Server-->>Client: pair-success
    else "stage = refresh_code"
        WA Server->>Client: notification (stage=refresh_code, ref, force_manual)
        Client->>Client: check ref matches (brief lock)
        Client->>App: "Event::PairingCodeRefresh { force_manual }"
    else unknown stage
        WA Server->>Client: warn + ignore
    end

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant App
    participant Client
    participant WA Server
    participant Phone

    App->>Client: pair_with_code(phone, code)
    Note over Client: stamp code_generation_ts
    Client->>WA Server: companion_hello IQ (nonce=0x00)
    WA Server-->>Client: pairing_ref
    Client->>App: "Event::PairingCode { remaining timeout }"
    App->>Phone: User enters 8-char code

    alt "stage = primary_hello"
        WA Server->>Client: notification (stage=primary_hello, ref, wrapped_ephemeral)
        Note over Client: acquire pair_code_state lock
        Client->>Client: "check ref == pairing_ref"
        Client->>Client: "check age <= 180s"
        Client->>Client: "check attempt_count < 3, then bump"
        Client->>Client: PBKDF2 decrypt (spawn_blocking)
        Client->>Client: prepare_key_bundle + persist adv_secret
        Client->>WA Server: companion_finish IQ
        Note over Client: release lock
        WA Server-->>Client: pair-success
    else "stage = refresh_code"
        WA Server->>Client: notification (stage=refresh_code, ref, force_manual)
        Client->>Client: check ref matches (brief lock)
        Client->>App: "Event::PairingCodeRefresh { force_manual }"
    else unknown stage
        WA Server->>Client: warn + ignore
    end

Loading

_{Reviews (5): Last reviewed commit: "fix(pair-code): advertise remaining vali..." | Re-trigger Greptile}

[cubic-dev-ai]

1 issue found across 4 files

Confidence score: 3/5

• In src/pair_code.rs, the retry counter appears to increment before validating primary_hello reference/expiry, so stale or unrelated notifications can consume legitimate pair-code attempts and cause premature pairing failure for real users; move the increment to occur only after those checks pass (and add a regression test for stale-notification handling) before merging.

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[github-actions]

📦 Binary size report

Metric	main	PR	Δ
bin size (stripped)	10.77 MiB	10.77 MiB	+4.19 KiB (+0.04%) 🔺
bin .text	8.77 MiB	8.78 MiB	+4.06 KiB (+0.05%) 🔺
bin allocated (text+data+bss)	10.77 MiB	10.77 MiB	+4.17 KiB (+0.04%) 🔺
llvm-lines wacore	503,173	503,158	-15 (-0.00%) 🔽
llvm-lines wacore copies	17,243	17,243	0
llvm-lines whatsapp-rust lib	745,608	746,771	+1,163 (+0.16%) 🔺
llvm-lines whatsapp-rust lib copies	24,265	24,288	+23 (+0.09%) 🔺
deps crates (Cargo.lock)	466	466	0

.text per crate

Crate	main	PR	Δ
.text whatsapp_rust	1.60 MiB	1.61 MiB	+3.58 KiB (+0.22%) 🔺
.text wacore	528.64 KiB	528.64 KiB	0
.text wacore_binary	157.49 KiB	157.49 KiB	0
.text wacore_libsignal	178.30 KiB	178.73 KiB	+442 B (+0.24%) 🔺
.text wacore_appstate	156.42 KiB	156.42 KiB	0
.text wacore_noise	26.05 KiB	26.05 KiB	0
.text waproto	1.60 MiB	1.60 MiB	0
.text whatsapp_rust_sqlite_storage	509.25 KiB	509.25 KiB	0
.text whatsapp_rust_tokio_transport	43.61 KiB	43.61 KiB	0
.text whatsapp_rust_ureq_http_client	10.47 KiB	10.47 KiB	0
.text std	1.00 MiB	1.00 MiB	+35 B (+0.00%) 🔺
.text other deps	2.94 MiB	2.94 MiB	0

Top movers (cargo-bloat attribution)

Crate	main	PR	Δ
whatsapp_rust	1.60 MiB	1.61 MiB	+3.58 KiB (+0.22%)

Baseline: 4def65976 (latest main run) · Head: 419f89bff · Graphs

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/pair_code.rs`:
- Around line 356-363: The retry budget in
PairCodeUtils::handle_primary_hello_attempts is being incremented before
checking the cap, so a rejected attempt still mutates state and can push the
counter past the limit. Reorder the logic to check primary_hello_attempt_count
against PairCodeUtils::max_primary_hello_attempts() before incrementing, and
only increment when the attempt is still allowed; keep the existing warn! and
false return path for exhausted retries.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI (base), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: d03c0a98-ef54-4fab-9fc0-de0f17f21c88

📥 Commits

Reviewing files that changed from the base of the PR and between ed15bdb and 97fa1b1.

📒 Files selected for processing (2)

• src/pair_code.rs
• wacore/src/pair_code.rs

[cubic-dev-ai]

1 issue found across 2 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 1 file (changes from recent commits).

<sub>Requires human review: This PR modifies core pairing protocol logic: nonce byte change, stage-2 notification dispatch with attempt/expiry gates, and a new event type. Even with zero AI issues, the blast radius of a bug in pairing flow (auth, retry, or state machine) is high and requires human judgment.

Re-trigger cubic</sub>

Dismissed because a newer commit was pushed; Greptile will re-review the current head.

[cubic-dev-ai]

1 issue found across 1 file (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

Dismissed because a newer commit was pushed; Greptile will re-review the current head.

[cubic-dev-ai]

0 issues found across 1 file (changes from recent commits).

<sub>Requires human review: Changes to critical pairing logic: nonce byte, stage dispatch, ref validation, expiry, attempt limits, and new event/handler. Requires human review for correctness and security.

Re-trigger cubic</sub>

[codspeed-hq]

Merging this PR will not alter performance

✅ 183 untouched benchmarks

---

_{Comparing claude/whatsapp-rust-pair-code-bugs-ezguso (9214c31) with main (4def659)}