Handshake Ledger app

Hardware-wallet app for Handshake (HNS). Derives Handshake addresses and signs
Handshake transactions, including name-auction covenants, on Ledger Stax, Flex,
Nano S+, Nano X and Apex+.

The design premise is that the host computer is untrusted: every APDU byte is
attacker-controlled, and the device's job is to be correct when the host lies.
Two failures outrank all others, and the code is shaped around them.

Signing something other than what the user approved. Any field the signature
commits to and the host can vary has to appear on the review screen, and
anything the screen cannot represent honestly is refused rather than shown under
a label that does not describe it. So the device signs SIGHASH_ALL only,
checked per input rather than once for the session; it displays a TRANSFER
covenant's destination, which decides who ends up owning the name and appears
nowhere else in the output; it shows a covenant's name hash when the plaintext
name cannot be verified against it; and it refuses covenant kinds it cannot
name, outputs whose values exceed their inputs, and declared input totals that
would overflow the fee arithmetic.

Misusing key material. Derivation paths are constrained to
m/44'/{5353..5356}'/account'[/change/index] in the app itself, not only by the
install manifest, because BOLOS terminates the app on an out-of-whitelist path
instead of returning an error. One coin type per signing session, since the
review renders every address under a single HRP.

Panics count too: set_panic!(exiting_panic) means a panic kills the app and
strands the session, so nothing unwraps on host-derived data and the session
ceilings are sized to the configured heap.

Consensus follows shd, the Swift Handshake node, which is the reference for the
sighash preimage, covenant item layouts and address encoding.

SIGN_TX is a PSBT-style state machine driven by P1 (BEGIN / ADD_INPUT /
ADD_OUTPUT / REVIEW / SIGN_INPUT): the host streams the transaction as
structured records, the device accumulates its own view of the values, shows one
review, then signs each input on demand.

Tests run under speculos in a container (./scripts/test), 66 of them, green on
all five devices. test_sign_tx_policy.py covers each refusal above and needs no
golden snapshots because every case is rejected before anything is drawn; the
snapshots that do exist are the record of what the user sees before approving.
tests/application_client/handshake_sighash.py is a deliberately independent
reimplementation of the sighash, used to verify real signatures.

Status: v0.1, pre-audit. Not for mainnet keys. Signing has not yet been
exercised on physical hardware.

Forked from LedgerHQ/app-boilerplate-rust (Apache-2.0).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

tests/application_client/README.md

@@ -0,0 +1,16 @@
+# Application client
+
+A small Python client for the Handshake Ledger app: enough to send APDUs,
+build the records `SIGN_TX` streams, and decode what comes back.
+
+- `handshake_command_sender.py`: APDU encoding and the `SIGN_TX` state machine
+  (BEGIN / ADD_INPUT / ADD_OUTPUT / REVIEW / SIGN_INPUT), plus the status words
+  from `src/main.rs::AppSW`.
+- `handshake_transaction.py`: payload builders and the covenant item layouts
+  from `shd/Sources/Covenants/CovenantData.swift`.
+- `handshake_response_unpacker.py`: response decoding. Note the app returns
+  **compressed** 33-byte public keys.
+- `handshake_sighash.py`: an independent BIP-143-style sighash over BLAKE2b-256,
+  written separately from the device's implementation so that a test failure
+  means the two disagree rather than that one implementation is self-consistent.
+- `py.typed`: marker for type checkers.

tests/application_client/handshake_command_sender.py

@@ -0,0 +1,150 @@
+"""APDU client for the Handshake Ledger app.
+
+Speaks the protocol the app actually implements: `SIGN_TX` is a state machine
+selected by P1 (BEGIN / ADD_INPUT / ADD_OUTPUT / REVIEW / SIGN_INPUT), not the
+chunked single-shot flow the Ledger boilerplate uses. See
+`src/handlers/sign_tx.rs` and `scripts/sign-tx`.
+"""
+
+from contextlib import contextmanager
+from enum import IntEnum
+from typing import Generator, List, Optional
+
+from ragger.backend.interface import BackendInterface, RAPDU
+from ragger.bip import pack_derivation_path
+
+CLA: int = 0xE0
+
+#: Data bytes per APDU. ADD_OUTPUT payloads above this are chunked with P2_MORE.
+MAX_APDU_DATA: int = 240
+
+
+class InsType(IntEnum):
+    GET_VERSION = 0x03
+    GET_APP_NAME = 0x04
+    GET_PUBLIC_KEY = 0x05
+    SIGN_TX = 0x06
+    SIGN_MESSAGE = 0x07
+
+
+class P1(IntEnum):
+    NONE = 0x00
+    #: GET_PUBLIC_KEY: show the address on-device before replying.
+    CONFIRM = 0x01
+    #: SIGN_TX sub-ops.
+    SIGN_BEGIN = 0x00
+    SIGN_ADD_INPUT = 0x01
+    SIGN_ADD_OUTPUT = 0x02
+    SIGN_REVIEW = 0x03
+    SIGN_INPUT = 0x04
+
+
+class P2(IntEnum):
+    LAST = 0x00
+    MORE = 0x80
+
+
+class Errors(IntEnum):
+    """Mirrors `AppSW` in src/main.rs."""
+
+    SW_DENY = 0x6985
+    SW_WRONG_P1P2 = 0x6A86
+    SW_WRONG_STATE = 0x6B00
+    SW_INS_NOT_SUPPORTED = 0x6D00
+    SW_CLA_NOT_SUPPORTED = 0x6E00
+    SW_COMM_ERROR = 0x6F00
+    SW_TX_DISPLAY_FAIL = 0xB001
+    SW_ADDR_DISPLAY_FAIL = 0xB002
+    SW_TX_WRONG_LENGTH = 0xB004
+    SW_TX_PARSING_FAIL = 0xB005
+    SW_TX_HASH_FAIL = 0xB006
+    SW_TX_SIGN_FAIL = 0xB008
+    SW_KEY_DERIVE_FAIL = 0xB009
+    SW_VERSION_PARSING_FAIL = 0xB00A
+    SW_BAD_DERIVATION_PATH = 0xB00B
+    SW_SWAP_FAIL = 0xC000
+
+
+def split_message(message: bytes, max_size: int) -> List[bytes]:
+    return [message[x:x + max_size] for x in range(0, len(message), max_size)]
+
+
+class HandshakeCommandSender:
+    def __init__(self, backend: BackendInterface) -> None:
+        self.backend = backend
+
+    # ── Simple queries ─────────────────────────────────────────────────────
+
+    def get_version(self) -> RAPDU:
+        return self.backend.exchange(cla=CLA, ins=InsType.GET_VERSION,
+                                     p1=P1.NONE, p2=P2.LAST, data=b"")
+
+    def get_app_name(self) -> RAPDU:
+        return self.backend.exchange(cla=CLA, ins=InsType.GET_APP_NAME,
+                                     p1=P1.NONE, p2=P2.LAST, data=b"")
+
+    def get_public_key(self, path: str) -> RAPDU:
+        return self.backend.exchange(cla=CLA, ins=InsType.GET_PUBLIC_KEY,
+                                     p1=P1.NONE, p2=P2.LAST,
+                                     data=pack_derivation_path(path))
+
+    @contextmanager
+    def get_public_key_with_confirmation(self, path: str) -> Generator[None, None, None]:
+        with self.backend.exchange_async(cla=CLA, ins=InsType.GET_PUBLIC_KEY,
+                                         p1=P1.CONFIRM, p2=P2.LAST,
+                                         data=pack_derivation_path(path)) as response:
+            yield response
+
+    # ── SIGN_TX state machine ──────────────────────────────────────────────
+
+    def sign_tx_begin(self, payload: bytes) -> RAPDU:
+        return self.backend.exchange(cla=CLA, ins=InsType.SIGN_TX,
+                                     p1=P1.SIGN_BEGIN, p2=P2.LAST, data=payload)
+
+    def sign_tx_add_input(self, payload: bytes) -> RAPDU:
+        return self.backend.exchange(cla=CLA, ins=InsType.SIGN_TX,
+                                     p1=P1.SIGN_ADD_INPUT, p2=P2.LAST, data=payload)
+
+    def sign_tx_add_output(self, payload: bytes) -> RAPDU:
+        """Send one output, chunking it across APDUs if needed."""
+        chunks = split_message(payload, MAX_APDU_DATA) or [b""]
+        rapdu = None
+        for i, chunk in enumerate(chunks):
+            p2 = P2.LAST if i == len(chunks) - 1 else P2.MORE
+            rapdu = self.backend.exchange(cla=CLA, ins=InsType.SIGN_TX,
+                                          p1=P1.SIGN_ADD_OUTPUT, p2=p2, data=chunk)
+        return rapdu
+
+    def sign_tx_review_sync(self) -> RAPDU:
+        """REVIEW without a navigator: only for cases the device rejects
+        before it puts anything on screen."""
+        return self.backend.exchange(cla=CLA, ins=InsType.SIGN_TX,
+                                     p1=P1.SIGN_REVIEW, p2=P2.LAST, data=b"")
+
+    @contextmanager
+    def sign_tx_review(self) -> Generator[None, None, None]:
+        """REVIEW: blocks on the user, so the caller drives the navigator."""
+        with self.backend.exchange_async(cla=CLA, ins=InsType.SIGN_TX,
+                                         p1=P1.SIGN_REVIEW, p2=P2.LAST,
+                                         data=b"") as response:
+            yield response
+
+    def sign_tx_input(self, index: int) -> RAPDU:
+        return self.backend.exchange(cla=CLA, ins=InsType.SIGN_TX,
+                                     p1=P1.SIGN_INPUT, p2=P2.LAST,
+                                     data=index.to_bytes(4, "big"))
+
+    # ── SIGN_MESSAGE ───────────────────────────────────────────────────────
+
+    @contextmanager
+    def sign_message(self, path: str, message: bytes) -> Generator[None, None, None]:
+        payload = (pack_derivation_path(path)
+                   + len(message).to_bytes(2, "little")
+                   + message)
+        with self.backend.exchange_async(cla=CLA, ins=InsType.SIGN_MESSAGE,
+                                         p1=P1.NONE, p2=P2.LAST,
+                                         data=payload) as response:
+            yield response
+
+    def get_async_response(self) -> Optional[RAPDU]:
+        return self.backend.last_async_response

tests/application_client/handshake_response_unpacker.py

@@ -0,0 +1,63 @@
+"""Response unpackers for the Handshake Ledger app.
+
+The app returns COMPRESSED (33-byte) secp256k1 public keys, unlike the Ledger
+boilerplate, which returns the 65-byte uncompressed form.
+"""
+
+from struct import unpack
+from typing import Tuple
+
+
+def _pop_sized(buffer: bytes, size: int) -> Tuple[bytes, bytes]:
+    return buffer[size:], buffer[0:size]
+
+
+def _pop_len_prefixed(buffer: bytes) -> Tuple[bytes, bytes]:
+    n = buffer[0]
+    return buffer[1 + n:], buffer[1:n + 1]
+
+
+def compress_pubkey(uncompressed: bytes) -> bytes:
+    """65-byte `04 || X || Y` to 33-byte `02|03 || X`."""
+    assert len(uncompressed) == 65 and uncompressed[0] == 0x04
+    prefix = 0x02 if uncompressed[64] % 2 == 0 else 0x03
+    return bytes([prefix]) + uncompressed[1:33]
+
+
+def unpack_get_app_name_response(response: bytes) -> str:
+    return response.decode("ascii")
+
+
+def unpack_get_version_response(response: bytes) -> Tuple[int, int, int]:
+    assert len(response) == 3
+    major, minor, patch = unpack("BBB", response)
+    return (major, minor, patch)
+
+
+def unpack_get_public_key_response(response: bytes) -> Tuple[bytes, bytes, str]:
+    """`pk_len(1) || pk(33) || cc_len(1) || cc(32) || addr_len(1) || addr`."""
+    response, pubkey = _pop_len_prefixed(response)
+    response, chaincode = _pop_len_prefixed(response)
+    response, address = _pop_len_prefixed(response)
+
+    assert len(pubkey) == 33, f"expected a compressed pubkey, got {len(pubkey)} bytes"
+    assert len(chaincode) == 32
+    assert len(response) == 0
+    return pubkey, chaincode, address.decode("ascii")
+
+
+def unpack_sign_input_response(response: bytes) -> Tuple[bytes, int, bytes]:
+    """`sig(64) || sighash_type(1) || pk_len(1) || pk(33)`."""
+    response, signature = _pop_sized(response, 64)
+    response, sighash = _pop_sized(response, 1)
+    response, pubkey = _pop_len_prefixed(response)
+
+    assert len(pubkey) == 33
+    assert len(response) == 0
+    return signature, sighash[0], pubkey
+
+
+def unpack_sign_message_response(response: bytes) -> Tuple[int, bytes, bytes]:
+    """`recovery_id(1) || sig(64) || pk(33)`, 98 bytes."""
+    assert len(response) == 98, f"expected 98 bytes, got {len(response)}"
+    return response[0], response[1:65], response[65:]

tests/application_client/handshake_sighash.py

@@ -0,0 +1,85 @@
+"""An independent BIP-143-style sighash for Handshake, for cross-checking the
+device's signatures.
+
+Deliberately a second implementation rather than a port of the device's: a test
+that reuses the code under test proves only that it is self-consistent. Field
+order and lengths follow `shd/Sources/Script/SigHash.swift::compute`.
+"""
+
+from hashlib import blake2b
+from typing import List, Sequence, Tuple
+
+
+def encode_varint(n: int) -> bytes:
+    """Deliberately duplicated rather than imported: this module is meant to be
+    an independent check, and it keeps the cross-check importable without ragger."""
+    if n < 0xFD:
+        return bytes([n])
+    if n <= 0xFFFF:
+        return b"\xfd" + n.to_bytes(2, "little")
+    if n <= 0xFFFFFFFF:
+        return b"\xfe" + n.to_bytes(4, "little")
+    return b"\xff" + n.to_bytes(8, "little")
+
+
+def blake2b_256(data: bytes) -> bytes:
+    return blake2b(data, digest_size=32).digest()
+
+
+def blake2b_160(data: bytes) -> bytes:
+    return blake2b(data, digest_size=20).digest()
+
+
+def p2wpkh_script_code(compressed_pubkey: bytes) -> bytes:
+    """OP_DUP OP_BLAKE160 <push20> <hash> OP_EQUALVERIFY OP_CHECKSIG.
+
+    Handshake uses OP_BLAKE160 (0xc0) where Bitcoin uses OP_HASH160 (0xa9).
+    """
+    return (b"\x76\xc0\x14"
+            + blake2b_160(compressed_pubkey)
+            + b"\x88\xac")
+
+
+def serialize_output(value: int,
+                     addr_hash: bytes,
+                     addr_version: int = 0,
+                     covenant_kind: int = 0,
+                     covenant_items: Sequence[bytes] = ()) -> bytes:
+    items = b"".join(encode_varint(len(i)) + i for i in covenant_items)
+    return (value.to_bytes(8, "little")
+            + bytes([addr_version, len(addr_hash)])
+            + addr_hash
+            + bytes([covenant_kind])
+            + encode_varint(len(covenant_items))
+            + items)
+
+
+def sighash_all(version: int,
+                inputs: List[Tuple[bytes, int, int]],
+                outputs: List[bytes],
+                locktime: int,
+                index: int,
+                script_code: bytes,
+                value: int) -> bytes:
+    """SIGHASH_ALL only, which is the one type the device signs.
+
+    `inputs` are (txid, vout, sequence); `outputs` are pre-serialized.
+    """
+    hash_prevouts = blake2b_256(b"".join(
+        txid + vout.to_bytes(4, "little") for txid, vout, _ in inputs))
+    hash_sequence = blake2b_256(b"".join(
+        seq.to_bytes(4, "little") for _, _, seq in inputs))
+    hash_outputs = blake2b_256(b"".join(outputs))
+
+    txid, vout, sequence = inputs[index]
+    preimage = (version.to_bytes(4, "little")
+                + hash_prevouts
+                + hash_sequence
+                + txid + vout.to_bytes(4, "little")
+                + encode_varint(len(script_code)) + script_code
+                + value.to_bytes(8, "little")
+                + sequence.to_bytes(4, "little")
+                + hash_outputs
+                + locktime.to_bytes(4, "little")
+                + (0x01).to_bytes(4, "little"))
+    return blake2b_256(preimage)

tests/application_client/handshake_transaction.py

@@ -0,0 +1,118 @@
+"""Builders for the structured records SIGN_TX streams to the device.
+
+Wire layouts are documented at the top of `src/handlers/sign_tx.rs`; the
+covenant item layouts mirror `shd/Sources/Covenants/CovenantData.swift`.
+"""
+
+from hashlib import sha3_256
+from typing import List, Sequence, Tuple
+
+from ragger.bip import pack_derivation_path
+
+SCRIPT_KIND_P2WPKH: int = 0x00
+SCRIPT_KIND_P2WSH: int = 0x01
+
+SIGHASH_ALL: int = 0x01
+SIGHASH_NONE: int = 0x02
+SIGHASH_SINGLE: int = 0x03
+SIGHASH_SINGLEREVERSE: int = 0x04
+SIGHASH_NOINPUT: int = 0x40
+SIGHASH_ANYONECANPAY: int = 0x80
+
+# Covenant types, matching shd/Sources/Protocol/CovenantType.swift.
+COVENANT_NONE: int = 0
+COVENANT_CLAIM: int = 1
+COVENANT_OPEN: int = 2
+COVENANT_BID: int = 3
+COVENANT_REVEAL: int = 4
+COVENANT_REDEEM: int = 5
+COVENANT_REGISTER: int = 6
+COVENANT_UPDATE: int = 7
+COVENANT_RENEW: int = 8
+COVENANT_TRANSFER: int = 9
+COVENANT_FINALIZE: int = 10
+COVENANT_REVOKE: int = 11
+
+
+def encode_varint(n: int) -> bytes:
+    if n < 0xFD:
+        return bytes([n])
+    if n <= 0xFFFF:
+        return b"\xfd" + n.to_bytes(2, "little")
+    if n <= 0xFFFFFFFF:
+        return b"\xfe" + n.to_bytes(4, "little")
+    return b"\xff" + n.to_bytes(8, "little")
+
+
+def name_hash(name: bytes) -> bytes:
+    """`shd` NameRules.hashName: SHA3-256, not Keccak."""
+    return sha3_256(name).digest()
+
+
+def begin_payload(n_in: int, n_out: int, version: int = 0, locktime: int = 0) -> bytes:
+    return (version.to_bytes(4, "little")
+            + encode_varint(n_in)
+            + encode_varint(n_out)
+            + locktime.to_bytes(4, "little"))
+
+
+def input_payload(path: str,
+                  value: int,
+                  txid: bytes = b"\x11" * 32,
+                  vout: int = 0,
+                  sequence: int = 0xFFFFFFFF,
+                  sighash: int = SIGHASH_ALL,
+                  script_kind: int = SCRIPT_KIND_P2WPKH) -> bytes:
+    assert len(txid) == 32
+    return (txid
+            + vout.to_bytes(4, "little")
+            + sequence.to_bytes(4, "little")
+            + value.to_bytes(8, "little")
+            + bytes([sighash])
+            + pack_derivation_path(path)
+            + bytes([script_kind]))
+
+
+def output_payload(value: int,
+                   addr_hash: bytes = b"\x22" * 20,
+                   addr_version: int = 0,
+                   covenant_kind: int = COVENANT_NONE,
+                   covenant_items: Sequence[bytes] = ()) -> bytes:
+    items = b"".join(encode_varint(len(i)) + i for i in covenant_items)
+    return (value.to_bytes(8, "little")
+            + bytes([addr_version, len(addr_hash)])
+            + addr_hash
+            + bytes([covenant_kind])
+            + encode_varint(len(covenant_items))
+            + items)
+
+
+def uint32_le(n: int) -> bytes:
+    return n.to_bytes(4, "little")
+
+
+def open_items(name: bytes) -> List[bytes]:
+    """OPEN: [nameHash, height, name] (CovenantData.makeOpen)."""
+    return [name_hash(name), uint32_le(0), name]
+
+
+def bid_items(name: bytes, height: int = 0, blind: bytes = b"\x33" * 32) -> List[bytes]:
+    """BID: [nameHash, startHeight, name, blind] (CovenantData.makeBid)."""
+    return [name_hash(name), uint32_le(height), name, blind]
+
+
+def reveal_items(name: bytes, height: int = 0, nonce: bytes = b"\x44" * 32) -> List[bytes]:
+    """REVEAL: [nameHash, startHeight, nonce]. Carries no plaintext name."""
+    return [name_hash(name), uint32_le(height), nonce]
+
+
+def transfer_items(name: bytes,
+                   dest_hash: bytes,
+                   height: int = 0,
+                   dest_version: int = 0) -> List[bytes]:
+    """TRANSFER: [nameHash, startHeight, [version], addressHash].
+
+    `items[3]` is the address the name is handed to, which is the whole point
+    of the covenant and appears nowhere else in the output.
+    """
+    return [name_hash(name), uint32_le(height), bytes([dest_version]), dest_hash]