Skip to main content

Shortcake Passkey Pairing

WhatsApp features a passkey-based companion linking protocol code-named Shortcake.

If a primary device (your phone) enforces passkey validation during device pairing (for example, directly after scanning a QR code or entering a pairing code), the server triggers a prologue request.

UDMODZ Edition fully supports the companion-side Shortcake handshake protocol when you configure a passkey signer.

How It Works​

  1. Prologue Request: The server sends a passkey_prologue_request IQ notification with WebAuthn options.
  2. WebAuthn Assertion: The client solves the WebAuthn challenge using a registered passkey.
  3. Commitment & Nonce Scheme: Ephemeral X25519 keys and nonces are generated and exchanged.
  4. Verification: A 5-letter Crockford32 code is generated on both the phone and the companion to verify identity.
  5. Encrypted Pairing: An AES-GCM encrypted envelope is sent to finalise connection setup.

Configuration​

To enable Shortcake, supply the signPasskeyAssertion option when calling makeWASocket. This function receives the server's raw WebAuthn options and should return the resolved credential assertion.

import makeWASocket from 'amiudmodz'
import { ShortcakeAssertionSigner } from 'amiudmodz/lib/Utils/shortcake'

// Your custom signer (e.g. interfacing with a YubiKey, TPM, 
// or an external authentication service)
const myPasskeySigner: ShortcakeAssertionSigner = async (requestOptions: Uint8Array) => {
  // 1. Decode WebAuthn options
  // 2. Prompt user/TPM to sign
  // 3. Return the result
  return {
    credentialId: new Uint8Array([...]),       // WebAuthn Credential ID
    webauthnAssertion: new Uint8Array([...])   // WebAuthn Signature/Assertion
  }
}

const sock = makeWASocket({
  auth: state,
  // Configure the passkey signer
  signPasskeyAssertion: myPasskeySigner
})

Connection Events & States​

When the Shortcake handshake starts, connection state updates are fired:

1. passkeyRequired State​

If the server demands a passkey but you have not configured signPasskeyAssertion, the connection emits a warning. You can listen for this to inform users they must log in on a device that supports passkeys:

sock.ev.on('connection.update', (update) => {
  if (update.passkeyRequired) {
    const { hasSigner } = update.passkeyRequired
    if (!hasSigner) {
      console.warn("A passkey is required by WhatsApp, but no signer was provided!")
    } else {
      console.info("Passkey required. Initiating Shortcake handshake...")
    }
  }
})

2. Verification Code Verification​

During pairing, a human-readable 5-digit verification code is derived. The library logs this code in the console so it can be compared with the code on the primary phone:

info [shortcake]: shortcake verification code code=K4B2M

If you need to display this code in a custom UI, you can intercept it from the logger.