From c186d07df234225873089503dc8076813ceca8db Mon Sep 17 00:00:00 2001 From: "Valentin D. Pinkman" Date: Thu, 23 Jan 2025 17:42:38 +0100 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20(transports):=20Add=20missing=20?= =?UTF-8?q?readme.md=20to=20transport=20packages?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 19 +++--- danger/helpers.ts | 22 +++---- packages/device-management-kit/README.md | 58 +++++++++--------- packages/transport/web-ble/README.md | 77 ++++++++++++++++++++++++ packages/transport/web-hid/README.md | 77 ++++++++++++++++++++++++ 5 files changed, 202 insertions(+), 51 deletions(-) create mode 100644 packages/transport/web-ble/README.md create mode 100644 packages/transport/web-hid/README.md diff --git a/README.md b/README.md index 30bdad3d2..1a9844596 100644 --- a/README.md +++ b/README.md @@ -145,12 +145,6 @@ proto use pnpm i ``` -Alternatively, if you want to bypass the postinstall scripts which can be long to run. - -```bash -pnpm i --ignore-scripts -``` - 4- Check the shell configuration file In you shell configuration file (e.g. .bashrc or .zshrc ) verify the path for `proto` is correctly set. @@ -189,12 +183,13 @@ Device Management Kit main module. pnpm dmk build ``` -### Signer +### Signers Transaction and message signer module. +Each signer is its own package. Here is an exemple with the ETH signer: ```bash -pnpm signer build +pnpm signer-eth build ``` ### Trusted Apps @@ -221,6 +216,12 @@ Sample application module. pnpm sample build ``` +#### Documentation + +```bash +pnpm doc build +``` + # Processes & usage ## Continuous integration @@ -295,7 +296,7 @@ It includes background information about the project and how to setup, run and b ## Reference API -Please refer to the core package [**readme**](https://github.com/LedgerHQ/device-sdk-ts/blob/develop/packages/core/README.md). +Please refer to the core package [**readme**](https://github.com/LedgerHQ/device-sdk-ts/blob/develop/packages/device-management-kit/README.md). # Contributing diff --git a/danger/helpers.ts b/danger/helpers.ts index c6e8ee868..430ab51b2 100644 --- a/danger/helpers.ts +++ b/danger/helpers.ts @@ -11,7 +11,7 @@ import { execSync } from "child_process"; type FailFn = (message: MarkdownString, file?: string, line?: number) => void; type MessageFn = ( message: MarkdownString, - opts?: { file?: string; line?: number; icon?: MarkdownString }, + opts?: { file?: string; line?: number; icon?: MarkdownString } ) => void; export const BRANCH_PREFIX = [ @@ -44,13 +44,13 @@ export const isFork = (pr: GitHubPRDSL) => pr?.head?.repo?.fork ?? false; const Branch = ( danger: DangerDSLType, fail: FailFn, - isFork: boolean = false, + isFork: boolean = false ) => ({ regex: isFork ? new RegExp(`^(${BRANCH_PREFIX.join("|")})\/.+`, "i") : new RegExp( `^(${BRANCH_PREFIX.join("|")})\/((dsdk)-[0-9]+|no-issue|issue-[0-9]+)\-.+`, - "i", + "i" ), getBranch: () => { @@ -99,7 +99,7 @@ Please fix the PR branch name to match the convention, see [CONTRIBUTING.md](htt export const checkBranches = ( danger: DangerDSLType, fail: FailFn, - fork: boolean = false, + fork: boolean = false ) => { const config = Branch(danger, fail, fork); const currentBranch = config.getBranch(); @@ -115,7 +115,7 @@ export const checkBranches = ( const Commits = ( danger: DangerDSLType, fail: FailFn, - fork: boolean = false, + fork: boolean = false ) => ({ regex: /^.+\(([a-z]+\-?){1,}\): [A-Z].*/, @@ -146,7 +146,7 @@ Example: \`💚 (scope): My feature\`\ const currentBranch = Branch(danger, fail, fork).getBranch(); return execSync( - `git log origin/develop..${currentBranch} --pretty=format:%s`, + `git log origin/develop..${currentBranch} --pretty=format:%s` ) .toString() .split("\n"); @@ -156,14 +156,14 @@ Example: \`💚 (scope): My feature\`\ export const checkCommits = ( danger: DangerDSLType, fail: FailFn, - fork: boolean = false, + fork: boolean = false ) => { const config = Commits(danger, fail, fork); const branchCommits = config.getCommits(); console.log("Branch commits:", branchCommits); const wrongCommits = branchCommits.filter( - (commit) => !config.regex.test(commit), + (commit) => !config.regex.test(commit) ); if (wrongCommits.length > 0) { @@ -225,7 +225,7 @@ Please fix the PR title to match the convention, see [CONTRIBUTING.md](https://g export const checkTitle = ( danger: DangerDSLType, fail: FailFn, - fork: boolean = false, + fork: boolean = false ) => { const config = Title(danger, fail, fork); if (!config.regex.test(danger.github.pr.title)) { @@ -240,10 +240,10 @@ export const checkChangesets = (danger: DangerDSLType, message: MessageFn) => { const changesetFiles = danger.git.fileMatch("**/.changeset/*.md"); if (changesetFiles.edited === false) { message( - `\ No changeset file found in the PR. Please add a changeset file.`, + `\ No changeset file found. Please make sure this is intended or add a changeset file.`, { icon: "⚠ī¸", - }, + } ); return false; } diff --git a/packages/device-management-kit/README.md b/packages/device-management-kit/README.md index e0cad35d9..74a41a076 100644 --- a/packages/device-management-kit/README.md +++ b/packages/device-management-kit/README.md @@ -8,7 +8,6 @@ - [Installation](#installation) - [Usage](#usage) - [Compatibility](#compatibility) - - [Pre-requisites](#pre-requisites) - [Main Features](#main-features) - [Setting up the SDK](#setting-up-the-sdk) - [Connecting to a Device](#connecting-to-a-device) @@ -37,13 +36,9 @@ npm install @ledgerhq/device-management-kit ## Usage -### Compatibility - -This library works in [any browser supporting the WebHID API](https://developer.mozilla.org/en-US/docs/Web/API/WebHID_API#browser_compatibility). - ### Pre-requisites -Some of the APIs exposed return objects of type `Observable` from RxJS. Ensure you are familiar with the basics of the Observer pattern and RxJS before using this SDK. You can refer to [RxJS documentation](https://rxjs.dev/guide/overview) for more information. +Some of the APIs exposed return objects of type `Observable` from RxJS. Ensure you are familiar with the basics of the Observer pattern and RxJS before using this Device Management Kit. You can refer to [RxJS documentation](https://rxjs.dev/guide/overview) for more information. ### Main Features @@ -60,27 +55,28 @@ Some of the APIs exposed return objects of type `Observable` from RxJS. Ensure y > [!NOTE] > At the moment we do not provide the possibility to distinguish two devices of the same model, via USB and to avoid connection to the same device twice. -### Setting up the SDK +### Setting up the Device Management Kit -The core package exposes an SDK builder `DeviceSdkBuilder` which will be used to initialise the SDK with your configuration. +The core package exposes a Device Manageent Kit builder `DeviceManagementKitBuilder` which will be used to initialise the Device Management Kit with your configuration. For now it allows you to add one or more custom loggers. -In the following example, we add a console logger (`.addLogger(new ConsoleLogger())`). Then we build the SDK with `.build()`. +In the following example, we add a console logger (`.addLogger(new ConsoleLogger())`) and a WebHID transport. Then we build the Device Management Kit with `.build()`. -**The returned object will be the entrypoint for all your interactions with the SDK.** +**The returned object will be the entrypoint for all your interactions with the Device Management Kit.** -The SDK should be built only once in your application runtime so keep a reference of this object somewhere. +The Device Management Kit should be built only once in your application runtime so keep a reference of this object somewhere. ```ts import { ConsoleLogger, - DeviceSdk, - DeviceSdkBuilder, + DeviceManagementKitBuilder, } from "@ledgerhq/device-management-kit"; +import { webHidTransportFactory } from "@ledgerhq/device-transport-kit-web-hid"; -export const sdk = new DeviceSdkBuilder() +export const sdk = new DeviceManagementKitBuilder() .addLogger(new ConsoleLogger()) + .addTransport(webHidTransportFactory) .build(); ``` @@ -88,20 +84,20 @@ export const sdk = new DeviceSdkBuilder() There are two steps to connecting to a device: -- **Discovery**: `sdk.startDiscovering()` +- **Discovery**: `dmk.startDiscovering()` - Returns an observable which will emit a new `DiscoveredDevice` for every scanned device. - The `DiscoveredDevice` objects contain information about the device model. - Use one of these values to connect to a given discovered device. -- **Connection**: `sdk.connect({ deviceId: device.id })` +- **Connection**: `dmk.connect({ deviceId: device.id })` - Returns a Promise resolving in a device session identifier `DeviceSessionId`. - **Keep this device session identifier to further interact with the device.** - - Then, `sdk.getConnectedDevice({ sessionId })` returns the `ConnectedDevice`, which contains information about the device model and its name. + - Then, `dmk.getConnectedDevice({ sessionId })` returns the `ConnectedDevice`, which contains information about the device model and its name. ```ts -sdk.startDiscovering().subscribe({ +dmk.startDiscovering().subscribe({ next: (device) => { - sdk.connect({ deviceId: device.id }).then((sessionId) => { - const connectedDevice = sdk.getConnectedDevice({ sessionId }); + dmk.connect({ deviceId: device.id }).then((sessionId) => { + const connectedDevice = dmk.getConnectedDevice({ sessionId }); }); }, error: (error) => { @@ -112,8 +108,8 @@ sdk.startDiscovering().subscribe({ Then once a device is connected: -- **Disconnection**: `sdk.disconnect({ sessionId })` -- **Observe the device session state**: `sdk.getDeviceSessionState({ sessionId })` +- **Disconnection**: `dmk.disconnect({ sessionId })` +- **Observe the device session state**: `dmk.getDeviceSessionState({ sessionId })` - This will return an `Observable` to listen to the known information about the device: - device status: - ready to process a command @@ -154,7 +150,7 @@ const apdu = new ApduBuilder(openAppApduArgs) // ### 2. Sending the APDU -const apduResponse = await sdk.sendApdu({ sessionId, apdu }); +const apduResponse = await dmk.sendApdu({ sessionId, apdu }); // ### 3. Parsing the result @@ -178,7 +174,7 @@ The `sendCommand` method will take care of building the APDU, sending it to the > ### ❗ī¸ Error Responses > > Most of the commands will reject with an error if the device is locked. -> Ensure that the device is unlocked before sending commands. You can check the device session state (`sdk.getDeviceSessionState`) to know if the device is locked. +> Ensure that the device is unlocked before sending commands. You can check the device session state (`dmk.getDeviceSessionState`) to know if the device is locked. > > Most of the commands will reject with an error if the response status word is not `0x9000` (success response from the device). @@ -191,7 +187,7 @@ import { OpenAppCommand } from "@ledgerhq/device-management-kit"; const command = new OpenAppCommand("Bitcoin"); // Open the Bitcoin app -await sdk.sendCommand({ sessionId, command }); +await dmk.sendCommand({ sessionId, command }); ``` #### Close App @@ -203,14 +199,14 @@ import { CloseAppCommand } from "@ledgerhq/device-management-kit"; const command = new CloseAppCommand(); -await sdk.sendCommand({ sessionId, command }); +await dmk.sendCommand({ sessionId, command }); ``` #### Get OS Version This command will return information about the currently installed OS on the device. -> ℹī¸ If you want this information you can simply get it from the device session state by observing it with `sdk.getDeviceSessionState({ sessionId })`. +> ℹī¸ If you want this information you can simply get it from the device session state by observing it with `dmk.getDeviceSessionState({ sessionId })`. ```ts import { GetOsVersionCommand } from "@ledgerhq/device-management-kit"; @@ -218,21 +214,21 @@ import { GetOsVersionCommand } from "@ledgerhq/device-management-kit"; const command = new GetOsVersionCommand(); const { seVersion, mcuSephVersion, mcuBootloaderVersion } = - await sdk.sendCommand({ sessionId, command }); + await dmk.sendCommand({ sessionId, command }); ``` #### Get App and Version This command will return the name and version of the currently running app on the device. -> ℹī¸ If you want this information you can simply get it from the device session state by observing it with `sdk.getDeviceSessionState({ sessionId })`. +> ℹī¸ If you want this information you can simply get it from the device session state by observing it with `dmk.getDeviceSessionState({ sessionId })`. ```ts import { GetAppAndVersionCommand } from "@ledgerhq/device-management-kit"; const command = new GetAppAndVersionCommand(); -const { name, version } = await sdk.sendCommand({ sessionId, command }); +const { name, version } = await dmk.sendCommand({ sessionId, command }); ``` ### Building a Custom Command @@ -264,7 +260,7 @@ import { const openAppDeviceAction = new OpenAppDeviceAction({ appName: "Bitcoin" }); -const { observable, cancel } = await sdk.executeDeviceAction({ +const { observable, cancel } = await dmk.executeDeviceAction({ deviceAction: openAppDeviceAction, command, }); diff --git a/packages/transport/web-ble/README.md b/packages/transport/web-ble/README.md new file mode 100644 index 000000000..c150dd3c1 --- /dev/null +++ b/packages/transport/web-ble/README.md @@ -0,0 +1,77 @@ +# Transport Device Kit Web BLE + +> [!CAUTION] +> This is still under development and we are free to make new interfaces which may lead to breaking changes. + +- [Transport Device Kit Web BLE Documentation](#transport-device-kit-web-ble) + - [Description](#description) + - [Installation](#installation) + - [Usage](#usage) + - [Compatibility](#compatibility) + - [Pre-requisites](#pre-requisites) + - [Main Features](#main-features) + - [How To](#how-to) + +## Description + +This transport is used to interact with a Ledger device through the Web BLE (Bluetooth) implementation by the Device Management Kit. + +## Installation + +To install the core package, run the following command: + +```sh +npm install @ledgerhq/device-transport-kit-web-ble +``` + +## Usage + +### Compatibility + +This library works in [any browser supporting the Web Bluetooth API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Bluetooth_API#browser_compatibility). + +### Pre-requisites + +To use this transport, ensure you have the Device Magement Kit installed in your project. + +### Main Features + +- Exposing a transport factory to be injected into the DeviceManagementKit +- Exposing the transport directly for a custom configuration + +### How To + +To use the transport, you need to inject it in the DeviceManagementKitBuilder before the build. This will allow the Device Managment Kit to find and interact with devices on the Web BLE protocol. + +```typescript +import { DeviceManagementKitBuilder } from "@ledgerhq/device-management-kit" +import { webBleTransportFactory, WebBleTransport } from "@ledgerhq/device-transport-kit-web-ble" + +// Easy setup with the factory +const dmk = new DeviceManagementKitBuilder() + .addTransport(webBleTransportFactory) + .build(); + + +// With custom config +const dmk = new DeviceManagementKitBuilder() + .addTransport(({ + deviceModelDataSource: DeviceModelDataSource; + loggerServiceFactory: (tag: string) => LoggerPublisherService; + config: DmkConfig; + apduSenderServiceFactory: ApduSenderServiceFactory; + apduReceiverServiceFactory: ApduReceiverServiceFactory; + }) => { + // custom code + return new WebBleTransport( + deviceModelDataSource, + loggerServiceFactory, + config, + apduSenderServiceFactory, + apduReceiverServiceFactory, + ); + }) + .build(); + + // You can then make use of the Device Management Kit +``` diff --git a/packages/transport/web-hid/README.md b/packages/transport/web-hid/README.md new file mode 100644 index 000000000..ee036c07d --- /dev/null +++ b/packages/transport/web-hid/README.md @@ -0,0 +1,77 @@ +# Transport Device Kit Web HID + +> [!CAUTION] +> This is still under development and we are free to make new interfaces which may lead to breaking changes. + +- [Transport Device Kit Web HID Documentation](#transport-device-kit-web-hid) + - [Description](#description) + - [Installation](#installation) + - [Usage](#usage) + - [Compatibility](#compatibility) + - [Pre-requisites](#pre-requisites) + - [Main Features](#main-features) + - [How To](#how-to) + +## Description + +This transport is used to interact with a Ledger device through the Web HID (usb) implementation by the Device Management Kit. + +## Installation + +To install the core package, run the following command: + +```sh +npm install @ledgerhq/device-transport-kit-web-hid +``` + +## Usage + +### Compatibility + +This library works in [any browser supporting the WebHID API](https://developer.mozilla.org/en-US/docs/Web/API/WebHID_API#browser_compatibility). + +### Pre-requisites + +To use this transport, ensure you have the Device Magement Kit installed in your project. + +### Main Features + +- Exposing a transport factory to be injected into the DeviceManagementKit +- Exposing the transport directly for a custom configuration + +### How To + +To use the transport, you need to inject it in the DeviceManagementKitBuilder before the build. This will allow the Devivce Management Kit to find and interact with devices on the Web HID protocol. + +```typescript +import { DeviceManagementKitBuilder } from "@ledgerhq/device-management-kit" +import { webHidTransportFactory, WebHidTransport } from "@ledgerhq/device-transport-kit-web-hid" + +// Easy setup with the factory +const dmk = new DeviceManagementKitBuilder() + .addTransport(webHidTransportFactory) + .build(); + + +// With custom config +const dmk = new DeviceManagementKitBuilder() + .addTransport(({ + deviceModelDataSource: DeviceModelDataSource; + loggerServiceFactory: (tag: string) => LoggerPublisherService; + config: DmkConfig; + apduSenderServiceFactory: ApduSenderServiceFactory; + apduReceiverServiceFactory: ApduReceiverServiceFactory; + }) => { + // custom code + return new WebHidTransport( + deviceModelDataSource, + loggerServiceFactory, + config, + apduSenderServiceFactory, + apduReceiverServiceFactory, + ); + }) + .build(); + + // You can then make use of the Device Management Kit +```