fix(deps): patch baileys to restore WhatsApp device pairing (companion_reg_refresh)

[cloviscoli]

Problem

Linking a new WhatsApp device is currently impossible on Evolution — QR pairing never completes and the phone shows "couldn't link device / não foi possível conectar no momento".

The root cause is upstream and not an Evolution bug: around 2026-07-28 WhatsApp added a new stage to the companion-registration flow, sending <notification type='companion_reg_refresh'> after the QR scan. Baileys acks it and discards it, so pair-success is never emitted and the QR ref pool drains. See WhiskeySockets/Baileys#2737 — reproduced independently in whatsmeow, which confirms it affects every open client.

Because companion_reg_refresh is absent from Baileys rc13, rc14 and master, no published Baileys release fixes this. The fix only exists as unmerged PRs.

This is the umbrella issue for those reports (#2696, #2679 and others here).

What this PR does

Uses the patches/ mechanism that already exists on develop (postinstall: patch-package, currently holding only a README) to vendor the fix until upstream merges it.

1. package.json / package-lock.json — bumps baileys from 7.0.0-rc13 to 7.0.0-rc14 (latest published).
2. patches/baileys+7.0.0-rc14.patch (new) — applies two upstream fixes:
   • Baileys#2765 — handles companion_reg_refresh by rotating the adv secret and re-rendering the QR without consuming a ref. This is what restores pairing.
   • Baileys#2602 — guards link_code_companion_reg: WhatsApp sends it in two shapes, and the one without the crypto fields crashes with Boom('Invalid buffer', 400) (that's #2600, which also breaks the pairing-code flow).

The patch touches only 4 files (Socket/messages-recv.js, Socket/socket.js, Utils/companion-reg-client-utils.{js,d.ts}) — no source maps, no unrelated build noise — and applies cleanly against a vanilla baileys@7.0.0-rc14.

Verification

Tested on a real deployment (Evolution v2.3.7 base + this patch, Docker):

• Before: QR cycled every ~3.5 min, phone showed "couldn't connect", connection.update never reached open; requestPairingCode() crashed with Invalid buffer.
• After: paired on the second QR attempt, state=open, session stable, and a real inbound WhatsApp message was delivered through the webhook end-to-end.

I also posted the standalone Docker recipe in the linked comment for anyone who needs it before this lands.

Notes for maintainers

• This vendors unmerged upstream PRs, so it should be dropped as soon as Baileys releases the fix — the patch filename is version-pinned, so a future baileys bump will surface it naturally.
• Happy to retarget this at 7.0.0-rc13 instead if you'd rather not bump the dependency in the same PR; the patch just needs regenerating against that version.

Summary by Sourcery

Restore WhatsApp device and pairing-code support by updating Baileys and applying the required upstream fixes.

Bug Fixes:

• Restore WhatsApp device pairing by handling companion registration refresh notifications and preserving QR ref rotation.
• Prevent pairing-code flows from failing when companion registration messages lack expected cryptographic fields.

Enhancements:

• Vendor the required upstream Baileys fixes through a version-pinned patch until they are released upstream.

Build:

• Upgrade the Baileys dependency from 7.0.0-rc13 to 7.0.0-rc14.

[sourcery-ai]

Reviewer's guide (collapsed on small PRs)

Reviewer's Guide

Restores WhatsApp device pairing by upgrading Baileys to rc14 and applying a version-pinned patch for the new companion_reg_refresh notification and malformed/variant link-code registration payloads. Reviewers should verify patch-package installation, lockfile consistency, and compatibility with both QR and pairing-code flows; the patch should be removed once an upstream Baileys release includes these fixes.

Sequence diagram for restored WhatsApp device pairing

sequenceDiagram
    actor User
    participant WhatsApp
    participant PatchedBaileys
    participant Evolution

    User->>Evolution: Start QR pairing
    Evolution->>PatchedBaileys: Create pairing session
    PatchedBaileys-->>User: Display QR
    User->>WhatsApp: Scan QR
    WhatsApp->>PatchedBaileys: companion_reg_refresh
    PatchedBaileys->>PatchedBaileys: Rotate adv secret
    PatchedBaileys-->>User: Render refreshed QR
    WhatsApp->>PatchedBaileys: Pairing confirmation
    PatchedBaileys-->>Evolution: pair-success
    Evolution-->>User: connection.update open

    alt Pairing-code flow
        User->>Evolution: requestPairingCode()
        Evolution->>PatchedBaileys: requestPairingCode()
        WhatsApp-->>PatchedBaileys: link_code_companion_reg
        PatchedBaileys-->>Evolution: Pairing code or guarded response
    end

Loading

File-Level Changes

Change	Details	Files
Pin Baileys to the latest published rc14 release and vendor unmerged upstream pairing fixes as a version-specific postinstall patch.	Update the direct dependency from rc13 to rc14. Add a patch-package patch covering the companion registration refresh flow and link-code payload variants. Rotate the advertising secret and refresh QR state without consuming refs when WhatsApp sends companion_reg_refresh. Avoid invalid-buffer failures when link_code_companion_reg omits crypto fields. Keep the patch limited to four Baileys runtime/type-definition files and tied to the installed package version.	package.json package-lock.json patches/baileys+7.0.0-rc14.patch

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

Sourcery assessment

Needs a human reviewer. This changes the WhatsApp device-pairing authentication flow by rotating and persisting the advertising secret, then regenerating the QR code when the server retires the old secret. If the notification handling or QR refresh is wrong, legitimate pairing can fail or an existing pending pairing can become unusable; reverting the code does not restore any secret already rotated and persisted.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

[otaviovicario]

+1 on getting this merged — hitting the exact issue this PR addresses. Self-hosted v2.3.7, new device pairing via QR fails with WhatsApp's "can't connect new devices" error since late July, while existing sessions keep working fine. This is blocking new customer onboarding for us.

I can build this branch and test it against a real instance if that helps move it along — will report back with results either way.