feat: add qr keyring package

[mikesposito]

This is a new Keyring implementation compatible with QR-based wallets, meant to replace @keystonehq/metamask-airgapped-keyring.

The goals are:

• Internalize the package
• Simplify internal logic (e.g. no event-based logic)
• Remove the need of KeyringController special methods (See methods nuked in chore(keyring-controller): remove QRKeyring-related code core#6031)
• Provide a consumer-injectable transport bridge to allow clients to control QR scanning implementation
• Improve API ergonomics
• Allow clients to easily support multiple QR devices per user

This package can be tested on Extension through this PR: MetaMask/metamask-extension#33893

• Fixes Internalize simplified QRKeyring implementation #144

How does it work?

The QrKeyring in this package is split into two main components:

• QrKeyring: The main keyring class that exposes the Keyring API. Some of its logic is implemented in internal utility classes:
  • Device: A stateful internal wrapper for the keyring's public keys derivation logic and account management. In the code it's implemented by a separate class, but it can be seen as an internal component of the keyring, and It is not exported from the package.
• QrKeyringBridge: The interface that a transport bridge must implement: it allows the client to control how QR codes are scanned. It's supposed to be implemented by a class that is injected by the client: when using KeyringController, it can be injected through a custom keyring builder (See this keyring builder that will be used by Extension).
  • QrKeyringScannerBridge: A generic bridge that allows the client to pass function hooks at construction time, which will be called when the keyring needs to scan a QR code.

Device pairing flow

Pairing is the process of initializing the keyring with a device, which is done by submitting the device details to the keyring in the form of a serialized UR, which usually comes from the "sync" QR scanned on the device. The client can trigger this process in three ways:

• At construction time, by passing a SerializedUR object to the QrKeyring constructor.
  • In this case, the scan is done before the keyring is constructed, and thus the keyring will directly receive the QR contents.
• By calling the QrKeyring.pairDevice() method, which allows the client to pass a SerializedUR object at any time.
  • Same as above, the scan is done outside the keyring, and the keyring will directly receive the QR contents.
• By calling the QrKeyring.getFirstPage() method, which will trigger a scan request if no device is paired yet.
  • In this case, the keyring will request a scan through the bridge, and the client will implement the scan logic.

Extension uses getFirstPage() to trigger the pairing flow, which will then request a scan through the bridge

Like for other Hardare wallets, the pairing flow is initiated in connectHardware() method. See the sequence diagram below for the pairing flow on Extension, and see the Extension requestScan callback for the implementation of the scan logic.

sequenceDiagram
        autonumber
        participant A as MM Extension
        create participant B as QrKeyring
        A->>B: getFirstPage()
        alt if not initialized
        create participant C as Bridge
        B->>C: requestScan(PAIRING)
        C-->>+A: 
        note over A,C: The client controls the bridge and implements the scan logic
        A-->>-C: 
        destroy C
        C->>B: return CBOR 
        create participant D as Int. derivation logic
        B->>D: init(CBOR)
        end
        B->>D: accountAtIndex(0..4)
        destroy D
        D->>B: return accounts
        destroy B
        B->>A: return accounts

Loading

Mobile

TBD - Likely using .pairDevice() given the current implementation of QR interactions on mobile.

Signing flow

sequenceDiagram
        autonumber
        participant A as Client
        create participant B as QrKeyring
        A->>B: sign{Transaction, PersonalMessage, TypedData}()
        alt not initialized
        B->>A: Fail
        end
        create participant C as Bridge
        B->>C: requestScan(SIGN)
        C-->>+A: 
        note over A,C: The client controls the bridge and implements the scan logic
        A-->>-C: 
        destroy C
        C->>B: return signature CBOR 
        destroy B
        B->>A: return hex signature

Loading

Account addition flow

No scan required after the initial pairing.

sequenceDiagram
        autonumber
        participant A as Client
        alt non sequential account addition 
        create participant B as QrKeyring
        A->>B: setAccountToUnlock( i )
        end
        A->>B: addAccounts( n )
        loop n-times
        create participant D as Int. derivation logic
        B->>D: accountAtIndex( i )
        destroy D
        D->>B: return account
        end
        B->>A: return created accounts

Loading

Examples

[danroc]

Thank you @mikesposito! Maybe we should import this using git merge --allow-unrelated-histories (+ manual fixes) to keep the history from the original repo.

[mikesposito]

@danroc this PR is not moving the package from another source - this is a new implementation, and only shares a similar account derivation strategy from URs with the original keyring package currently used on clients

Do you think we should bring in its commit history anyway? Also, the package is in a Keystone monorepo, which would include commits to other packages potentially unrelated

[danroc]

Sorry @mikesposito, I didn't realise it was a new implementation! In this case it makes sense to start fresh, thank you for the clarification.

[github-actions]

This PR is marked as stale because it has been open for 60 days with no activity. Please remove the stale label or leave a comment, or it will be closed in 14 days.

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	@​keystonehq/​metamask-airgapped-keyring@​0.15.2
	@​keystonehq/​bc-ur-registry-eth@​0.19.1
	@​metamask/​utils@​9.3.0 ⏵ 9.2.1				-2

View full report

[socket-security]

All alerts resolved. Learn more about Socket for GitHub.

This PR previously contained dependency changes with security issues that have been resolved, removed, or ignored.

Ignoring alerts on:

• assert@2.1.0

View full report

[github-actions]

Preview builds have been published. See these instructions (from the core monorepo) for more information about preview builds.

Expand for full list of packages and versions.

{
  "@metamask-previews/keyring-api": "18.0.0-d2e6996",
  "@metamask-previews/eth-hd-keyring": "12.1.0-d2e6996",
  "@metamask-previews/eth-ledger-bridge-keyring": "11.1.1-d2e6996",
  "@metamask-previews/eth-qr-keyring": "0.0.0-d2e6996",
  "@metamask-previews/eth-simple-keyring": "10.0.0-d2e6996",
  "@metamask-previews/eth-trezor-keyring": "9.0.0-d2e6996",
  "@metamask-previews/keyring-internal-api": "6.2.0-d2e6996",
  "@metamask-previews/keyring-internal-snap-client": "4.1.0-d2e6996",
  "@metamask-previews/eth-snap-keyring": "13.0.0-d2e6996",
  "@metamask-previews/keyring-snap-client": "5.0.0-d2e6996",
  "@metamask-previews/keyring-snap-sdk": "4.0.0-d2e6996",
  "@metamask-previews/keyring-utils": "3.0.0-d2e6996"
}

[cryptodev-2s]

LGTM! I’ll just leave one small suggestion for the changelog so we won’t need to reference the initial PR later. Everything else looks good!

[mikesposito]

@SocketSecurity ignore npm/assert@2.1.0

The new author seems trustworthy

[cryptodev-2s]

LGTM!

[gantunesr]

Looks good

[dawnseeker8]

LGTM