Skip to content

feat(client): add client.pair() for wireless debugging - #593

Merged
koral-- merged 2 commits into
masterfrom
feat/client-pair
Nov 20, 2026
Merged

koral-- merged 2 commits into
masterfrom
feat/client-pair

Conversation

@koral--

@koral-- koral-- commented Nov 20, 2026 •

Copy link
Copy Markdown
Member

Fixes #529

Adds client.pair(address, code) and client.pair(host, port, code), the equivalent of adb pair <host>:<port> <code>. As with adb pair, the ADB server does the TLS/SPAKE2 pairing itself (platform-tools 30+). adbkit only sends the host query host:pair:<code>:<host>:<port>, the same one adb pair sends (StringPrintf("host:pair:%s:%s", password, host) in AOSP's commandline.cpp), and reads the outcome. It is built the same way as client.connect(). address is the host:port shown in the device's dialog ([ipv6]:port for IPv6), so it can be passed as is.

What the server actually replies

The server pairs in a service thread, so it answers OKAY as soon as that thread starts. The outcome follows:

  • Failure: a second status, FAIL, followed by the length-prefixed message. This is observed, not assumed (see below).
  • Success: a length-prefixed Successfully paired to <host:port> [guid=<guid>]. This format is taken from AOSP and has not been observed here, because that needs a real phone.
  • Servers older than platform-tools 30: reply FAIL immediately (unknown host service).

The command handles all of these:

Reply Result
OKAY + Successfully paired to … Resolves with { address, guid?, reply } (PairResult, exported).
OKAY + FAIL + message Rejects with Parser.FailError carrying the server's message.
FAIL + message Rejects with Parser.FailError.
OKAY + any other text Rejects with Parser.FailError carrying that text, so callers handle one error type.

A defensive branch also accepts OKAY OKAY <value>. The connection is ended on every outcome, including a reply that is cut short or times out.

Argument checks

These reject with a TypeError before any connection is opened:

  • a code that isn't a non-empty string, or contains : (the server splits the request at the first : after the code); a number gets its own message, since it loses a leading zero;
  • a port outside 1-65535;
  • a host that already includes the port in the three-argument form (use pair(address, code)), and an empty host.

An IPv6 host goes out in brackets (host:pair:<code>:[fe80::1]:37000); without them the server can't split host and port. The adb:command debug log shows the request with the code masked (host:pair:******:…).

The code is a string because pairing codes can start with 0. address is the pairing address the server reports, not a serial. The JSDoc and README make both points:

  • the server must be platform-tools 30+;
  • you call client.connect() with the device's connect port afterwards, not the pairing port.

Checks against the local ADB server (platform-tools 37.0.3, host queries only, no device involved)

Raw bytes from the server for host:pair:123456:127.0.0.1:1 (closed port):

OKAYFAIL0027Failed: Unable to start pairing client.

client.pair('127.0.0.1', 1, '123456') rejects after 22 ms (pair('[::1]:1', '123456') and pair('::1', 1, '123456') send [::1]:1 and get the same reply, so the server parses the bracketed form):

FailError: Failure: 'Failed: Unable to start pairing client.'

A local TCP listener that accepts and immediately drops the connection gives this raw reply:

OKAYFAIL0031Failed: Wrong password or connection was dropped.

client.pair() against it rejects with FailError: Failure: 'Failed: Wrong password or connection was dropped.'.

Other observations:

  • A port-less host (host:pair:123456:127.0.0.1) gives OKAYFAIL002eInvalid port while parsing address [127.0.0.1]. Not every failure starts with Failed:, so success is detected by the Successfully paired prefix rather than failure by Failed:.
  • An unroutable address (192.0.2.1:37000, TEST-NET-1) fails the same way after about 10 s; the JSDoc mentions the delay.
  • The adb 37.0.3 CLI itself prints error: protocol fault (couldn't read status message) for the closed-port case, so it doesn't parse this reply shape either.

Not tested end to end: a real pairing needs a phone with Wireless debugging on the same Wi-Fi network, so the success path is covered only by unit tests using the AOSP reply format.

Tests

test/adb/command/host/pair.mts, in the style of the connect tests:

  • the exact query written, with a leading-zero code
  • success with the guid parsed
  • success without a guid
  • the real OKAYFAIL… bytes rejecting with FailError
  • an OKAY + Failed: … reply rejecting with FailError
  • an immediate FAIL (old server)
  • OKAY OKAY <value>
  • unexpected data
  • an IPv6 host, bare or in brackets, sent in brackets
  • each invalid argument rejecting with TypeError, writing nothing and ending the connection
  • a cut-short reply ending the connection
  • the debug log masking the code
  • client.pair() with host:port, [ipv6]:port and host and port apart, and invalid arguments rejecting without connecting

Undoing the masking, the brackets or the final end() each makes a test fail. npm run lint, npm run compile and npm test pass (354 passing).

🤖 Generated with Claude Code

koral-- and others added 2 commits November 20, 2026 19:01
client.pair(host, port, code) sends host:pair:<code>:<host>:<port>, the
query `adb pair` sends, and lets the ADB server (platform-tools 30+) do
the pairing.

The server answers OKAY once its pairing thread starts, then either a
length-prefixed "Successfully paired to <host:port> [guid=<guid>]" or a
second status, FAIL, with the message ("Failed: Unable to start pairing
client.", "Failed: Wrong password or connection was dropped."). FAIL
replies reject with Parser.FailError; any other reply that isn't a
success rejects with an Error carrying the reply. The result type,
PairResult, holds the reported address, the guid and the raw reply.

Fixes #529

Signed-off-by: Karol Wrótniak <karol.wrotniak@droidsonroids.pl>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
From review:
- Put an IPv6 host in brackets; the server can't split fe80::1:37000.
- Reject, before connecting, a code that is not a non-empty string or
  contains ':' (the server splits the request at it), a port outside
  1-65535, and a host that already includes the port.
- Add pair(address, code), so the 'host:port' shown in the device's
  dialog can be passed as is, like connect() accepts it.
- Mask the code in the adb:command debug log.
- Reject a 'Failed: ...' reply with Parser.FailError, like a FAIL status.
- End the connection on every outcome, also a cut-short reply.
- Drop a comment claiming the FAIL check must come first.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Karol Wrótniak <karol.wrotniak@droidsonroids.pl>
@koral--
koral-- merged commit 9c8fe6d into master Nov 20, 2026
6 checks passed
@koral--
koral-- deleted the feat/client-pair branch November 20, 2026 18:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Wireless network pairing verification code

1 participant