@mosip/react-inji-verify-sdk 0.14.0-beta.10 β†’ 0.14.0-beta.11

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.
Files changed (2) hide show
  1. package/Readme.md +192 -236
  2. package/package.json +1 -1
package/Readme.md CHANGED
@@ -1,275 +1,231 @@
1
1
  # INJI VERIFY SDK
2
2
 
3
- Inji Verify SDK is a library which exposes React components for integrating Inji Verify features seamlessly into any relaying party application.
3
+ Inji Verify SDK provides ready-to-use **React components** to integrate [OpenID4VP](https://openid.net/specs/openid-4-verifiable-presentations-1_0.html)-based **Verifiable Credential (VC) verification** into any React TypeScript web application.
4
4
 
5
- ## Features
6
5
 
7
- - OpenId4VP component that creates QR code and performs OpenId4Vp sharing backend flow.
6
+ ## πŸš€ Usage Guide
8
7
 
9
- ## Usage
10
- `npm i @mosip/react-inji-verify-sdk`
11
-
12
- [npm](https://www.npmjs.com/package/@mosip/react-inji-verify-sdk)
13
-
14
- ## Local Publishing Guide
15
-
16
- Install the dependencies
17
- `npm install`
18
-
19
- Build the project
20
- `npm run build`
21
-
22
- 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 setup Verdaccio. Then run
24
- `npm publish --registry http://localhost:<VERADACCIO_PORT>`
25
-
26
- ## Integration Guide
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
33
-
34
- - Ract Project Setup
35
-
36
- > **NOTE**
37
- The component does not support other frontend frameworks like Angular, Vue, or React Native.
38
- The component is written in React + TypeScript
8
+ ### Step 1: Install the Package
9
+ ```bash
10
+ npm i @mosip/react-inji-verify-sdk
11
+ ```
39
12
 
13
+ ### Step 2: Import and Use
14
+ ```javascript
15
+ import { OpenID4VPVerification, QRCodeVerification } from "@mosip/react-inji-verify-sdk";
16
+ ```
40
17
 
41
- #### Backend Requirements
18
+ ### Step 3: Choose Your Verification Method
42
19
 
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 adehere to the OpenAPI spec defined [here]("../docs/api-documentation-openapi.yaml") in case if the backend service is not inji-verify-service.
20
+ **Option A: QR Code Verification (Scan & Upload)**
21
+ ```javascript
22
+ function MyApp() {
23
+ return (
24
+ <QRCodeVerification
25
+ verifyServiceUrl="https://your-backend.com/verify"
26
+ onVCProcessed={(result) => {
27
+ console.log("Verification complete:", result);
28
+ // Handle the verification result here
29
+ }}
30
+ onError={(error) => {
31
+ console.log("Something went wrong:", error);
32
+ }}
33
+ triggerElement={<button>πŸ“· Scan ID Document</button>}
34
+ />
35
+ );
36
+ }
37
+ ```
44
38
 
45
- > ⚠️ Important: The component expects these endpoints to be accessible via a base URL (verifyServiceUrl).
46
- Example:
47
- If you deploy the inji-verify/verify-service at:
48
- https://injiverify-service.example.com
49
- Then use this as the verifyServiceUrl in the component:
50
- verifyServiceUrl="https://injiverify-service.example.com/v1/verify"
39
+ **Option B: Digital Wallet Verification**
40
+ ```javascript
41
+ function MyApp() {
42
+ return (
43
+ <OpenID4VPVerification
44
+ verifyServiceUrl="https://your-backend.com/v1/verify"
45
+ presentationDefinitionId="your-definition-id"
46
+ onVpProcessed={(result) => {
47
+ console.log("Wallet verification complete:", result);
48
+ // Handle the verification result here
49
+ }}
50
+ onQrCodeExpired={() => alert("QR code expired, please try again")}
51
+ onError={(error) => console.log("Error:", error)}
52
+ triggerElement={<button>πŸ“± Verify with Digital Wallet</button>}
53
+ />
54
+ );
55
+ }
56
+ ```
51
57
 
52
- #### Installation
58
+ ## πŸ“‹ What You'll Get Back
53
59
 
54
- `npm i @mosip/react-inji-verify-sdk`
60
+ When verification is complete, you'll receive results like this:
55
61
 
56
- #### Component Props
62
+ ```javascript
63
+ {
64
+ vcResults: [
65
+ {
66
+ vc: { /* Your verified credential data */ },
67
+ vcStatus: "SUCCESS" // or "INVALID", "EXPIRED"
68
+ }
69
+ ],
70
+ vpResultStatus: "SUCCESS" // Overall verification status
71
+ }
72
+ ```
57
73
 
58
- ##### Exclusive Verification Flows
59
- <br/>
60
- > Only one of the following should be provided:
74
+ ## πŸ”§ Before You Start
61
75
 
76
+ ### What You Need:
77
+ 1. **A React project** (TypeScript recommended)
78
+ 2. **A verification backend** - You need a server that can verify credentials
79
+ 3. **Camera permissions** - For QR scanning features
62
80
 
63
- | Prop | Description |
64
- |----------------------------------------------|---------------------------------------------------|
65
- | `onVPReceived(txnId: string)` | Use when your backend fetches the VP result later |
66
- | `onVPProcessed(vpResult: VerificationResults)` | Use when the frontend needs the result directly |
81
+ ### Backend Requirements:
82
+ Your backend must support the OpenID4VP protocol. You can either:
83
+ - Use the official `inji-verify-service`
84
+ - Build your own following [this specification](https://openid.net/specs/openid-4-verifiable-presentations-1_0-ID3.html)
67
85
 
68
- ##### Presentation Definition Options
69
- <br/>
70
- > Only one of the following should be provided:
86
+ **Important:** Your backend URL should look like:
87
+ ```
88
+ https://your-backend.com
89
+ ```
71
90
 
72
- | Prop | Description |
73
- |----------------------------------------------|---------------------------------------------------|
74
- | `presentationDefinitionId` | Fetch a predefined definition from the backend |
75
- | `presentationDefinition` | Provide the full definition inline as a JSON object |
91
+ ## πŸ“– Detailed Component Guide
76
92
 
93
+ ### QRCodeVerification Component
77
94
 
78
- ##### Required Props
79
- <br/>
95
+ **Perfect for:** Scanning QR codes from documents or uploading QR codes (PNG, JPEG, JPG, PDF)
80
96
 
81
- | Prop | Type | Description |
82
- |------------------|----------------------|----------------------------------------|
83
- | `verifyServiceUrl` | `string` | Base URL for your verification backend |
84
- | `protocol` | `string` | Protocol for QR (e.g.: `"openid4vp://"`) |
85
- | `onQrCodeExpired` | `() => void` | Callback when QR expires |
86
- | `onError` | `(err: Error) => void` | Error handler callback |
97
+ #### Basic Setup:
98
+ ```javascript
99
+ <QRCodeVerification
100
+ verifyServiceUrl="https://your-backend.com"
101
+ onVCProcessed={(result) => handleResult(result)}
102
+ onError={(error) => handleError(error)}
103
+ triggerElement={<button>Start Verification</button>}
104
+ />
105
+ ```
87
106
 
88
- ##### Optional Props
89
- <br/>
107
+ #### All Available Options:
108
+ ```javascript
109
+ <QRCodeVerification
110
+ // Required
111
+ verifyServiceUrl="https://your-backend.com"
112
+ onVCProcessed={(result) => console.log(result)} // OR use onVCReceived
113
+ onError={(error) => console.log(error)}
114
+
115
+ // Optional
116
+ triggerElement={<button>Custom Trigger</button>}
117
+ transactionId="your-tracking-id" //Optional
118
+ uploadButtonId="my-upload-btn"
119
+ uploadButtonStyle={{ backgroundColor: 'blue' }}
120
+ isEnableUpload={true} // Allow file uploads
121
+ isEnableScan={true} // Allow camera scanning
122
+ isEnableZoom={true} // Allow camera zoom
123
+ />
124
+ ```
90
125
 
91
- | Prop | Type | Description |
92
- |----------------|-----------------|-----------------------------------------------------|
93
- | `triggerElement` | `React.ReactNode` | Element that triggers verification (e.g., a button) |
94
- | `transactionId` | `string` | Optional external tracking ID |
95
- | `qrCodeStyles` | `object` | Customize QR appearance (size, color, margin, etc.) |
126
+ **Choose One Callback:**
127
+ - `onVCProcessed`: Get full verification results immediately
128
+ - `onVCReceived`: Get just a transaction ID (your backend handles the rest)
96
129
 
97
- #### Integration Examples
130
+ ### OpenID4VPVerification Component
98
131
 
99
- ##### VP Result via UI (frontend receives result)
100
- <br/>
132
+ **Perfect for:** Integrating with digital wallets (like mobile ID apps)
101
133
 
102
- ```
134
+ #### Basic Setup:
135
+ ```javascript
103
136
  <OpenID4VPVerification
104
- triggerElement={<button>Start VP Verification</button>}
105
- protocol="openid4vp://"
106
- verifyServiceUrl="https://verifier.example.com/v1/verify"
107
- presentationDefinitionId="example-definition-id"
108
- onVPProcessed={(vpResult) => {
109
- console.log("VP Verified:", vpResult);
110
- }}
111
- onQrCodeExpired={() => alert("QR expired")}
112
- onError={(err) => console.error("Verification error:", err)}
137
+ verifyServiceUrl="https://your-backend.com"
138
+ presentationDefinitionId="what-you-want-to-verify"
139
+ onVpProcessed={(result) => handleResult(result)}
140
+ onQrCodeExpired={() => alert("Please try again")}
141
+ onError={(error) => handleError(error)}
113
142
  />
114
143
  ```
115
144
 
116
- ##### VP Result via Backend (frontend just gets txnId)
117
- <br/>
118
-
119
- ```
145
+ #### With Presentation Definition:
146
+ ```javascript
120
147
  <OpenID4VPVerification
121
- triggerElement={<button>Verify using Wallet</button>}
122
- protocol="openid4vp://"
123
- verifyServiceUrl="https://verifier.example.com/v1/verify"
124
- presentationDefinition={{
125
- id: "custom-def",
126
- input_descriptors: [/* your PD here */],
127
- }}
128
- onVPReceived={(txnId) => {
129
- // Send txnId to your backend to fetch the result later
130
- console.log("VP submission received, txn ID:", txnId);
131
- }}
148
+ verifyServiceUrl="https://your-backend.com"
149
+ presentationDefinition={"Refer Option 2 below"}
150
+ onVpProcessed={(result) => console.log(result)}
132
151
  onQrCodeExpired={() => alert("QR expired")}
133
- onError={(err) => console.error("Verification error:", err)}
152
+ onError={(error) => console.error(error)}
153
+ triggerElement={<button>πŸ” Verify Credentials</button>}
134
154
  />
135
155
  ```
136
156
 
137
- #### Testing the Component (for QA)
138
-
139
- - **Simulate Wallet Scan** : Use a mobile wallet app that supports OpenID4VP, or use mock tools to scan the QR code.
140
-
141
- - **Trigger Expiry** : Don't scan the QR and wait for expiry to ensure onQrCodeExpired fires.
142
-
143
- - **Force Errors** :
144
- - Stop the backend or simulate a 500 error.
145
- - Try missing required props or using both callbacks to see validation.
146
-
147
- ### QRCodeVerification
148
-
149
- 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.
150
-
151
- #### Component Props
152
- βœ… Required Props
153
- <br/>
154
-
155
- | Prop | Type | Description |
156
- |--------|------| ------------|
157
- | `verifyServiceUrl` | string | Backend service URL for VC submission or verification.|
158
- | `onError` | (error: Error) => void | Callback triggered on errors during scanning/upload.|
159
- |`onVCReceived or onVCProcessed` | See below |See below
160
-
161
- Only one of these callbacks should be provided.
162
-
163
- #### πŸ“Œ Callback Types
164
- Use one of the following:
165
-
166
- ##### onVCReceived
157
+ #### Define What to Verify:
167
158
 
168
- ```onVCReceived: (txnId: string) => void; ```
169
-
170
- Called when a Verifiable Presentation (VP) is received and submitted to the backend, returning the transaction ID
171
-
172
- ##### onVCProcessed
173
-
174
- ``` onVCProcessed: (vpResult: VerificationResults) => void; ```
175
-
176
- Called when the VP is verified, returning an array of verification result objects:
177
-
178
- ```type VerificationResult = { vc: unknown; vcStatus: "SUCCESS" | "INVALID" | "EXPIRED"; }; ```
179
-
180
- ``` type VerificationResults = VerificationResult[]; ```
181
-
182
- **⚠️ onVCReceived and onVCProcessed cannot be used simultaneously.**
183
-
184
- #### πŸ› οΈ Optional Props
185
- <br/>
186
-
187
- | Prop | Type | Default | Description |
188
- |------------------|--------------------|-----------------|-----------------------------------------------------|
189
- | `triggerElement` | `React.ReactNode` | null | Optional trigger to initiate the scan/upload (e.g., a button or label). |
190
- | `transactionId` | string | null | Optional external tracking ID |
191
- | `uploadButtonId` | `string` | "upload-qr" | Custom ID for upload button. |
192
- | `uploadButtonStyle` | `React.CSSProperties` | "upload-button-default" | Inline style object to apply custom styling to the upload button. |
193
- | `isEnableUpload` | boolean | true | Enables/disables QR-CODE image upload. |
194
- | `isEnableScan` | boolean | true | Enables/disables camera scanning. |
195
- | `isEnableZoom` | boolean | true | Enables camera zoom on mobile devices. |
196
-
197
- #### Upload Support
198
- Upload supports the following image types:
199
-
200
- - PNG
201
-
202
- - JPEG
203
-
204
- - JPG
205
-
206
- - PDF
207
-
208
- You can customize the upload button’s style using uploadButtonStyle, and control its placement with uploadButtonId.
209
-
210
- #### Callback Behaviour
211
-
212
- **onVCReceived** : Used when you want the VC sent to a backend and just need a txnId response.
213
-
214
- **onVCProcessed** : Used for apps that handle VC verification client-side and want full VC + status.
215
-
216
- **onError** : Handles all runtime, parsing, and scanning errors.
217
-
218
- The component will clean up camera streams and timers on unmount.
219
-
220
- #### Example with onVCProcessed
221
-
222
- ```
223
- <QRCodeVerification
224
- verifyServiceUrl="https://your-api/verify"
225
- onVCProcessed={(vpResult) => { console.log("VC + Status:", vpResult)}}
226
- onError={(e) => console.error("Error:", e.message)}
227
- triggerElement={<div className="btn-primary">Verify Now</div>}
228
- />
159
+ **Option 1: Use a predefined template**
160
+ ```javascript
161
+ presentationDefinitionId="drivers-license-check"
229
162
  ```
230
163
 
231
- #### Basic Usage
232
-
164
+ **Option 2: Define exactly what you want**
165
+ ```javascript
166
+ presentationDefinition={{
167
+ id: "custom-verification",
168
+ purpose: "We need to verify your identity",
169
+ format: {
170
+ ldp_vc: {
171
+ proof_type: ["Ed25519Signature2020"],
172
+ },
173
+ },
174
+ input_descriptors: [
175
+ {
176
+ id: "id-card-check",
177
+ constraints: {
178
+ fields: [
179
+ {
180
+ path: ["$.type"],
181
+ filter: {
182
+ type: "object",
183
+ pattern: "DriverLicenseCredential",
184
+ },
185
+ },
186
+ ],
187
+ },
188
+ },
189
+ ],
190
+ }}
233
191
  ```
234
- import {QRCodeVerification} from "@mosip/react-inji-verify-sdk";
235
- const App = () => {
236
- const handleVCReceived = (txnId: string) => {
237
- console.log("txnId received from VC submission:", txnId);
238
- };
239
- const handleError = (error: Error) => {
240
- console.error("Verification Error:", error.message);
241
- };
242
- return (
243
- <QRCodeVerification
244
- verifyServiceUrl="https://your-backend/verify"
245
- onVCReceived={handleVCReceived}
246
- onError={handleError}
247
- triggerElement={<button>Start Verification</button>}
248
- />
249
- );
250
- };
251
- ```
252
-
253
- #### Redirect Behavior
254
- 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:
255
-
256
-
257
- ```
258
- https://your-rp-domain.com/#vp_token=<base64url-encoded-token>
259
- ```
260
-
261
- ### Compatibility & Scope
262
-
263
- ##### Supported
264
-
265
- - βœ… ReactJS (with TypeScript)
266
-
267
- - βœ… Modern React projects (17+)
268
-
269
- ##### Not Supported
270
-
271
- - ❌ React Native
272
-
273
- - ❌ Angular, Vue, or other frontend frameworks
274
192
 
275
- - ❌ SSR frameworks like Next.js without customization
193
+ ## πŸŽ›οΈ Component Options Reference
194
+
195
+ ### Common Props (Both Components)
196
+
197
+ | Property | Type | Required | Description |
198
+ |----------|------|----------|-------------|
199
+ | `verifyServiceUrl` | string | βœ… | Your backend verification URL |
200
+ | `onError` | function | βœ… | What to do when something goes wrong |
201
+ | `triggerElement` | React element | ❌ | Custom button/element to start verification |
202
+ | `transactionId` | string | ❌ | Your own tracking ID |
203
+
204
+ ### QRCodeVerification Specific
205
+
206
+ | Property | Type | Default | Description |
207
+ |----------|------|---------|-------------|
208
+ | `onVCProcessed` | function | - | Get full results immediately |
209
+ | `onVCReceived` | function | - | Get transaction ID only |
210
+ | `isEnableUpload` | boolean | true | Allow file uploads |
211
+ | `isEnableScan` | boolean | true | Allow camera scanning |
212
+ | `isEnableZoom` | boolean | true | Allow camera zoom |
213
+ | `uploadButtonStyle` | object | - | Custom upload button styling |
214
+
215
+ ### OpenID4VPVerification Specific
216
+
217
+ | Property | Type | Default | Description |
218
+ |----------|------|---------|-------------|
219
+ | `protocol` | string | "openid4vp://" | Protocol for QR codes (optional) |
220
+ | `presentationDefinitionId` | string | - | Predefined verification template |
221
+ | `presentationDefinition` | object | - | Custom verification rules |
222
+ | `onVpProcessed` | function | - | Get full results immediately |
223
+ | `onVpReceived` | function | - | Get transaction ID only |
224
+ | `onQrCodeExpired` | function | - | Handle QR code expiration |
225
+ | `isEnableSameDeviceFlow` | boolean | true | Enable same-device flow (optional) |
226
+ | `qrCodeStyles` | object | - | Customize QR code appearance |
227
+
228
+ ## ⚠️ Important Limitations
229
+
230
+ - **React Only:** Won't work with Angular, Vue, or React Native
231
+ - **Backend Required:** You must have a verification service running
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mosip/react-inji-verify-sdk",
3
- "version": "0.14.0-beta.10",
3
+ "version": "0.14.0-beta.11",
4
4
  "description": "A react component library to perform Inji verify tasks, such as OpenId4VP sharing, Reading VC QR codes",
5
5
  "sideEffects": ["*.css"],
6
6
  "main": "dist/index.js",