KarpelesLab / libwallet / 25715271438

24%

push

github

ClawdWallet:pair — Stage 1 deep-link agent verification

Adds a single Dart-facing call (LibwalletClient.clawdWallet.pair(url)) that
takes a clawd://pair?agent=...&token=... URL, drives the one-round-trip
Spot handshake, and returns a verified AgentIdentity (or throws a typed
PairingException). The host app never speaks Spot — libwallet owns the
protocol, the app owns the UX. Mirrors how Wallet:initiateKeygen splits
the keygen flow.

Wire contract: tibaneapp/docs/clawdwallet-pairing.md.

Go side (wltwallet/pair.go):
- Parses+validates the URL (scheme, path, agent k.<base64url> shape, token).
- Builds the {v, token, mobile_spot_id} body and sends it via spotlib's
  Query primitive to <agent-spot-id>/pair with a 15s timeout.
- Dispatches the response: success body → AgentIdentity, error body →
  one of the 4 contract codes (token_invalid / token_expired /
  token_consumed / bad_request). Plus 3 libwallet-internal sentinels
  for the failure modes the contract leaves to the implementation:
  url_malformed (caught locally, no Spot traffic), agent_unreachable
  (timeout / transport error, wraps the underlying cause via %w), and
  identity_mismatch (response's agent_spot_id != URL's agent param —
  treat as a redirection attack, do NOT return the identity).
- Each sentinel is errors.New("<code>") so the wire-level code is the
  Error() string the FFI layer surfaces verbatim to Dart.

Dart side:
- AgentIdentity model with the four contract fields. Capabilities is
  opaque (Map<String, dynamic>); unknown keys round-trip.
- PairingException hierarchy: abstract base + 7 typed subclasses keyed
  to the Go sentinels. PairingIdentityMismatchException is flagged as
  security in the docstring so apps render it differently from the
  user-error cases.
- ClawdWalletApi.pair() catches LibwalletException, inspects .message,
  and re-throws the typed PairingException. Substring match handles
  %w-wrapped Go errors. Unknown codes fail closed as
  PairingBadRequestExcepti... (continued)

70 of 109 new or added lines in 1 file covered. (64.22%)

3332 of 15872 relevant lines covered (20.99%)

119.48 hits per line