@injistack/react-inji-verify-sdk 0.17.0-beta.12

package/README.md

@@ -0,0 +1,247 @@
+# INJI VERIFY SDK
+
+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) and Verifiable Presentation (VP) verification** into any React TypeScript web application.
+
+
+## Usage Guide
+
+### Step 1: Install the Package
+```bash
+npm i @injistack/react-inji-verify-sdk
+```
+
+### Step 2: Import and Use
+```javascript
+import { OpenID4VPVerification, QRCodeVerification } from "@injistack/react-inji-verify-sdk";
+```
+
+### Step 3: Choose Your Verification Method
+
+**Option A: QR Code Verification (Scan & Upload)**
+```javascript
+function MyApp() {
+  return (
+    <QRCodeVerification
+      verifyServiceUrl="https://your-backend.com/verify"
+      onVCProcessed={(result) => {
+        console.log("Verification complete:", result);
+        // Handle the verification result here
+      }}
+      onError={(error) => {
+        console.log("Something went wrong:", error);
+      }}
+      triggerElement={<button>📷 Scan ID Document</button>}
+      clientId="CLIENT_ID"
+    />
+  );
+}
+```
+
+**Option B: OpenID4VP Verification**
+```javascript
+function MyApp() {
+  return (
+    <OpenID4VPVerification
+      verifyServiceUrl="https://your-backend.com/v1/verify"
+      presentationDefinitionId="your-definition-id"
+      onVpProcessed={(result) => {
+        console.log("Wallet verification complete:", result);
+        // Handle the verification result here
+      }}
+      onQrCodeExpired={() => alert("QR code expired, please try again")}
+      onError={(error) => console.log("Error:", error)}
+      triggerElement={<button>📱 Verify with Digital Wallet</button>}
+      clientId="CLIENT_ID"
+    />
+  );
+}
+```
+
+## Response Received
+
+When verification is completed, the response received is as below:
+
+```javascript
+{
+  vcResults: [
+    {
+      vc: { /* Your verified credential data */ },
+      vcStatus: "SUCCESS" // or  "INVALID", "EXPIRED"
+    }
+  ],
+  vpResultStatus: "SUCCESS" // Overall verification status
+}
+```
+>**Security Recommendation**
+>
+>Avoid consuming results directly from VPProcessed or VCProcessed.
+Instead, use VPReceived or VCReceived events to capture the txnId, then retrieve the verification results securely from your backend's verification service endpoint.
+This ensures data integrity and prevents reliance on client-side verification data for final decisions.
+
+## Pre-requisites
+
+### What You Need:
+1. **A React project** (TypeScript recommended)
+2. **A verification backend** - You need a server that can verify credentials
+3. **Camera permissions** - For QR scanning features
+
+### Backend Requirements:
+Your backend must support the OpenID4VP protocol. You can either:
+- Use the official `inji-verify-service`
+- Build your own following [this specification](https://openid.net/specs/openid-4-verifiable-presentations-1_0-ID3.html)
+
+**Important:** Your backend URL should look like:
+```
+https://your-backend.com
+```
+
+## 📖 Detailed Component Guide
+
+### QRCodeVerification Component
+
+**Perfect for:** Scanning QR codes from documents or uploading QR codes (PNG, JPEG, JPG, PDF)
+
+#### Basic Setup:
+```javascript
+<QRCodeVerification
+  verifyServiceUrl="https://your-backend.com"
+  onVCProcessed={(result) => handleResult(result)}
+  onError={(error) => handleError(error)}
+  triggerElement={<button>Start Verification</button>}
+  clientId="CLIENT_ID"
+/>
+```
+
+#### All Available Options:
+```javascript
+<QRCodeVerification
+  // Required
+  verifyServiceUrl="https://your-backend.com"
+  onVCProcessed={(result) => console.log(result)}  // OR use onVCReceived
+  onError={(error) => console.log(error)}
+  clientId="CLIENT_ID"
+
+  // Optional
+  triggerElement={<button>Custom Trigger</button>}
+  transactionId="your-tracking-id"  //Optional
+  uploadButtonId="my-upload-btn"
+  uploadButtonStyle={{ backgroundColor: 'blue' }}
+  isEnableUpload={true}        // Allow file uploads
+  isEnableScan={true}          // Allow camera scanning  
+  isEnableZoom={true}          // Allow camera zoom
+  isVPSubmissionSupported={false}  // This attribute indicates whether VP submission is supported in Inji OVP VC sharing flow. By default, it is false which means that VP token will be directly sent in response. If set to true, then VP token will be submitted to the VP_SUBMISSION_ URL.
+  acceptVPWithoutHolderProof={false} // This attribute controls whether unsigned Verifiable Presentations (VPs without proof) are allowed in the Inji OVP VC sharing flow. By default, it is set to false, meaning unsigned VP tokens are not supported and an error is thrown if an unsigned VP is received. If set to true, VP tokens without a signature (proof) are allowed and can be verified. For data-share it is set to true by default.
+/>
+```
+
+**Choose One Callback:**
+- `onVCProcessed`: Get full verification results immediately
+- `onVCReceived`: Get just a transaction ID (your backend handles the rest)
+
+### OpenID4VPVerification Component
+
+**Perfect for:** Integrating with digital wallets (like mobile ID apps)
+
+#### Basic Setup:
+```javascript
+<OpenID4VPVerification
+  verifyServiceUrl="https://your-backend.com"
+  presentationDefinitionId="what-you-want-to-verify"
+  onVpProcessed={(result) => handleResult(result)}
+  onQrCodeExpired={() => alert("Please try again")}
+  onError={(error) => handleError(error)}
+  clientId="CLIENT_ID"
+/>
+```
+
+#### With Presentation Definition:
+```javascript
+<OpenID4VPVerification
+  verifyServiceUrl="https://your-backend.com"
+  presentationDefinition={"Refer Option 2 below"}
+  onVpProcessed={(result) => console.log(result)}
+  onQrCodeExpired={() => alert("QR expired")}
+  onError={(error) => console.error(error)}
+  triggerElement={<button>🔐 Verify Credentials</button>}
+  clientId="CLIENT_ID"
+/>
+```
+
+#### Define What to Verify:
+
+**Option 1: Use a predefined template**
+```javascript
+presentationDefinitionId="drivers-license-check"
+```
+
+**Option 2: Define exactly what you want**
+```javascript
+presentationDefinition={{
+  id: "custom-verification",
+  purpose: "We need to verify your identity",
+  format: {
+    ldp_vc: {
+      proof_type: ["Ed25519Signature2020"],
+    },
+  },
+  input_descriptors: [
+    {
+      id: "id-card-check",
+      constraints: {
+        fields: [
+          {
+            path: ["$.type"],
+            filter: {
+              type: "object",
+              pattern: "DriverLicenseCredential",
+            },
+          },
+        ],
+      },
+    },
+  ],
+}}
+```
+
+## 🎛️ Component Options Reference
+
+### Common Props (Both Components)
+
+| Property                         | Type          | Required | Description                                 |
+|----------------------------------|---------------|----------|---------------------------------------------|
+| `verifyServiceUrl`               | string        | ✅       | Backend verification URL                    |
+| `onError`                        | function      | ✅       | Callback invoked when an error occurs       |
+| `triggerElement`                 | React element | ❌       | Custom button/element to start verification |
+| `transactionId`                  | string        | ❌       | Optional client-side tracking ID            |
+| `clientId`                       | string        | ✅       | Client identifier                           |
+| `acceptVPWithoutHolderProof`     | boolean       | ❌       | Allow unsigned Verifiable Presentations     |
+
+### QRCodeVerification Specific
+
+| Property                  | Type     | Default | Description                  |
+|---------------------------|----------|---------|------------------------------|
+| `onVCProcessed`           | function | -       | Get full results immediately |
+| `onVCReceived`            | function | -       | Get transaction ID only      |
+| `isEnableUpload`          | boolean  | true    | Allow file uploads           |
+| `isEnableScan`            | boolean  | true    | Allow camera scanning        |
+| `isEnableZoom`            | boolean  | true    | Allow camera zoom            |
+| `uploadButtonStyle`       | object   | -       | Custom upload button styling |
+| `isVPSubmissionSupported` | Boolean  | false   | Toggle VP submission support |
+
+### OpenID4VPVerification Specific
+
+| Property                   | Type     | Default        | Description                        |
+|----------------------------|----------|----------------|------------------------------------|
+| `protocol`                 | string   | "openid4vp://" | Protocol for QR codes (optional)   |
+| `presentationDefinitionId` | string   | -              | Predefined verification template   |
+| `presentationDefinition`   | object   | -              | Custom verification rules          |
+| `onVpProcessed`            | function | -              | Get full results immediately       |
+| `onVpReceived`             | function | -              | Get transaction ID only            |
+| `onQrCodeExpired`          | function | -              | Handle QR code expiration          |
+| `isSameDeviceFlowEnabled`  | boolean  | true           | Enable same-device flow (optional) |
+| `qrCodeStyles`             | object   | -              | Customize QR code appearance       |
+
+## ⚠️ Important Limitations
+
+- **React Only:** Won't work with Angular, Vue, or React Native
+- **Backend Required:** You must have a verification service running

package/dist/components/openid4vp-verification/OpenID4VPVerification.d.ts

@@ -0,0 +1,6 @@
+import React from "react";
+import { OpenID4VPVerificationProps } from "./OpenID4VPVerification.types";
+import "./OpenID4VPVerification.css";
+export declare const isMobileDevice: () => boolean;
+declare const OpenID4VPVerification: React.FC<OpenID4VPVerificationProps>;
+export default OpenID4VPVerification;

package/dist/components/openid4vp-verification/OpenID4VPVerification.types.d.ts

@@ -0,0 +1,139 @@
+/// <reference types="react" />
+export type VerificationStatus = "valid" | "invalid" | "expired";
+export interface VerificationResult {
+    /**
+    
+    Verified credential data (structured per implementation).
+    */
+    vc: Record<string, unknown>;
+    /**
+    
+    The status of the verification.
+    */
+    vcStatus: VerificationStatus;
+}
+export type VerificationResults = VerificationResult[];
+export interface VPRequestBody {
+    clientId: string;
+    nonce: string;
+    transactionId?: string;
+    presentationDefinitionId?: string;
+    presentationDefinition?: PresentationDefinition;
+    acceptVPWithoutHolderProof?: boolean;
+}
+type ExclusivePresentationDefinition = 
+/**
+ * ID of the presentation definition used for verification.
+ * Required for some verification flows.
+ */
+{
+    presentationDefinitionId: string;
+    presentationDefinition?: never;
+}
+/**
+ * The full presentation definition JSON string.
+ * If provided, it will be used instead of fetching from the backend.
+ */
+ | {
+    presentationDefinition?: PresentationDefinition;
+    presentationDefinitionId?: never;
+};
+type ExclusiveCallbacks = 
+/**
+ * Callback triggered when the verification presentation (VP) is received.
+ * Provides the associated transaction ID.
+ */
+{
+    onVPReceived: (transactionId: string) => void;
+    onVPProcessed?: never;
+}
+/**
+ * Callback triggered when the VP is successfully processed.
+ * Provides the verification result data.
+ */
+ | {
+    onVPProcessed: (VPResult: VerificationResults) => void;
+    onVPReceived?: never;
+};
+interface InputDescriptor {
+    id: string;
+    format?: {
+        ldp_vc: {
+            proof_type: string[];
+        };
+    };
+    constraints?: {};
+}
+export interface PresentationDefinition {
+    id?: string;
+    purpose: string;
+    format?: {
+        ldp_vc: {
+            proof_type: string[];
+        };
+    };
+    input_descriptors: InputDescriptor[];
+}
+export type OpenID4VPVerificationProps = ExclusivePresentationDefinition & ExclusiveCallbacks & {
+    /**
+     React element that triggers the verification process (e.g., a button).
+     If not provided, the component may automatically start the process.
+     */
+    triggerElement?: React.ReactNode;
+    /**
+     The backend service URL where the verification request will be sent.
+     */
+    verifyServiceUrl: string;
+    /**
+     The client identifier for relaying party.
+     */
+    clientId: string;
+    /**
+     The protocol being used for verification (e.g., OpenID4VP).
+     */
+    protocol?: string;
+    /**
+     A unique identifier for the transaction.
+     */
+    transactionId?: string;
+    /**
+     Indicates whether the same device flow is enabled.
+     Defaults to true, allowing verification on the same device.
+     */
+    isSameDeviceFlowEnabled?: boolean;
+    /**
+     Styling options for the QR code.
+     */
+    qrCodeStyles?: {
+        size?: number;
+        level?: "L" | "M" | "Q" | "H";
+        bgColor?: string;
+        fgColor?: string;
+        margin?: number;
+        borderRadius?: number;
+    };
+    /**
+     * Callback triggered when the QR code expires before verification is completed.
+     */
+    onQrCodeExpired: () => void;
+    /**
+     * Callback triggered when an error occurs during the verification process.
+     * This is a required field to ensure proper error handling.
+     */
+    onError: (error: AppError) => void;
+    /**
+     Indicates whether to accept VP submissions without holder proof.
+     When true, allows unsigned VPs (VPs without proof).
+     */
+    acceptVPWithoutHolderProof?: boolean;
+};
+export interface SessionState {
+    requestId: string;
+    transactionId: string;
+}
+export type AppError = {
+    errorMessage: string;
+    errorCode?: string;
+    transactionId?: string | null;
+};
+export {};

package/dist/components/qrcode-verification/QRCodeVerification.d.ts

@@ -0,0 +1,5 @@
+/// <reference types="react" />
+import { QRCodeVerificationProps } from "./QRCodeVerification.types";
+import "./QRCodeVerification.css";
+declare const QRCodeVerification: React.FC<QRCodeVerificationProps>;
+export default QRCodeVerification;

package/dist/components/qrcode-verification/QRCodeVerification.types.d.ts

@@ -0,0 +1,105 @@
+/// <reference types="react" />
+type ExclusiveCallbacks = 
+/**
+ * Callback triggered when the verification presentation (VP) is received.
+ * Provides the associated transaction ID.
+ */
+{
+    onVCReceived: (txnId: string) => void;
+    onVCProcessed?: never;
+}
+/**
+ * Callback triggered when the VP is successfully processed.
+ * Provides the verification result data.
+ */
+ | {
+    onVCProcessed: (vpResult: VerificationResults) => void;
+    onVCReceived?: never;
+};
+export type QRCodeVerificationProps = ExclusiveCallbacks & {
+    /**
+     * React element that triggers the verification process (e.g., a button).
+     * If not provided, the component may automatically start the process.
+     */
+    triggerElement?: React.ReactNode;
+    /**
+     * The backend service URL where the verification request will be sent.
+     * This is a required field.
+     */
+    verifyServiceUrl: string;
+    /**
+    
+    * A unique identifier for the transaction.
+    */
+    transactionId?: string;
+    /**
+     * Callback triggered when an error occurs during the verification process.
+     * This is a required field to ensure proper error handling.
+     */
+    onError: (error: Error) => void;
+    /**
+     * Upload button config.
+     */
+    uploadButtonId?: string;
+    uploadButtonStyle?: string;
+    /**
+     * Enable camera zoom (mobile).
+     */
+    isEnableZoom?: boolean;
+    /**
+     * Enable upload functionality.
+     * Defaults to true.
+     */
+    isEnableUpload?: boolean;
+    /**
+     * Enable scan functionality.
+     * Defaults to true.
+     */
+    isEnableScan?: boolean;
+    /**
+     * Callback invoked when the scanner is closed.
+     * Can be used to redirect to home or perform cleanup.
+     */
+    onClose?: () => void;
+    /**
+     * Enable scan functionality.
+     * Defaults to true.
+     */
+    scannerActive?: boolean;
+    /**
+     * A unique identifier for the client application.
+     * Used in the OVP redirect flow.
+     */
+    clientId: string;
+    /**
+     * Enable Data share VP Supported functionality.
+     * Defaults to false.
+     */
+    isVPSubmissionSupported?: boolean;
+    /**
+     Indicates whether to accept VP submissions without holder proof.
+     When true, allows unsigned VPs (VPs without proof).
+     */
+    acceptVPWithoutHolderProof?: boolean;
+};
+interface VerificationResult {
+    /**
+     * Verified credential data (structure depends on implementation).
+     */
+    vc: unknown;
+    /**
+     * The status of the verification (e.g., "valid", "invalid", "expired").
+     */
+    vcStatus: VcStatus;
+}
+export type VerificationResults = VerificationResult[];
+export type VcStatus = "SUCCESS" | "INVALID" | "EXPIRED";
+export type scanResult = {
+    data: any;
+    error: Error | null;
+};
+export interface vcSubmissionBody {
+    vc: any;
+    transactionId?: string;
+}
+export {};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { default as OpenID4VPVerification } from '././components/openid4vp-verification/OpenID4VPVerification';
+export { default as QRCodeVerification } from '././components/qrcode-verification/QRCodeVerification';