From 41e33dc24ed0d59d798a437a58e49ec26291b461 Mon Sep 17 00:00:00 2001 From: Berend Sliedrecht <61358536+berendsliedrecht@users.noreply.github.com> Date: Thu, 10 Oct 2024 14:37:31 +0200 Subject: [PATCH] docs: added documentation on usage of bleShareProof and bleRequestProof (#100) Signed-off-by: Berend Sliedrecht --- README.md | 3 + docs/request.md | 103 +++++++++++++++++++++++++++++++++++ docs/share.md | 88 ++++++++++++++++++++++++++++++ library/src/bleShareProof.ts | 1 + 4 files changed, 195 insertions(+) create mode 100644 docs/request.md create mode 100644 docs/share.md diff --git a/README.md b/README.md index b9d1f65..ef53f97 100644 --- a/README.md +++ b/README.md @@ -40,6 +40,9 @@ --- +> Refer to [docs](./docs) for some more in-depth documentation in the newer, and easier to use, API. +> The [example](./example) application shows how this can be used. + ## Introduction This package can be used as a transport for [DIDComm](https://didcomm.org) messages over Bluetooth Low Energy (BLE). diff --git a/docs/request.md b/docs/request.md new file mode 100644 index 0000000..2d3f6f9 --- /dev/null +++ b/docs/request.md @@ -0,0 +1,103 @@ +# BLE Request Proof Function Documentation + +## Overview + +The `bleRequestProof` function is designed to facilitate a proof request over Bluetooth Low Energy (BLE). + +## Function Signature + +```typescript +export const bleRequestProof = async (options: BleRequestProofOptions) => Promise +``` + +## Parameters + +The function takes a single object parameter of type `BleRequestProofOptions` with the following properties: + +- `agent: Agent` - An instance of the Agent class from the Credo framework. +- `peripheral: Peripheral` - A Peripheral object representing the BLE device. + - This can be retrieved with the `usePeripheral` hook as shown in the example. +- `serviceUuid: string` - The UUID of the BLE service to use. + - This UUID needs to be established out-of-band, i.e. by generating one and scanning a QR code. +- `presentationTemplate: PresentationTemplate` - An object containing the proof request details. +- `onFailure: () => Promise | void` - A callback function to be called if the proof request fails. +- `onConnected?: () => Promise | void` - An optional callback function to be called when the BLE connection is established. +- `onDisconnected?: () => Promise | void` - An optional callback function to be called when the BLE connection is disconnected. + +## Return Value + +Proof record id + +## Usage Example + +```typescript +import { Agent } from '@credo-ts/core'; +import { bleRequestProof, PresentationTemplate, usePeripheral } from '@animo-id/react-native-ble-didcomm'; + +const agent = new Agent(/* agent configuration */); +const peripheral = usePeripheral(); + +const presentationTemplate: PresentationTemplate = { + id: 'template-id', + name: 'Proof Request Template', + requestMessage: { + anoncreds: { + name: 'anon-request', + version: '2.0', + requested_attributes: { nameGroup: { name: 'name' } }, + requested_predicates: { + ageGroup: { name: 'age', p_value: 20, p_type: '>' }, + }, + }, + }, +}; + +const serviceUuid = 'your-service-uuid'; + +try { + const proofRecordId = await bleRequestProof({ + agent, + peripheral, + serviceUuid, + presentationTemplate, + onFailure: () => console.error('Proof request failed'), + onConnected: () => console.log('BLE connected'), + onDisconnected: () => console.log('BLE disconnected') + }); + + console.log(`Proof record created with ID: ${proofRecordId}`); +} catch (error) { + console.error('Error in bleRequestProof:', error); +} +``` + +## Function Flow + +1. Starts the BLE transport for the agent. +2. Sets up the indication, message and service UUID as characteristics +3. Sets up a disconnection notifier. +4. Sends the proof request message when connected. +5. Starts a message receiver for incoming messages. +6. Waits for the proof to be received and processes it. +7. Returns the proof record ID upon successful completion. + +## Error Handling + +If an error occurs during the execution of the function, it will: + +1. Log the error using the agent's logger. +2. Call the `onFailure` callback. +3. Throw the error for the caller to handle. + +## Peer Dependencies + +- `@credo-ts/core` +- `@credo-ts/anoncreds` +- `react` +- `react-native` + +## Notes + +- The function uses credo-ts for presentation exchange. +- It's designed to work with Bluetooth Low Energy, so make sure your environment supports BLE operations. +- The function handles the entire flow of requesting and receiving a proof over BLE, including connection management and message exchange. diff --git a/docs/share.md b/docs/share.md new file mode 100644 index 0000000..d544642 --- /dev/null +++ b/docs/share.md @@ -0,0 +1,88 @@ +# BLE Share Proof Function Documentation + +## Overview + +The `bleShareProof` function is designed to facilitate a response to a proof request over Bluetooth Low Energy (BLE). + +## Function Signature + +```typescript +export const bleShareProof = async (options: BleShareProofOptions): Promise +``` + +## Parameters + +The function takes a single object parameter of type `BleShareProofOptions` with the following properties: + +- `agent: Agent` - An instance of the Agent class from the Credo framework. +- `central: Central` - A Central object representing the BLE central device. + - This can be retrieved with the `useCentral` hook as shown in the example. +- `serviceUuid: string` - The UUID of the BLE service to use. + - This UUID needs to be established out-of-band, i.e. by generating one and scanning a QR code. +- `onFailure: () => Promise | void` - A callback function to be called if the proof sharing fails. +- `onConnected?: () => Promise | void` - An optional callback function to be called when the BLE connection is established. +- `onDisconnected?: () => Promise | void` - An optional callback function to be called when the BLE connection is disconnected. + +## Return Value + +The function returns a Promise that resolves to `void` when the proof sharing process is complete. + +## Usage Example + +```typescript +import { Agent } from '@credo-ts/core'; +import { bleShareProof, useCentral } from '@animo-id/react-native-ble-didcomm'; + +const agent = new Agent(/* agent configuration */); +const central = useCentral(); + +const serviceUuid = 'your-service-uuid'; + +try { + await bleShareProof({ + agent, + central, + serviceUuid, + onFailure: () => console.error('Proof sharing failed'), + onConnected: () => console.log('BLE connected'), + onDisconnected: () => console.log('BLE disconnected') + }); + + console.log('Proof sharing completed successfully'); +} catch (error) { + console.error('Error in bleShareProof:', error); +} +``` + +## Function Flow + +1. Starts the BLE transport for the agent (both inbound and outbound). +2. Initializes the central device and starts scanning for peripherals. +3. Sets up a disconnection notifier. +4. Discovers and connects to a peripheral device. +5. Notifies when connected. +6. Shares the proof by: + a. Receiving an out-of-band invitation. + b. Automatically responding to the proof request. +7. Handles the acknowledgment of the shared proof. + +## Error Handling + +If an error occurs during the execution of the function, it will: + +1. Log the error using the agent's logger. +2. Call the `onFailure` callback. +3. Throw the error for the caller to handle. + +## Peer Dependencies + +- `@credo-ts/core` +- `@credo-ts/anoncreds` +- `react` +- `react-native` + +## Notes + +- The function uses credo-ts for presentation exchange. +- It's designed to work with Bluetooth Low Energy, so make sure your environment supports BLE operations. +- The function handles the entire flow of requesting and receiving a proof over BLE, including connection management and message exchange. diff --git a/library/src/bleShareProof.ts b/library/src/bleShareProof.ts index 43f3f25..4b76e95 100644 --- a/library/src/bleShareProof.ts +++ b/library/src/bleShareProof.ts @@ -44,6 +44,7 @@ export const bleShareProof = async ({ const proofRecord = await shareProof(agent, central, serviceUuid) await handleAck(agent, central, proofRecord) + return proofRecord.id } catch (e) { if (e instanceof Error) { agent.config.logger.error(e.message, { cause: e })