Add SEP-53 message signing support for hardware wallets

[SmolinPavel]

What

Enables SEP-53 message signing for hardware wallets. Previously SignMessage
returned an "Unsupported signing method" screen whenever the active account was
a hardware wallet.

That guard was added in 5.23.0 (Aug 2024). It predates Ledger Stellar app
v6.0.0, which added a dedicated SEP-53 SIGN_MESSAGE instruction (APDU
0x0C, documented in app-stellar as "Sign the SEP-0053 message"). The pinned
@ledgerhq/hw-app-str@7.7.4 already exposes signMessage, so no dependency
change is needed.

How

The message path mirrors the existing Soroban auth-entry path — a new
hardwareSignMessage map in hardwareConnect.ts, an isSignMessage branch in
the signWithHardwareWallet thunk, and an isSignMessage prop on
HardwareSign.

The device applies the SEP-53 prefix and hashing itself and displays the message
for review, so it receives the raw UTF-8 bytes. The resulting signature is
identical to what encodeSep53Message + a local key produce, so the dApp-facing
response shape is unchanged. This is not blind signing — the message renders
as text on the device.

Two supporting fixes the path needs

• base64 transport. The signature crosses runtime.sendMessage as base64 and
  is normalized back to a Buffer by a new toSignatureBuffer helper. A raw
  Buffer is JSON-serialized in transit, so signedBlob.toString("base64") in
  submitBlob would have produced "[object Object]".
• signerAddress. handleSignedHwPayload now forwards the signing address,
  which SEP-53 consumers need in order to verify the signature they get back.
  The message branch verifies the returned signature against that key before
  reporting it — connectToLedgerTransport closes and reopens the connection on
  every call, so the key read by getWalletPublicKey is not otherwise provably
  the key that signed.

Error handling

A Stellar app older than v6.0.0 now reports that it needs updating, rather than
surfacing an opaque transport error. The check is a getAppConfiguration()
preflight in hardwareSignMessage; an unparseable version defers to the device
rather than refusing. Deliberately not matched on the device's generic
INS_NOT_SUPPORTED (0x6d00) status word — parseWalletError is shared by every
Ledger flow, and that code also fires for e.g. a Soroban auth entry on an older
app, where both the reason and the version number would be wrong.

Second commit also fixes an adjacent problem this path exposed: HardwareSign
runs its first signing attempt automatically from a mount effect, but the error
block only rendered after the "Detect device" button had been clicked. A device
that failed immediately left the overlay reading "Connect device to computer"
with no explanation until the user clicked through and failed again. Rendering on
the error itself drops the flag and covers the automatic attempt, so the existing
transaction and auth-entry overlays report failures on first try too.

Testing

Verified end to end on a Ledger Flex running Stellar app 6.0.3: the message
text renders on the device, approval returns a signature, and the dApp verifies
it against the signer address.

• 27 new unit tests covering the signing helper, the version and size gates, the
  error mapping, the thunk branch, the base64 normalization, the signerAddress
  passthrough, and a new HardwareSign suite for the account guard and the
  first-attempt error state. The thunk and component tests sign with real
  keypairs, so signature verification is exercised rather than stubbed.
• Full Jest suite: 1540 passing. The one failing suite, testNodeCompat.js, is
  pre-existing on master and needs @stellar/freighter-api built first.
• tsc --noEmit -p extension/tsconfig.json clean; ESLint clean on changed files.

Notes for reviewers

• INTEGRATING_HARDWARE_WALLET.MD documented only hardwareSign; it now also
  covers hardwareSignAuth (already required) and hardwareSignMessage.
• Two now-unused locale keys were removed alongside the deleted warning screen.
• getAppConfiguration() also reports the device's maxDataSize, so an
  oversized message is rejected with an actionable error rather than the
  library's RequestDataTooLarge (0xB004) remap. Measured in UTF-8 bytes.

Two pre-existing gaps this work surfaced, deliberately left alone

Both affect the hardware transaction and auth-entry paths equally, so fixing
either only for messages would make the behaviour inconsistent. Flagging rather
than guessing, since both touch areas you own:

1. signerAddress is still undefined for hardware transactions and auth
   entries. docs/api-integration.md:145 tells integrators to "always verify
   result.signerAddress === expectedAddress", which means a dApp following that
   guidance rejects every hardware-wallet transaction. Closing it properly means
   verifying those signatures too (against tx.hash() and hash(authPreimage)
   respectively) before reporting a key — cheap, but it changes the wallet's
   busiest signing path, and I could only test message signing on a device.
2. signWithHardwareWallet dispatches no metrics. The signing events in
   popup/metrics/access.ts are registered on signTransaction / signBlob /
   signEntry, so hardware signing has never appeared in them. This wants one
   handler covering all three and an event shape you'd want to decide.

[Copilot]

Pull request overview

Adds SEP-53 message signing support for Ledger hardware wallets.

Changes:

• Adds Ledger message signing with version validation and error handling.
• Transports signatures as base64 and forwards signer addresses.
• Updates hardware-signing UI, tests, localization, and documentation.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
extension/src/popup/views/SignMessage/index.tsx	Enables the hardware signing overlay.
extension/src/popup/locales/pt/translation.json	Updates Portuguese signing messages.
extension/src/popup/locales/en/translation.json	Updates English signing messages.
extension/src/popup/helpers/hardwareConnect.ts	Implements Ledger SEP-53 signing.
extension/src/popup/helpers/__tests__/hardwareConnect.test.ts	Tests Ledger signing and version handling.
extension/src/popup/ducks/transactionSubmission.ts	Routes message payloads to hardware signing.
extension/src/popup/ducks/__tests__/signWithHardwareWallet.test.ts	Tests the new thunk branch.
extension/src/popup/components/hardwareConnect/HardwareSign/index.tsx	Integrates message signing and immediate errors.
extension/src/helpers/stellar.ts	Adds signature transport normalization.
extension/src/helpers/__tests__/stellar.test.ts	Tests signature normalization.
extension/src/background/messageListener/handlers/handleSignedHwPayload.ts	Forwards signer addresses.
extension/src/background/messageListener/freighterApiMessageListener.ts	Normalizes hardware signatures.
extension/src/background/messageListener/__tests__/handleSignedHwPayload.test.ts	Tests signer-address forwarding.
extension/INTEGRATING_HARDWARE_WALLET.MD	Documents additional signing integrations.
@shared/api/types/message-request.ts	Extends hardware payload messages.
@shared/api/internal.ts	Sends signer addresses to the background.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated no new comments.

Suppressed comments (1)

extension/src/popup/components/hardwareConnect/HardwareSign/index.tsx:115

• This account check is not bound to the actual signing operation. getWalletPublicKey reads one Ledger connection, but hardwareSignMessage subsequently calls connectToLedgerTransport(), which closes that connection and opens another. With multiple authorized devices—or a device swap between calls—the signature can come from a different key while signerAddress is still reported as the key checked here, producing an unverifiable/misattributed response. Derive the key and sign through the same transport/API instance, or verify the returned SEP-53 signature against expectedPublicKey before forwarding it.

      const expectedPublicKey = requestedPublicKey || activePublicKey;
      if (
        isSignMessage &&
        expectedPublicKey &&
        publicKey !== expectedPublicKey
      ) {
        throw new Error(MISMATCHED_HARDWARE_ACCOUNT_ERROR);

[Copilot]

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated no new comments.

Suppressed comments (2)

extension/src/popup/helpers/tests/hardwareConnect.test.ts:205

• Use “an” before “8-byte.”

    // "☕" is 3 UTF-8 bytes; 4 of them exceed a 8-byte device limit even though

extension/src/popup/components/hardwareConnect/HardwareSign/index.tsx:153

• signerAddress is still explicitly omitted for hardware transaction and auth-entry responses, despite the stated supporting fix and the SDK contracts requiring a signer address. Those flows will continue resolving undefined, so consumer checks such as those documented in docs/api-integration.md:106-108 and :158-160 still fail. Verify each hardware signature against publicKey in signWithHardwareWallet (as the message branch does), then forward the verified key for all three flows.

            signerAddress: isSignMessage ? publicKey : undefined,

[SmolinPavel]

@JakeUrban could you please review this PR?

[aristidesstaffieri]

The new guard compares the device key against requestedPublicKey with raw string equality, but accountToSign is passed through unnormalized — a dApp can legitimately supply a muxed (M...) address whose base account is exactly the account that's active and attached.

In that case signFlowAccountSelector finds no match (it also compares exact G-strings), the guard compares a G-address against the M-string, and signing dead-ends with MISMATCHED_HARDWARE_ACCOUNT_ERROR — telling the user to connect a different device while the correct one is already attached. Retrying via "Detect device" fails identically forever. The same request works for signTransaction, which normalizes muxed and federation forms via decodeAccountToSign before comparing.

isSameAccount in extension/src/helpers/stellar.ts already does the muxed→base normalization synchronously:

if (isSignMessage && expectedPublicKey && !isSameAccount(publicKey, expectedPublicKey)) {
  throw new Error(MISMATCHED_HARDWARE_ACCOUNT_ERROR);
}

---

Generated by Claude Code

[JakeUrban]

We can update this so we're consistent with signTransaction, but a dapp passing a muxed or federated address is invalid isn't it @aristidesstaffieri ?

[SmolinPavel]

Traced it — the dead-end is real. signFlowAccountSelector compares exact strings (popup/helpers/account.ts:379), and currentAccount is pre-seeded from the active account so accountNotFound never fires. The user reaches the signing screen, hits the device error with the correct Ledger attached, and Detect device re-runs the same comparison forever.

One correction: signTransaction doesn't work either. decodeAccountToSign() runs at SignTransaction/index.tsx:232, but useGetSignTxData(..., accountToSign, ...) already ran at :134, and it mutates a render-local let nothing reads afterward. It gets the raw M-address too — SignMessage is just the only flow with a device guard, so it's the only one that fails loudly.

@JakeUrban muxed isn't supported end to end today: even for software accounts signMessage returns the base G, which fails the signerAddress === expectedAddress check we tell integrators to write. isSameAccount wouldn't change that — the guard would pass but the dApp still rejects. It also uses the sync getBaseAccount, so federation dead-ends identically.

So it's where it fails, not whether. Either isSameAccount (downgrades to a clean dApp-side rejection) or reject M/federation up front with copy naming the real problem. Happy to do either — preference?