@uverifyng/react-native-liveness 0.1.0

package/README.md

@@ -0,0 +1,70 @@
+# UVerify liveness for React Native
+
+UVerify’s face check (liveness), and verification links, inside your React Native app.
+
+The check runs on UVerify’s hosted page, the same one your customers get in a browser, so every anti-spoofing layer (depth, colour flash, random prompts) applies, and improvements reach your app without an app update.
+
+```bash
+npm install @uverifyng/react-native-liveness react-native-webview
+```
+
+React Native 0.72+, `react-native-webview` 13+. iOS 14.3+ (camera inside web views), Android 7+.
+
+## Setup
+
+**iOS** — `Info.plist`:
+
+```xml
+<key>NSCameraUsageDescription</key>
+<string>We use the camera to confirm it’s really you.</string>
+```
+
+**Android** — `AndroidManifest.xml`:
+
+```xml
+<uses-permission android:name="android.permission.CAMERA" />
+```
+
+## Use
+
+Your **server** creates the session with a UVerify server SDK and returns its `url` and `id`. Never put your API key in the app.
+
+```tsx
+import { UVerifyWebView } from '@uverifyng/react-native-liveness';
+
+function FaceCheck({ session, onDone }) {
+  return (
+    <UVerifyWebView
+      url={session.url}
+      onFinish={(result) => {
+        if (result.type === 'liveness') onDone(result.sessionId, result.status); // 'passed' | 'failed' | 'expired'
+      }}
+      onCancel={(reason) => onDone(null, reason)} // 'back' | 'camera_denied'
+    />
+  );
+}
+```
+
+Then, on your server, run the face match with that session:
+
+```ts
+await uverify.identity.bvnFaceMatch({ id_number, first_name, last_name, liveness_session_id: sessionId });
+```
+
+The result in the app is only a hint to move on; **trust what your server gets from the API**.
+
+### Verification links
+
+The same component opens a verification link (`link.url` from `kyc.createLink`): `onFinish` receives `{ type: 'kyc', id, status, outcome }`.
+
+### Options
+
+| Prop | |
+|---|---|
+| `url` | The session or link `url` from your server |
+| `redirectUrl` | The `redirect_url` you created it with, if any; reaching it also finishes (`{ type: 'redirect', params }`) |
+| `onFinish(result)` | The flow finished |
+| `onCancel(reason)` | Back button, or the camera was refused |
+| `allowedHosts` | Extra hosts allowed in the view (UVerify’s are always allowed; everything else is blocked) |
+
+MIT licence.

package/dist/UVerifyWebView.d.ts

@@ -0,0 +1,26 @@
+import React from 'react';
+import { type StyleProp, type ViewStyle } from 'react-native';
+import { type UVerifyResult } from './events';
+export interface UVerifyWebViewProps {
+    /** A liveness session's `url`, or a verification link's `url` (from your server, via the UVerify API). */
+    url: string;
+    /** The redirect_url you created the session/link with, if any: reaching it also finishes. */
+    redirectUrl?: string;
+    /** The flow finished. For liveness, pass `result.sessionId` to your server for the face match. */
+    onFinish: (result: UVerifyResult) => void;
+    /** The person backed out (Android back button) or refused the camera. */
+    onCancel?: (reason: 'back' | 'camera_denied') => void;
+    /** Extra hosts to allow (default: uverify.com.ng and its subdomains). */
+    allowedHosts?: string[];
+    style?: StyleProp<ViewStyle>;
+}
+/**
+ * UVerify's hosted face check (or a verification link) inside your app. The
+ * check itself runs on UVerify's page, the same one customers get in a
+ * browser, so every anti-spoofing layer applies and improvements reach your
+ * app without an update.
+ *
+ * Needs the camera permission: add NSCameraUsageDescription to Info.plist and
+ * <uses-permission android:name="android.permission.CAMERA" /> to AndroidManifest.xml.
+ */
+export declare function UVerifyWebView({ url, redirectUrl, onFinish, onCancel, allowedHosts, style }: UVerifyWebViewProps): React.JSX.Element;

package/dist/UVerifyWebView.js

@@ -0,0 +1,116 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UVerifyWebView = UVerifyWebView;
+const react_1 = __importStar(require("react"));
+const react_native_1 = require("react-native");
+const react_native_webview_1 = require("react-native-webview");
+const events_1 = require("./events");
+/**
+ * UVerify's hosted face check (or a verification link) inside your app. The
+ * check itself runs on UVerify's page, the same one customers get in a
+ * browser, so every anti-spoofing layer applies and improvements reach your
+ * app without an update.
+ *
+ * Needs the camera permission: add NSCameraUsageDescription to Info.plist and
+ * <uses-permission android:name="android.permission.CAMERA" /> to AndroidManifest.xml.
+ */
+function UVerifyWebView({ url, redirectUrl, onFinish, onCancel, allowedHosts = [], style }) {
+    const [cameraOk, setCameraOk] = (0, react_1.useState)(react_native_1.Platform.OS !== 'android');
+    const [denied, setDenied] = (0, react_1.useState)(false);
+    const done = (0, react_1.useRef)(false);
+    const hosts = ['uverify.com.ng', ...allowedHosts.map((h) => h.toLowerCase())];
+    const finish = (0, react_1.useCallback)((r) => {
+        if (done.current)
+            return;
+        done.current = true;
+        onFinish(r);
+    }, [onFinish]);
+    // Android: ask for the camera before the page does (the web view can only use it if the app has it).
+    (0, react_1.useEffect)(() => {
+        if (react_native_1.Platform.OS !== 'android')
+            return;
+        react_native_1.PermissionsAndroid.request(react_native_1.PermissionsAndroid.PERMISSIONS.CAMERA).then((r) => {
+            if (r === react_native_1.PermissionsAndroid.RESULTS.GRANTED)
+                setCameraOk(true);
+            else {
+                setDenied(true);
+                onCancel?.('camera_denied');
+            }
+        });
+    }, [onCancel]);
+    (0, react_1.useEffect)(() => {
+        const sub = react_native_1.BackHandler.addEventListener('hardwareBackPress', () => {
+            if (done.current)
+                return false;
+            done.current = true;
+            onCancel?.('back');
+            return true;
+        });
+        return () => sub.remove();
+    }, [onCancel]);
+    const onMessage = (e) => {
+        const r = (0, events_1.parseMessage)(e.nativeEvent.data);
+        if (r)
+            finish(r);
+    };
+    const onShouldStart = (req) => {
+        const r = (0, events_1.parseRedirect)(req.url, redirectUrl);
+        if (r) {
+            finish(r);
+            return false;
+        }
+        return (0, events_1.isAllowed)(req.url, hosts);
+    };
+    if (denied) {
+        return (react_1.default.createElement(react_native_1.View, { style: [styles.center, style] },
+            react_1.default.createElement(react_native_1.Text, { style: styles.text }, "Camera access is needed for the face check. Allow it in Settings, then try again.")));
+    }
+    if (!cameraOk) {
+        return (react_1.default.createElement(react_native_1.View, { style: [styles.center, style] },
+            react_1.default.createElement(react_native_1.ActivityIndicator, null)));
+    }
+    return (react_1.default.createElement(react_native_webview_1.WebView, { style: [styles.fill, style], source: { uri: url }, originWhitelist: ['https://*'], onMessage: onMessage, onShouldStartLoadWithRequest: onShouldStart, javaScriptEnabled: true, domStorageEnabled: true, 
+        // iOS: camera inside the page, inline (not full-screen), no second prompt from WebKit.
+        allowsInlineMediaPlayback: true, mediaPlaybackRequiresUserAction: false, mediaCapturePermissionGrantType: "grant", 
+        // Android: react-native-webview passes the page's camera request through once the app holds CAMERA (asked above).
+        setSupportMultipleWindows: false, startInLoadingState: true, renderLoading: () => (react_1.default.createElement(react_native_1.View, { style: styles.center },
+            react_1.default.createElement(react_native_1.ActivityIndicator, null))) }));
+}
+const styles = react_native_1.StyleSheet.create({
+    fill: { flex: 1 },
+    center: { flex: 1, alignItems: 'center', justifyContent: 'center', padding: 24 },
+    text: { textAlign: 'center', fontSize: 15, color: '#444' },
+});

package/dist/events.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Pure logic, shared by the component and its tests: what the hosted page
+ * tells the app, and how a redirect back to your site is read.
+ */
+export type UVerifyResult = {
+    type: 'liveness';
+    sessionId: string;
+    status: 'passed' | 'failed' | 'expired';
+} | {
+    type: 'kyc';
+    id: string;
+    status: string;
+    outcome: string | null;
+} | {
+    type: 'redirect';
+    url: string;
+    params: Record<string, string>;
+};
+/** The hosted page's "finished" message (posted by uverify.com.ng), or null if it's something else. */
+export declare function parseMessage(data: string): UVerifyResult | null;
+/** The page is sending the person back to your redirect_url: finish with its query parameters. */
+export declare function parseRedirect(url: string, redirectUrl: string | undefined): UVerifyResult | null;
+/** Only UVerify's pages (and about:blank) load in the view; anything else is refused. */
+export declare function isAllowed(url: string, hosts: string[]): boolean;

package/dist/events.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseMessage = parseMessage;
+exports.parseRedirect = parseRedirect;
+exports.isAllowed = isAllowed;
+/** The hosted page's "finished" message (posted by uverify.com.ng), or null if it's something else. */
+function parseMessage(data) {
+    let m;
+    try {
+        m = JSON.parse(data);
+    }
+    catch {
+        return null;
+    }
+    if (m?.source !== 'uverify')
+        return null;
+    if (m.type === 'liveness.finished' && typeof m.session_id === 'string')
+        return { type: 'liveness', sessionId: m.session_id, status: m.status };
+    if (m.type === 'kyc.finished' && typeof m.id === 'string')
+        return { type: 'kyc', id: m.id, status: m.status, outcome: m.outcome ?? null };
+    return null;
+}
+/** The page is sending the person back to your redirect_url: finish with its query parameters. */
+function parseRedirect(url, redirectUrl) {
+    if (!redirectUrl)
+        return null;
+    const strip = (u) => u.split('?')[0].split('#')[0].replace(/\/+$/, '');
+    if (strip(url) !== strip(redirectUrl))
+        return null;
+    const params = {};
+    const q = url.split('#')[0].split('?')[1] ?? '';
+    for (const pair of q.split('&').filter(Boolean)) {
+        const [k, v = ''] = pair.split('=');
+        params[decodeURIComponent(k)] = decodeURIComponent(v.replace(/\+/g, ' '));
+    }
+    return { type: 'redirect', url, params };
+}
+/** Only UVerify's pages (and about:blank) load in the view; anything else is refused. */
+function isAllowed(url, hosts) {
+    if (url === 'about:blank')
+        return true;
+    const m = url.match(/^https:\/\/([^/?#:]+)/i);
+    return !!m && hosts.some((h) => m[1].toLowerCase() === h || m[1].toLowerCase().endsWith(`.${h}`));
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { UVerifyWebView } from './UVerifyWebView';
+export type { UVerifyWebViewProps } from './UVerifyWebView';
+export { isAllowed, parseMessage, parseRedirect } from './events';
+export type { UVerifyResult } from './events';

package/dist/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseRedirect = exports.parseMessage = exports.isAllowed = exports.UVerifyWebView = void 0;
+var UVerifyWebView_1 = require("./UVerifyWebView");
+Object.defineProperty(exports, "UVerifyWebView", { enumerable: true, get: function () { return UVerifyWebView_1.UVerifyWebView; } });
+var events_1 = require("./events");
+Object.defineProperty(exports, "isAllowed", { enumerable: true, get: function () { return events_1.isAllowed; } });
+Object.defineProperty(exports, "parseMessage", { enumerable: true, get: function () { return events_1.parseMessage; } });
+Object.defineProperty(exports, "parseRedirect", { enumerable: true, get: function () { return events_1.parseRedirect; } });

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@uverifyng/react-native-liveness",
+  "version": "0.1.0",
+  "description": "UVerify's face check (liveness) and verification links inside a React Native app.",
+  "license": "MIT",
+  "author": "Elasto Web Services Limited",
+  "homepage": "https://uverify.com.ng/docs",
+  "repository": { "type": "git", "url": "https://github.com/elastodev/uverify-sdks", "directory": "react-native" },
+  "keywords": ["uverify", "liveness", "face-match", "kyc", "react-native", "nigeria"],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-native": ">=0.72",
+    "react-native-webview": ">=13"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.0",
+    "react": "^18.3.1",
+    "react-native": "^0.76.0",
+    "react-native-webview": "^13.12.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}