@mosip/react-inji-verify-sdk 0.13.0-beta.7 → 0.13.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/Readme.md +233 -36
- package/package.json +1 -1
package/Readme.md
CHANGED
|
@@ -5,6 +5,7 @@ Inji Verify SDK is a library which exposes React components for integrating Inji
|
|
|
5
5
|
## Features
|
|
6
6
|
|
|
7
7
|
- OpenId4VP component that creates QR code and performs OpenId4Vp sharing backend flow.
|
|
8
|
+
- QRCodeVerification component that allows scanning and uploading images to verify the verifiable credentials.
|
|
8
9
|
|
|
9
10
|
## Usage
|
|
10
11
|
`npm i @mosip/react-inji-verify-sdk`
|
|
@@ -20,27 +21,21 @@ Build the project
|
|
|
20
21
|
`npm run build`
|
|
21
22
|
|
|
22
23
|
Publish the npm package using Verdaccio
|
|
23
|
-
We use [verdaccio](https://verdaccio.org/docs/what-is-verdaccio). `npm link` or `yarn link` won't work as we have peer dependencies. Follow the docs to
|
|
24
|
+
We use [verdaccio](https://verdaccio.org/docs/what-is-verdaccio). `npm link` or `yarn link` won't work as we have peer dependencies. Follow the docs to set up Verdaccio. Then run
|
|
24
25
|
`npm publish --registry http://localhost:<VERADACCIO_PORT>`
|
|
25
26
|
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
### OpenID4VPVerification
|
|
29
|
-
|
|
30
|
-
This guide walks you through integrating the OpenID4VPVerification component into your React TypeScript project. It facilitates Verifiable Presentation (VP) verification using the OpenID4VP protocol and supports flexible workflows, including client-side and backend-to-backend verification.
|
|
31
|
-
|
|
32
|
-
#### Prerequisites
|
|
27
|
+
### Prerequisites
|
|
33
28
|
|
|
34
|
-
-
|
|
29
|
+
- React Project Setup
|
|
35
30
|
|
|
36
31
|
> **NOTE**
|
|
37
32
|
The component does not support other frontend frameworks like Angular, Vue, or React Native.
|
|
38
33
|
The component is written in React + TypeScript
|
|
39
34
|
|
|
40
35
|
|
|
41
|
-
|
|
36
|
+
### Backend Requirements
|
|
42
37
|
|
|
43
|
-
To use the component, you must host a verification backend that implements the OpenID4VP protocol. This backend is referred to as the [inji-verify-service]("../Readme.md"). It also needs to
|
|
38
|
+
To use the component, you must host a verification backend that implements the OpenID4VP protocol. This backend is referred to as the [inji-verify-service]("../Readme.md"). It also needs to adhere to the OpenAPI spec defined [here]("../docs/api-documentation-openapi.yaml") in case if the backend service is not inji-verify-service.
|
|
44
39
|
|
|
45
40
|
> ⚠️ Important: The component expects these endpoints to be accessible via a base URL (verifyServiceUrl).
|
|
46
41
|
Example:
|
|
@@ -49,47 +44,147 @@ https://injiverify-service.example.com
|
|
|
49
44
|
Then use this as the verifyServiceUrl in the component:
|
|
50
45
|
verifyServiceUrl="https://injiverify-service.example.com/v1/verify"
|
|
51
46
|
|
|
52
|
-
|
|
47
|
+
## Integration Guide
|
|
53
48
|
|
|
54
|
-
|
|
49
|
+
### OpenID4VPVerification
|
|
50
|
+
|
|
51
|
+
This guide walks you through integrating the OpenID4VPVerification component into your React TypeScript project. It facilitates Verifiable Presentation (VP) verification using the OpenID4VP protocol and supports flexible workflows, including client-side and backend-to-backend verification.
|
|
55
52
|
|
|
56
53
|
#### Component Props
|
|
57
54
|
|
|
58
55
|
##### Exclusive Verification Flows
|
|
59
|
-
|
|
56
|
+
|
|
60
57
|
> Only one of the following should be provided:
|
|
61
58
|
|
|
62
59
|
|
|
63
|
-
| Prop
|
|
64
|
-
|
|
60
|
+
| Prop | Description |
|
|
61
|
+
|------------------------------------------------|---------------------------------------------------|
|
|
65
62
|
| `onVpReceived(txnId: string)` | Use when your backend fetches the VP result later |
|
|
66
63
|
| `onVpProcessed(vpResult: VerificationResults)` | Use when the frontend needs the result directly |
|
|
67
64
|
|
|
65
|
+
##### `onVpProcessed` Response Structure
|
|
66
|
+
```ts
|
|
67
|
+
type vpResultStatus = "SUCCESS" | "FAILED";
|
|
68
|
+
|
|
69
|
+
/*
|
|
70
|
+
* Individual VC verification result
|
|
71
|
+
*/
|
|
72
|
+
interface VerificationResult {
|
|
73
|
+
/**
|
|
74
|
+
* Verified credential data (structured per implementation).
|
|
75
|
+
*/
|
|
76
|
+
vc: Record<string, unknown>;
|
|
77
|
+
|
|
78
|
+
/**
|
|
79
|
+
* The status of the individual VC.
|
|
80
|
+
*/
|
|
81
|
+
vcStatus: VerificationStatus;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/*
|
|
85
|
+
* Individual VP verification result
|
|
86
|
+
*/
|
|
87
|
+
interface VerificationResults {
|
|
88
|
+
/**
|
|
89
|
+
* Array of individual VC verification results.
|
|
90
|
+
*/
|
|
91
|
+
vcResults: VerificationResult[];
|
|
92
|
+
|
|
93
|
+
/**
|
|
94
|
+
* The status of the overall Verifiable Presentation.
|
|
95
|
+
*/
|
|
96
|
+
vpResultStatus: vpResultStatus;
|
|
97
|
+
}
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
#### Example Usage
|
|
101
|
+
```tsx
|
|
102
|
+
<OpenID4VPVerification
|
|
103
|
+
triggerElement={<button>Start VP Verification</button>}
|
|
104
|
+
protocol="openid4vp://"
|
|
105
|
+
verifyServiceUrl="https://verifier.example.com/v1/verify"
|
|
106
|
+
presentationDefinitionId="example-definition-id"
|
|
107
|
+
onVpProcessed={(vpResult) => {
|
|
108
|
+
console.log("VP Verification Results:", vpResult);
|
|
109
|
+
}}
|
|
110
|
+
onQrCodeExpired={() => alert("QR expired")}
|
|
111
|
+
onError={(err) => console.error("Verification error:", err)}
|
|
112
|
+
/>;
|
|
113
|
+
```
|
|
114
|
+
#### Sample output structure:
|
|
115
|
+
```tx
|
|
116
|
+
VP Verification Results: {
|
|
117
|
+
vcResults: [
|
|
118
|
+
{
|
|
119
|
+
vc: "",
|
|
120
|
+
vcStatus: "",
|
|
121
|
+
},
|
|
122
|
+
],
|
|
123
|
+
vpResultStatus : "";
|
|
124
|
+
}
|
|
125
|
+
```
|
|
126
|
+
|
|
68
127
|
##### Presentation Definition Options
|
|
69
|
-
<br/>
|
|
70
|
-
> Only one of the following should be provided:
|
|
71
128
|
|
|
72
|
-
|
|
73
|
-
|----------------------------------------------|---------------------------------------------------|
|
|
74
|
-
| `presentationDefinitionId` | Fetch a predefined definition from the backend |
|
|
75
|
-
| `presentationDefinition` | Provide the full definition inline as a JSON object |
|
|
129
|
+
> Only one of the following should be provided:
|
|
76
130
|
|
|
131
|
+
| Prop | Description |
|
|
132
|
+
|----------------------------|-----------------------------------------------------|
|
|
133
|
+
| `presentationDefinitionId` | Fetch a predefined definition from the backend |
|
|
134
|
+
| `presentationDefinition` | Provide the full definition inline as a JSON object |
|
|
135
|
+
|
|
136
|
+
#### Example — Inline presentationDefinition Usage
|
|
137
|
+
|
|
138
|
+
If you want to directly provide a Presentation Definition instead of fetching it by ID, you can pass it like this:
|
|
139
|
+
|
|
140
|
+
```js
|
|
141
|
+
presentationDefinition = {
|
|
142
|
+
id: "c4822b58-7fb4-454e-b827-f8758fe27f9a",
|
|
143
|
+
purpose:
|
|
144
|
+
"Relying party is requesting your digital ID for the purpose of Self-Authentication",
|
|
145
|
+
format: {
|
|
146
|
+
ldp_vc: {
|
|
147
|
+
proof_type: ["Ed25519Signature2020"],
|
|
148
|
+
},
|
|
149
|
+
},
|
|
150
|
+
input_descriptors: [
|
|
151
|
+
{
|
|
152
|
+
id: "id card credential",
|
|
153
|
+
format: {
|
|
154
|
+
ldp_vc: {
|
|
155
|
+
proof_type: ["Ed25519Signature2020"],
|
|
156
|
+
},
|
|
157
|
+
},
|
|
158
|
+
constraints: {
|
|
159
|
+
fields: [
|
|
160
|
+
{
|
|
161
|
+
path: ["$.type"],
|
|
162
|
+
filter: {
|
|
163
|
+
type: "object",
|
|
164
|
+
pattern: "LifeInsuranceCredential",
|
|
165
|
+
},
|
|
166
|
+
},
|
|
167
|
+
],
|
|
168
|
+
},
|
|
169
|
+
},
|
|
170
|
+
],
|
|
171
|
+
};
|
|
172
|
+
```
|
|
173
|
+
> If you use `presentationDefinition`, do not pass `presentationDefinitionId`, and vice versa.
|
|
77
174
|
|
|
78
175
|
##### Required Props
|
|
79
|
-
<br/>
|
|
80
176
|
|
|
81
|
-
| Prop
|
|
82
|
-
|
|
83
|
-
| `verifyServiceUrl` | `string` | Base URL for your verification backend
|
|
84
|
-
| `protocol`
|
|
85
|
-
| `onQrCodeExpired` | `() => void` | Callback when QR expires
|
|
86
|
-
| `onError` | `(err: Error) => void` | Error handler callback
|
|
177
|
+
| Prop | Type | Description |
|
|
178
|
+
|--------------------|------------------------|------------------------------------------|
|
|
179
|
+
| `verifyServiceUrl` | `string` | Base URL for your verification backend |
|
|
180
|
+
| `protocol` | `string` | Protocol for QR (e.g.: `"openid4vp://"`) |
|
|
181
|
+
| `onQrCodeExpired` | `() => void` | Callback when QR expires |
|
|
182
|
+
| `onError` | `(err: Error) => void` | Error handler callback |
|
|
87
183
|
|
|
88
184
|
##### Optional Props
|
|
89
|
-
<br/>
|
|
90
185
|
|
|
91
|
-
| Prop
|
|
92
|
-
|
|
186
|
+
| Prop | Type | Description |
|
|
187
|
+
|------------------|-------------------|-----------------------------------------------------|
|
|
93
188
|
| `triggerElement` | `React.ReactNode` | Element that triggers verification (e.g., a button) |
|
|
94
189
|
| `transactionId` | `string` | Optional external tracking ID |
|
|
95
190
|
| `qrCodeStyles` | `object` | Customize QR appearance (size, color, margin, etc.) |
|
|
@@ -97,9 +192,8 @@ verifyServiceUrl="https://injiverify-service.example.com/v1/verify"
|
|
|
97
192
|
#### Integration Examples
|
|
98
193
|
|
|
99
194
|
##### VP Result via UI (frontend receives result)
|
|
100
|
-
<br/>
|
|
101
195
|
|
|
102
|
-
```
|
|
196
|
+
```tsx
|
|
103
197
|
<OpenID4VPVerification
|
|
104
198
|
triggerElement={<button>Start VP Verification</button>}
|
|
105
199
|
protocol="openid4vp://"
|
|
@@ -114,9 +208,8 @@ verifyServiceUrl="https://injiverify-service.example.com/v1/verify"
|
|
|
114
208
|
```
|
|
115
209
|
|
|
116
210
|
##### VP Result via Backend (frontend just gets txnId)
|
|
117
|
-
<br/>
|
|
118
211
|
|
|
119
|
-
```
|
|
212
|
+
```tsx
|
|
120
213
|
<OpenID4VPVerification
|
|
121
214
|
triggerElement={<button>Verify using Wallet</button>}
|
|
122
215
|
protocol="openid4vp://"
|
|
@@ -144,6 +237,110 @@ verifyServiceUrl="https://injiverify-service.example.com/v1/verify"
|
|
|
144
237
|
- Stop the backend or simulate a 500 error.
|
|
145
238
|
- Try missing required props or using both callbacks to see validation.
|
|
146
239
|
|
|
240
|
+
### QRCodeVerification
|
|
241
|
+
This guide walks you through integrating the QRCodeVerification component into your React TypeScript project. It facilitates QR code scanning and image upload to verify Verifiable Credentials (VCs) in your React application, including client-side and backend-to-backend verification.
|
|
242
|
+
|
|
243
|
+
#### Component Props
|
|
244
|
+
##### Required Props
|
|
245
|
+
|
|
246
|
+
| Prop | Type | Description |
|
|
247
|
+
|-----------------------------------|--------------------------|---------------------------------------------------------|
|
|
248
|
+
| `verifyServiceUrl` | `string` | Backend service URL for VC submission and verification. |
|
|
249
|
+
| `onError` | `(error: Error) => void` | Callback triggered on errors during scanning/upload. |
|
|
250
|
+
| `onVCReceived` or `onVCProcessed` | See below | Only one of these callbacks should be provided. |
|
|
251
|
+
|
|
252
|
+
##### Callback Types
|
|
253
|
+
Use one of the following:
|
|
254
|
+
|
|
255
|
+
`onVCReceived`
|
|
256
|
+
|
|
257
|
+
```
|
|
258
|
+
onVCReceived: (txnId: string) => void;
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
Called when a Verifiable Presentation (VP) is received and submitted to the backend, returning the transaction ID
|
|
262
|
+
|
|
263
|
+
`onVCProcessed`
|
|
264
|
+
|
|
265
|
+
```
|
|
266
|
+
onVCProcessed: (vpResult: VerificationResults) => void;
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
Called when the VP is verified, returning an array of verification result objects:
|
|
270
|
+
|
|
271
|
+
```ts
|
|
272
|
+
type VerificationResult = { vc: unknown; vcStatus: "SUCCESS" | "INVALID" | "EXPIRED"; }; type VerificationResults = VerificationResult[];
|
|
273
|
+
```
|
|
274
|
+
> `onVCReceived` and `onVCProcessed` cannot be used simultaneously.
|
|
275
|
+
|
|
276
|
+
##### Required Props
|
|
277
|
+
| Prop | Type | Default | Description |
|
|
278
|
+
|---------------------|-----------------------|:--------------------------|-------------------------------------------------------------------------|
|
|
279
|
+
| `triggerElement` | `React.ReactNode` | `null` | Optional trigger to initiate the scan/upload (e.g., a button or label). |
|
|
280
|
+
| `uploadButtonId` | `(string` | `"upload-qr"` | Custom ID for upload button. |
|
|
281
|
+
| `uploadButtonStyle` | `React.CSSProperties` | `"upload-button-default"` | Inline style object to apply custom styling to the upload button. |
|
|
282
|
+
| `isEnableUpload` | `boolean` | `true` | Enables/disables QR-CODE image upload. |
|
|
283
|
+
| `isEnableScan` | `boolean` | `true` | Enables/disables camera scanning. |
|
|
284
|
+
| `isEnableZoom` | `boolean` | `true` | Enables camera zoom on mobile devices. |
|
|
285
|
+
|
|
286
|
+
#### Upload Support
|
|
287
|
+
Upload supports the following image types:
|
|
288
|
+
|
|
289
|
+
* PNG
|
|
290
|
+
* JPEG
|
|
291
|
+
* JPG
|
|
292
|
+
* PDF
|
|
293
|
+
|
|
294
|
+
You can customize the upload button’s style using `uploadButtonStyle`, and control its placement with `uploadButtonId`.
|
|
295
|
+
|
|
296
|
+
#### Callback Behaviour
|
|
297
|
+
* `onVCReceived`: Used when you want the VC sent to a backend and just need a txnId response.
|
|
298
|
+
* `onVCProcessed`: Used for apps that handle VC verification client-side and want full VC + status.
|
|
299
|
+
* `onError`: Handles all runtime, parsing, and scanning errors.
|
|
300
|
+
|
|
301
|
+
> The component will clean up camera streams and timers on unmount.
|
|
302
|
+
|
|
303
|
+
##### Example with `onVCProcessed`
|
|
304
|
+
|
|
305
|
+
```tsx
|
|
306
|
+
<QRCodeVerification
|
|
307
|
+
verifyServiceUrl="https://your-api/verify"
|
|
308
|
+
onVCProcessed={(vpResult) => { console.log("VC + Status:", vpResult)}}
|
|
309
|
+
onError={(e) => console.error("Error:", e.message)}
|
|
310
|
+
triggerElement={<div className="btn-primary">Verify Now</div>}
|
|
311
|
+
/>
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
##### Basic Usage
|
|
315
|
+
|
|
316
|
+
```tsx
|
|
317
|
+
import {QRCodeVerification} from "@mosip/react-inji-verify-sdk";
|
|
318
|
+
const App = () => {
|
|
319
|
+
const handleVCReceived = (txnId: string) => {
|
|
320
|
+
console.log("txnId received from VC submission:", txnId);
|
|
321
|
+
};
|
|
322
|
+
const handleError = (error: Error) => {
|
|
323
|
+
console.error("Verification Error:", error.message);
|
|
324
|
+
};
|
|
325
|
+
return (
|
|
326
|
+
<QRCodeVerification
|
|
327
|
+
verifyServiceUrl="https://your-backend/verify"
|
|
328
|
+
onVCReceived={handleVCReceived}
|
|
329
|
+
onError={handleError}
|
|
330
|
+
triggerElement={<button>Start Verification</button>}
|
|
331
|
+
/>
|
|
332
|
+
);
|
|
333
|
+
};
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
#### Redirect Behavior
|
|
337
|
+
|
|
338
|
+
When using **Online Share QR Code**, the user is redirected to the client (issuer) server for processing, and then sent **back to the RP’s root path (`/`)** with the `vp_token` in the **URL fragment**:
|
|
339
|
+
|
|
340
|
+
```
|
|
341
|
+
https://your-rp-domain.com/#vp_token=<base64url-encoded-token>
|
|
342
|
+
```
|
|
343
|
+
|
|
147
344
|
|
|
148
345
|
### Compatibility & Scope
|
|
149
346
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mosip/react-inji-verify-sdk",
|
|
3
|
-
"version": "0.13.
|
|
3
|
+
"version": "0.13.1",
|
|
4
4
|
"description": "A react component library to perform Inji verify tasks, such as OpenId4VP sharing, Reading VC QR codes",
|
|
5
5
|
"main": "dist/index.js",
|
|
6
6
|
"module": "dist/index.js",
|