ExWapp.Pairing.LinkCode (ExWapp v0.1.2)

Copy Markdown View Source

Implements WhatsApp's phone-number (link-code) companion pairing protocol.

The request side wraps a fresh companion ephemeral public key with the eight-character pairing code. The finish side unwraps the primary phone's ephemeral key, derives the authenticated key bundle, rotates the ADV secret, and persists enough account state for the reconnect/login that follows.

Summary

Types

finish_result()
request_result()

Functions

crockford_encode(bytes)

Encodes bytes with WhatsApp's Crockford alphabet.

derive_pairing_code_key(pairing_code, salt)

Derives the AES key used to wrap link-code ephemeral public keys.

finish(store, notification)

Completes a pending link-code pairing from a server notification.

request(store, phone, opts \\ [], runtime_cfg \\ %{})

Starts a link-code pairing request and persists its ephemeral credentials.

Types

finish_result()

@type finish_result() :: %{
  jid: String.t(),
  node: ExWapp.Binary.Node.t(),
  adv_secret: binary(),
  data: map()
}

request_result()

@type request_result() :: %{
  code: String.t(),
  jid: String.t(),
  request_id: String.t(),
  node: ExWapp.Binary.Node.t()
}

Functions

crockford_encode(bytes)

@spec crockford_encode(binary()) :: String.t()

Encodes bytes with WhatsApp's Crockford alphabet.

derive_pairing_code_key(pairing_code, salt)

@spec derive_pairing_code_key(binary(), binary()) :: binary()

Derives the AES key used to wrap link-code ephemeral public keys.

finish(store, notification)

@spec finish(ExWapp.Store.t(), ExWapp.Binary.Node.t()) ::
  {:ok, finish_result()} | {:error, term()}

Completes a pending link-code pairing from a server notification.

The returned node is the companion_finish IQ that must be sent before the server's expected reconnect. Credential persistence is completed before this function returns.

request(store, phone, opts \\ [], runtime_cfg \\ %{})

@spec request(ExWapp.Store.t(), String.t(), keyword(), map()) ::
  {:ok, request_result()} | {:error, term()}

Starts a link-code pairing request and persists its ephemeral credentials.

A custom code follows the upstream contract: it must be exactly eight bytes. When omitted, five random bytes are encoded with WhatsApp's Crockford alphabet, producing an eight-character code.