fix(pair-code): canonicalize companion_platform_display OS to a server-safe set

[jlucaso1]

What

Fixes a second, orthogonal blocker for phone-number pair-code linking, found by testing live against the WhatsApp server (a pre-auth companion_hello probe comparing byte-for-byte with a working WhatsApp Web capture). Follow-up to #976 (the nonce fix).

The pair-code companion_hello server rejects a non-OS companion_platform_display with bad-request. The lib derived that field's OS from DeviceProps::os, which a consumer may set to an arbitrary branding string — so e.g. os = "Veloz" produced "Chrome (Veloz)" and pairing failed with a persistent 400. QR pairing is unaffected: it never sends this field, so it tolerates arbitrary branding.

Empirically confirmed: with the #976 nonce fix alone (os = "Veloz") → bad-request; changing only the OS to a real value ("Linux") → HTTP 200, code emitted, primary phone received the notification.

The fix

WA Web only ever emits a real OS name from its UA parser (WAWebBrowserInfo().os → ua-parser-js getOS().name). Model that as a small, closed CompanionOs enum in wacore/src/companion_reg.rs:

• wire_str() → the canonical ua-parser spelling ("Windows", "Mac OS", "Linux", "Android", "iOS").
• classify() → fuzzy, case-insensitive parse. Distinctive names match by substring; short ambiguous tokens ("ios", "arch", "cros") match whole-word so branding like "KaiOS", "March", "Search", "across" doesn't false-match. Chrome OS / distros fold to Linux; from_hint() = classify-or-Linux.

companion_platform_display routes the OS through CompanionOs::from_hint(os).wire_str(), so the default path can never emit a server-rejected string.

Kept deliberately conservative. Live testing showed the server is currently lenient (it also accepts Ubuntu, Fedora, Mac, macOS verbatim), but collapsing to a small guaranteed-accepted set is robust against that leniency changing. iPad folds to iOS, since older UA parsers report iPad as "iOS" and "iPadOS" isn't a confirmed-accepted value.

Flexibility: opt-in OS override

Because the default coercion drops real-but-non-canonical names the server does accept (e.g. Ubuntu), there's an escape hatch for advanced callers: PairCodeOptions::display_os: Option<String>. When set (non-empty) the OS is sent verbatim, bypassing coercion; None keeps the safe default. It complements the existing platform_id (browser) override, so a caller controls both parts of Browser (OS). Documented as at-the-caller's-risk (a non-OS string is rejected with bad-request); an all-whitespace value is ignored so we never emit an empty OS.

Error-handling + docs (no speculative behavior)

• Corrects the false doc that caused the passthrough ("Server validates only length; there is no browser whitelist" — the pair-code server does validate the OS).
• Warns once (process-gated) when a branding os is coerced, so a consumer sees why their branding didn't ride through; skipped when display_os overrides.
• Documents that a pair-code bad-request (400) can be rate-limiting (throttled per phone number), not invalid input — indistinguishable in the response, so back off and retry rather than treat every 400 as fatal. No auto-retry and no hardcoded threshold (both server-tunable / unreliable to detect); any server backoff hint is preserved on the wrapped IqError.

Scope

Pair-code only. QR pairing does not send companion_platform_display, so its branding path (DeviceProps::os) is untouched, and QR-only consumers are unaffected.

Testing

• CompanionOs: wire_str canonical spellings, a classify/from_hint alias table (Windows/Mac/darwin/Ubuntu/Fedora/Arch/Chrome OS(+no-space)/CrOS/Android/iOS/iPad…), the "Veloz" → Linux regression, and the whole-word guards — "KaiOS", "March", "Search", "across" all stay unclassified → Linux via fallback (never via a false substring match).
• Override: verbatim display_os, override beats a branding props.os, all-whitespace falls back to coercion.
• Existing os = "Mac" display tests updated to canonical "Mac OS".
• cargo test -p wacore --lib companion_reg (22) + pair_code, cargo test -p whatsapp-rust --lib pair_code green; cargo fmt --all --check and cargo clippy -p wacore -p whatsapp-rust --tests clean.

Not in scope

Whether the persistent linked-device name on the phone comes from this field or from post-auth DeviceProps (which would decide if a dedicated branding field is worth adding) is left for a follow-up once probed — the coercion + opt-in override is the correct, safe behavior regardless.

[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

wacore now canonicalizes OS hints through a new CompanionOs enum and uses that result in companion_platform_display. pair_code.rs re-exports the enum, updates pairing docs for bad-request rate-limiting, and warns when an OS hint is unrecognized before coercing it to Linux.

Changes

CompanionOs Canonicalization

Layer / File(s)	Summary
CompanionOs enum and classification logic wacore/src/companion_reg.rs	New CompanionOs enum with wire_str, classify, and from_hint methods maps free-form OS hints to canonical server wire strings, defaulting unrecognized inputs to "Linux".
Wire canonicalization wiring and tests wacore/src/companion_reg.rs	companion_platform_display now canonicalizes OS via CompanionOs::from_hint(os).wire_str(); tests update the Mac expectation to "Mac OS" and add coverage for alias handling, branding fallback, and canonical display output.
Pairing flow re-export, docs, and warning src/pair_code.rs	Re-exports CompanionOs; expands PairError and pair_with_code docs to note bad-request may indicate per-number rate-limiting; adds a warning log when device OS can't be classified before coercion to "Linux".

Estimated code review effort: 2 (Simple) | ~12 minutes

Possibly related PRs

• oxidezap/whatsapp-rust#202: Touches the same pair-code flow in src/pair_code.rs, including Client::pair_with_code.
• oxidezap/whatsapp-rust#593: Also changes companion_platform_display, the same output path this PR canonicalizes further.
• oxidezap/whatsapp-rust#595: Modifies companion_platform_display formatting alongside client-type display logic.

Suggested labels: api-design, size-increase-ok

🚥 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 and concisely summarizes the main change: canonicalizing pair-code OS values to a server-safe set.
Description check	✅ Passed	The description is directly related to the changeset and accurately describes the pair-code OS canonicalization and error-handling updates.

✨ 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 canonicalizes the OS component of companion_platform_display for pair-code linking, fixing persistent bad-request (400) rejections when DeviceProps::os held a branding string. It is an orthogonal, targeted fix that does not touch QR pairing.

• Introduces CompanionOs enum in wacore/src/companion_reg.rs with wire_str(), classify() (fuzzy, case-insensitive, with whole-word guards for ambiguous tokens), and from_hint() (classify-or-Linux fallback); splits the old companion_platform_display into a safe canonicalizing variant and a new companion_platform_display_raw escape hatch.
• Adds PairCodeOptions::display_os: Option<String> so advanced callers can send a verbatim OS (e.g. \"Ubuntu\") while the default path is always server-safe; a once-per-process warn! fires when a branding string is silently coerced.
• Updates docs and error variants to document that bad-request from the server may be rate-limiting, not just invalid input.

Confidence Score: 5/5

Safe to merge — the fix is narrowly scoped to pair-code OS canonicalization, the classify logic is sound and well-tested, and QR pairing is completely unaffected.

All changed paths are covered by dedicated tests including regression cases (Veloz→Linux, KaiOS not matching iOS, ChromeOS no-space). The escape hatch (display_os) is correctly guarded against whitespace. No panics, no data races on the Once guard, and the coercion can never emit an empty or server-rejected string by default.

No files require special attention.

Important Files Changed

Filename	Overview
wacore/src/companion_reg.rs	Introduces CompanionOs enum with wire_str/classify/from_hint, and splits companion_platform_display into a safe canonicalizing variant and a verbatim _raw escape hatch. Logic is correct; ChromeOS (no-space) now handled; classify ordering and whole-word guards are sound.
wacore/src/pair_code.rs	resolve_companion_platform correctly handles the new display_os override — non-empty trimmed value goes verbatim through companion_platform_display_raw, whitespace/None falls back to the safe coercion path. PairCodeOptions gains display_os with correct Default impl.
src/pair_code.rs	Adds once-per-process branding OS coercion warning and re-exports CompanionOs. Static Once guard is correctly scoped; warning fires after resolve_companion_platform with a redundant classify call (minor). Doc updates for RequestFailed rate-limit semantics are accurate.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Caller
    participant Client as Client::pair_code
    participant RCP as resolve_companion_platform
    participant CPD as companion_platform_display
    participant COS as CompanionOs
    participant CPR as companion_platform_display_raw
    participant WA as WhatsApp Server

    Caller->>Client: pair_code(options, ...)
    Client->>RCP: "&options, &device_props"
    alt "display_os = Some(non-empty)"
        RCP->>CPR: id, raw_os (verbatim)
        CPR-->>RCP: Browser (raw_os)
    else "display_os = None / whitespace"
        RCP->>CPD: id, props.os
        CPD->>COS: from_hint(os)
        COS-->>CPD: canonical_os (Windows/MacOs/Linux/Android/Ios)
        CPD->>CPR: id, canonical_os.wire_str()
        CPR-->>RCP: Browser (Canonical OS)
    end
    RCP-->>Client: (platform_id, display_string)
    Note over Client: OS_COERCE_WARNED.call_once if branding os coerced and no override
    Client->>WA: "companion_hello IQ (companion_platform_display = display_string)"
    WA-->>Client: 200 OK + pair code (or bad-request if invalid)
    Client-->>Caller: Ok(8-char code)

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 Caller
    participant Client as Client::pair_code
    participant RCP as resolve_companion_platform
    participant CPD as companion_platform_display
    participant COS as CompanionOs
    participant CPR as companion_platform_display_raw
    participant WA as WhatsApp Server

    Caller->>Client: pair_code(options, ...)
    Client->>RCP: "&options, &device_props"
    alt "display_os = Some(non-empty)"
        RCP->>CPR: id, raw_os (verbatim)
        CPR-->>RCP: Browser (raw_os)
    else "display_os = None / whitespace"
        RCP->>CPD: id, props.os
        CPD->>COS: from_hint(os)
        COS-->>CPD: canonical_os (Windows/MacOs/Linux/Android/Ios)
        CPD->>CPR: id, canonical_os.wire_str()
        CPR-->>RCP: Browser (Canonical OS)
    end
    RCP-->>Client: (platform_id, display_string)
    Note over Client: OS_COERCE_WARNED.call_once if branding os coerced and no override
    Client->>WA: "companion_hello IQ (companion_platform_display = display_string)"
    WA-->>Client: 200 OK + pair code (or bad-request if invalid)
    Client-->>Caller: Ok(8-char code)

Loading

_{Reviews (6): Last reviewed commit: "docs(pair-code): condense OS-coercion wa..." | Re-trigger Greptile}

[coderabbitai]

Actionable comments posted: 2

🤖 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 206-214: The warning in pair_with_code is emitted on every call
instead of being one-time, so update the OS coercion path in src/pair_code.rs to
gate the warn! behind a shared one-shot guard (for example a static Once or
equivalent flag) or otherwise lower its verbosity. Keep the check tied to the
existing CompanionOs::classify and device_snapshot.device_props.os handling so
unrecognized branding OS values only produce the coercion warning once across
retries, matching the documented behavior.

In `@wacore/src/companion_reg.rs`:
- Around line 139-146: CompanionOs is still using a manual wire-string path
instead of the generated wire enum support. Update the CompanionOs enum to
derive WireEnum and move the wire labels onto the variants so the generated
as_str() can replace the current wire_str() usage. Keep classify() as the
separate fuzzy parser for free-form OS hints, and adjust any CompanionOs call
sites to use the generated string accessor.

🪄 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: 648d8395-7515-4774-8721-d7fe3299930f

📥 Commits

Reviewing files that changed from the base of the PR and between 61df380 and 68441c1.

📒 Files selected for processing (2)

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

[cubic-dev-ai]

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

<sub>Requires human review: Modifies core pairing logic by introducing a canonical OS enum with fuzzy classification. Although targeted, this is a business logic change in a critical code path that could affect the behavior of pair-code linking for unrecognized OS strings.

Re-trigger cubic</sub>

[cubic-dev-ai]

1 issue found and verified against the latest diff

Confidence score: 4/5

• In wacore/src/companion_reg.rs, using a raw contains("ios") check can misclassify non-iOS hints (for example KaiOS) as iOS, which may skip the intended unknown→Linux fallback and produce incorrect platform handling at runtime — tighten the match to a tokenized or anchored iOS check before merging.

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

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 2 files (changes from recent commits).

<sub>Auto-approved: Canonicalizes a free-form OS string to a small server-safe set for pair-code linking. No business logic, infrastructure, or API changes; confined to a single enum in wacore. The companion_platform_display path is isolated to pair-code only (QR is unaffected).

Re-trigger cubic</sub>

[github-actions]

📦 Binary size report

Metric	main	PR	Δ
bin size (stripped)	10.76 MiB	10.77 MiB	+4.06 KiB (+0.04%) 🔺
bin .text	8.77 MiB	8.77 MiB	+3.56 KiB (+0.04%) 🔺
bin allocated (text+data+bss)	10.76 MiB	10.77 MiB	+4.06 KiB (+0.04%) 🔺
llvm-lines wacore	503,177	504,285	+1,108 (+0.22%) 🔺
llvm-lines wacore copies	17,244	17,275	+31 (+0.18%) 🔺
llvm-lines whatsapp-rust lib	745,528	745,748	+220 (+0.03%) 🔺
llvm-lines whatsapp-rust lib copies	24,271	24,280	+9 (+0.04%) 🔺
deps crates (Cargo.lock)	466	466	0

.text per crate

Crate	main	PR	Δ
.text whatsapp_rust	1.60 MiB	1.60 MiB	-1.14 KiB (-0.07%) 🔽
.text wacore	528.83 KiB	529.79 KiB	+981 B (+0.18%) 🔺
.text wacore_binary	157.49 KiB	157.49 KiB	0
.text wacore_libsignal	178.73 KiB	178.73 KiB	0
.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	512.98 KiB	512.98 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	1020.03 KiB	1021.39 KiB	+1.37 KiB (+0.13%) 🔺
.text other deps	2.94 MiB	2.95 MiB	+2.28 KiB (+0.08%) 🔺

Top movers (cargo-bloat attribution)

Crate	main	PR	Δ
prettyplease	1.97 KiB	3.46 KiB	+1.49 KiB (+75.56%)
std	1020.03 KiB	1021.39 KiB	+1.37 KiB (+0.13%)
whatsapp_rust	1.60 MiB	1.60 MiB	-1.14 KiB (-0.07%)

Baseline: a3c81c3c1 (latest main run) · Head: 89a66f98d · Graphs

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

[cubic-dev-ai]

0 issues found across 3 files (changes from recent commits).

<sub>Auto-approved: Adds OS canonicalization for pair-code, fixing server rejection of non-OS display strings. Well-tested, low-risk, and includes an opt-out override.

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: New canonical OS enum with classifying logic, nonce comparison, and warnings introduces risk of WhatsApp server rejection or subtle bugs in core pairing flow.

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: Adds CompanionOs enum and updates wire format and error model; these core changes can break pairing and warrant domain-specific review.

Re-trigger cubic</sub>