@kwik-id/sdk-react-native 0.0.0-stage → 0.1.0-alpha.0

package/src/api/upload.ts

@@ -0,0 +1,87 @@
+/**
+ * Multipart upload for RN via expo-file-system (gives real upload progress, which
+ * RN's fetch/FormData path cannot). The gateway's multer expects the field `file`.
+ */
+import { FileSystemUploadType, createUploadTask } from "expo-file-system";
+
+import type { CaptureAsset } from "../types";
+import { ApiError } from "./api-error";
+
+export interface UploadResult {
+    uploadId: string;
+    status: string;
+}
+
+export type Uploader = (opts: {
+    url: string;
+    asset: CaptureAsset;
+    headers: Record<string, string>;
+    onProgress?: (pct: number) => void;
+    /**
+     * Inactivity timeout in ms: the upload is cancelled and rejected when no progress
+     * (or response) arrives for this long. Omit or pass 0 to disable.
+     */
+    timeoutMs?: number;
+}) => Promise<UploadResult>;
+
+function parseBody(body: string): { uploadId?: string; status?: string; message?: string } {
+    try {
+        return JSON.parse(body);
+    } catch {
+        return {};
+    }
+}
+
+/** Default uploader — used on device. */
+export const uploadMultipart: Uploader = async ({ url, asset, headers, onProgress, timeoutMs }) => {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let rejectTimeout: (error: Error) => void = () => undefined;
+    const timedOut = new Promise<never>((_, reject) => {
+        rejectTimeout = reject;
+    });
+    // Reset on every progress event so a slow-but-moving upload isn't killed.
+    const armTimeout = () => {
+        if (!timeoutMs) return;
+        if (timer) clearTimeout(timer);
+        timer = setTimeout(() => {
+            task.cancelAsync().catch(() => undefined);
+            rejectTimeout(new ApiError("Upload timeout", 0, "UPLOAD_TIMEOUT"));
+        }, timeoutMs);
+    };
+
+    const task = createUploadTask(
+        url,
+        asset.uri,
+        {
+            httpMethod: "POST",
+            uploadType: FileSystemUploadType.MULTIPART,
+            fieldName: "file",
+            mimeType: asset.type,
+            headers,
+        },
+        (p) => {
+            armTimeout();
+            if (p.totalBytesExpectedToSend > 0) {
+                onProgress?.((p.totalBytesSent / p.totalBytesExpectedToSend) * 100);
+            }
+        }
+    );
+
+    armTimeout();
+    let res: Awaited<ReturnType<typeof task.uploadAsync>>;
+    try {
+        res = await Promise.race([task.uploadAsync(), timedOut]);
+    } finally {
+        if (timer) clearTimeout(timer);
+    }
+    if (!res || res.status < 200 || res.status >= 300) {
+        const parsed = res ? parseBody(res.body) : {};
+        throw new ApiError(
+            parsed.message || `Upload failed with status ${res?.status ?? 0}`,
+            res?.status ?? 0
+        );
+    }
+
+    const parsed = parseBody(res.body);
+    return { uploadId: parsed.uploadId || "", status: parsed.status || "uploaded" };
+};

package/src/camera/camera-view.tsx

@@ -0,0 +1,217 @@
+/**
+ * CameraView — vision-camera wrapper for still capture (Phase 1).
+ *
+ * Phase 1 is capture-only, so this uses `takePhoto` and does NOT run a frame
+ * processor (that lands in Phase 2 for liveness). Handles permission + device
+ * selection and reports a RawPhoto to the caller.
+ *
+ * vision-camera is required lazily: its NativeCameraModule throws at import time
+ * when the native module is missing (e.g. Expo Go), which would crash any import of
+ * this SDK before KwikIdRNSDK.initialize() can report a friendly runtime error.
+ */
+import { useEffect, useRef, useState } from "react";
+
+import { ActivityIndicator, Linking, Pressable, StyleSheet, Text, View } from "react-native";
+import type { Camera } from "react-native-vision-camera";
+
+import type { RawPhoto } from "./photo-capture";
+
+type VisionCamera = typeof import("react-native-vision-camera");
+
+let visionCamera: VisionCamera | undefined;
+
+function loadVisionCamera(): VisionCamera {
+    visionCamera ??= require("react-native-vision-camera") as VisionCamera;
+    return visionCamera;
+}
+
+export interface CameraViewProps {
+    facing: "front" | "back";
+    /** Only render/activate the camera when this view is on screen. */
+    active: boolean;
+    primaryColor: string;
+    /** Optional overlay (e.g. document frame or face oval) drawn over the preview. */
+    overlay?: React.ReactNode;
+    instruction?: string;
+    /** Shown above the shutter when a capture (or the caller's onCapture) fails. */
+    captureErrorText?: string;
+    /** Permission-denied screen title. */
+    permissionTitle?: string;
+    /** Permission-denied screen body. */
+    permissionBody?: string;
+    /** Label of the button that opens the OS settings. */
+    openSettingsLabel?: string;
+    /** Accessibility label of the shutter button. */
+    captureLabel?: string;
+    /** May return a promise; a rejection is shown as `captureErrorText` and the user can retry. */
+    onCapture: (photo: RawPhoto) => void | Promise<void>;
+    onPermissionDenied?: (canAskAgain: boolean) => void;
+}
+
+export function CameraView({
+    facing,
+    active,
+    primaryColor,
+    overlay,
+    instruction,
+    captureErrorText = "Could not capture the photo. Please try again.",
+    permissionTitle = "Camera access needed",
+    permissionBody = "Enable camera access in Settings to continue verification.",
+    openSettingsLabel = "Open Settings",
+    captureLabel = "Capture photo",
+    onCapture,
+    onPermissionDenied,
+}: CameraViewProps) {
+    const { Camera, useCameraDevice, useCameraPermission } = loadVisionCamera();
+    const camera = useRef<Camera>(null);
+    const device = useCameraDevice(facing);
+    const { hasPermission, requestPermission } = useCameraPermission();
+    const [capturing, setCapturing] = useState(false);
+    const [permissionChecked, setPermissionChecked] = useState(false);
+    const [captureFailed, setCaptureFailed] = useState(false);
+
+    useEffect(() => {
+        let cancelled = false;
+        (async () => {
+            if (!hasPermission) {
+                const granted = await requestPermission();
+                if (!cancelled && !granted) {
+                    onPermissionDenied?.(false);
+                }
+            }
+            if (!cancelled) setPermissionChecked(true);
+        })();
+        return () => {
+            cancelled = true;
+        };
+    }, [hasPermission, requestPermission, onPermissionDenied]);
+
+    const takePhoto = async () => {
+        if (!camera.current || capturing) return;
+        setCapturing(true);
+        setCaptureFailed(false);
+        try {
+            const photo = await camera.current.takePhoto({ flash: "off" });
+            await onCapture({ path: photo.path, width: photo.width, height: photo.height });
+        } catch {
+            setCaptureFailed(true);
+        } finally {
+            setCapturing(false);
+        }
+    };
+
+    if (!hasPermission && permissionChecked) {
+        return (
+            <View style={styles.center}>
+                <Text style={styles.permTitle}>{permissionTitle}</Text>
+                <Text style={styles.permBody}>{permissionBody}</Text>
+                <Pressable
+                    style={[styles.settingsBtn, { borderColor: primaryColor }]}
+                    onPress={() => Linking.openSettings()}
+                >
+                    <Text style={[styles.settingsText, { color: primaryColor }]}>
+                        {openSettingsLabel}
+                    </Text>
+                </Pressable>
+            </View>
+        );
+    }
+
+    if (!device || !permissionChecked) {
+        return (
+            <View style={styles.center}>
+                <ActivityIndicator color={primaryColor} />
+            </View>
+        );
+    }
+
+    return (
+        <View style={styles.fill}>
+            <Camera
+                ref={camera}
+                style={StyleSheet.absoluteFill}
+                device={device}
+                isActive={active}
+                photo
+            />
+            {overlay}
+            <View style={styles.bottomBar}>
+                {captureFailed ? (
+                    <Text
+                        accessibilityRole="alert"
+                        style={[styles.instruction, styles.captureError]}
+                    >
+                        {captureErrorText}
+                    </Text>
+                ) : instruction ? (
+                    <Text style={styles.instruction}>{instruction}</Text>
+                ) : null}
+                <Pressable
+                    accessibilityLabel={captureLabel}
+                    style={styles.shutterOuter}
+                    onPress={takePhoto}
+                    disabled={capturing}
+                >
+                    <View style={[styles.shutterInner, capturing && styles.shutterBusy]}>
+                        {capturing ? <ActivityIndicator color="#fff" /> : null}
+                    </View>
+                </Pressable>
+            </View>
+        </View>
+    );
+}
+
+const styles = StyleSheet.create({
+    fill: { flex: 1, backgroundColor: "#000" },
+    center: {
+        flex: 1,
+        alignItems: "center",
+        justifyContent: "center",
+        padding: 24,
+        backgroundColor: "#000",
+    },
+    bottomBar: {
+        position: "absolute",
+        bottom: 0,
+        left: 0,
+        right: 0,
+        alignItems: "center",
+        paddingBottom: 40,
+    },
+    instruction: {
+        color: "#fff",
+        fontSize: 15,
+        marginBottom: 16,
+        textAlign: "center",
+        paddingHorizontal: 24,
+    },
+    captureError: { color: "#fca5a5", fontWeight: "600" },
+    shutterOuter: {
+        width: 76,
+        height: 76,
+        borderRadius: 38,
+        borderWidth: 4,
+        borderColor: "#fff",
+        alignItems: "center",
+        justifyContent: "center",
+    },
+    shutterInner: {
+        width: 58,
+        height: 58,
+        borderRadius: 29,
+        backgroundColor: "#fff",
+        alignItems: "center",
+        justifyContent: "center",
+    },
+    shutterBusy: { backgroundColor: "#1E3A8A" },
+    permTitle: {
+        color: "#fff",
+        fontSize: 18,
+        fontWeight: "600",
+        marginBottom: 8,
+        textAlign: "center",
+    },
+    permBody: { color: "#ccc", fontSize: 14, textAlign: "center", marginBottom: 20 },
+    settingsBtn: { borderWidth: 1.5, borderRadius: 10, paddingVertical: 12, paddingHorizontal: 24 },
+    settingsText: { fontSize: 15, fontWeight: "600" },
+});

package/src/camera/index.ts

@@ -0,0 +1,4 @@
+export { CameraView } from "./camera-view";
+export type { CameraViewProps } from "./camera-view";
+export { compressCapture } from "./photo-capture";
+export type { RawPhoto } from "./photo-capture";

package/src/camera/photo-capture.ts

@@ -0,0 +1,58 @@
+/**
+ * Normalize + compress a captured photo into a CaptureAsset ready for upload.
+ *
+ * Decoupled from vision-camera: callers pass a plain { path } (the camera hook maps
+ * VisionCamera's PhotoFile to this). Keeps the 10 MB server cap in mind by resizing
+ * the longest edge and compressing to JPEG.
+ */
+import { SaveFormat, manipulateAsync } from "expo-image-manipulator";
+
+import type { CaptureAsset, CaptureType } from "../types";
+
+export interface RawPhoto {
+    /** Absolute file path or file:// URI from the camera. */
+    path: string;
+    width?: number;
+    height?: number;
+}
+
+const MAX_EDGE = 1600;
+
+function toFileUri(path: string): string {
+    return path.startsWith("file://") || path.startsWith("content://") ? path : `file://${path}`;
+}
+
+function fileName(type: CaptureType, ts: number): string {
+    const base = type === "document_front" ? "front" : type === "document_back" ? "back" : "selfie";
+    return `${base}_${ts}.jpg`;
+}
+
+export async function compressCapture(
+    type: CaptureType,
+    photo: RawPhoto,
+    timestamp: number
+): Promise<CaptureAsset> {
+    const uri = toFileUri(photo.path);
+
+    // Resize the longest edge to MAX_EDGE (only downscale) and compress to JPEG.
+    const longest = Math.max(photo.width ?? 0, photo.height ?? 0);
+    const resize =
+        longest > MAX_EDGE
+            ? (photo.width ?? 0) >= (photo.height ?? 0)
+                ? [{ resize: { width: MAX_EDGE } }]
+                : [{ resize: { height: MAX_EDGE } }]
+            : [];
+
+    const result = await manipulateAsync(uri, resize, {
+        compress: 0.8,
+        format: SaveFormat.JPEG,
+    });
+
+    return {
+        uri: result.uri,
+        name: fileName(type, timestamp),
+        type: "image/jpeg",
+        width: result.width,
+        height: result.height,
+    };
+}

package/src/crypto/fingerprint.ts

@@ -0,0 +1,46 @@
+/**
+ * Device fingerprint for RN (replaces the web SDK's canvas/WebGL fingerprint).
+ *
+ * Built from stable device + locale attributes available without extra permissions.
+ * Best-effort: the gateway does not currently require this header.
+ */
+import * as Device from "expo-device";
+import * as Localization from "expo-localization";
+import { Dimensions, Platform } from "react-native";
+
+import type { DeviceFingerprint } from "../types";
+import { sha256Hex } from "./hmac";
+
+export function generateFingerprint(): DeviceFingerprint {
+    const platform = `${Platform.OS} ${String(Platform.Version)}`;
+    const osVersion = Device.osVersion ?? String(Platform.Version);
+    const deviceModel = [Device.brand, Device.modelName].filter(Boolean).join(" ") || "unknown";
+
+    const { width, height, scale } = Dimensions.get("screen");
+    const screenResolution = `${Math.round(width)}x${Math.round(height)}@${scale}`;
+
+    const timezone = Localization.getCalendars()[0]?.timeZone ?? "unknown";
+    const language = Localization.getLocales()[0]?.languageTag ?? "unknown";
+
+    const components = [
+        platform,
+        osVersion,
+        deviceModel,
+        screenResolution,
+        timezone,
+        language,
+        Device.osName ?? "",
+    ];
+
+    const fingerprintHash = sha256Hex(components.join("|"));
+
+    return {
+        platform,
+        osVersion,
+        deviceModel,
+        screenResolution,
+        timezone,
+        language,
+        fingerprintHash,
+    };
+}

package/src/crypto/hmac.ts

@@ -0,0 +1,172 @@
+/**
+ * Pure-JS SHA-256 and HMAC-SHA256.
+ *
+ * Self-contained (no native dependency) so it runs identically on device and in
+ * node tests, and never blocks the verification flow. The web SDK used
+ * `crypto.subtle`; expo-crypto exposes digests but not raw HMAC, so we implement
+ * the standard ipad/opad construction here. Signatures are best-effort — the
+ * KwikId gateway enforces only the Bearer token.
+ */
+
+const K = [
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+    0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+    0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+];
+
+function rotr(x: number, n: number): number {
+    return (x >>> n) | (x << (32 - n));
+}
+
+/** SHA-256 over raw bytes → 32-byte digest. */
+export function sha256Bytes(message: Uint8Array): Uint8Array {
+    const h = [
+        0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab,
+        0x5be0cd19,
+    ];
+
+    // Pre-processing (padding).
+    const bitLen = message.length * 8;
+    const withOne = message.length + 1;
+    const totalLen = withOne + ((56 - (withOne % 64) + 64) % 64) + 8;
+    const padded = new Uint8Array(totalLen);
+    padded.set(message);
+    padded[message.length] = 0x80;
+    // Append 64-bit big-endian length (top 32 bits assumed 0 for our payload sizes).
+    const dv = new DataView(padded.buffer);
+    dv.setUint32(totalLen - 4, bitLen >>> 0, false);
+    dv.setUint32(totalLen - 8, Math.floor(bitLen / 0x100000000), false);
+
+    const w = new Uint32Array(64);
+    for (let offset = 0; offset < totalLen; offset += 64) {
+        for (let i = 0; i < 16; i++) {
+            w[i] = dv.getUint32(offset + i * 4, false);
+        }
+        for (let i = 16; i < 64; i++) {
+            const s0 = rotr(w[i - 15], 7) ^ rotr(w[i - 15], 18) ^ (w[i - 15] >>> 3);
+            const s1 = rotr(w[i - 2], 17) ^ rotr(w[i - 2], 19) ^ (w[i - 2] >>> 10);
+            w[i] = (w[i - 16] + s0 + w[i - 7] + s1) >>> 0;
+        }
+
+        let [a, b, c, d, e, f, g, hh] = h;
+        for (let i = 0; i < 64; i++) {
+            const S1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+            const ch = (e & f) ^ (~e & g);
+            const temp1 = (hh + S1 + ch + K[i] + w[i]) >>> 0;
+            const S0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+            const maj = (a & b) ^ (a & c) ^ (b & c);
+            const temp2 = (S0 + maj) >>> 0;
+            hh = g;
+            g = f;
+            f = e;
+            e = (d + temp1) >>> 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (temp1 + temp2) >>> 0;
+        }
+
+        h[0] = (h[0] + a) >>> 0;
+        h[1] = (h[1] + b) >>> 0;
+        h[2] = (h[2] + c) >>> 0;
+        h[3] = (h[3] + d) >>> 0;
+        h[4] = (h[4] + e) >>> 0;
+        h[5] = (h[5] + f) >>> 0;
+        h[6] = (h[6] + g) >>> 0;
+        h[7] = (h[7] + hh) >>> 0;
+    }
+
+    const out = new Uint8Array(32);
+    const outDv = new DataView(out.buffer);
+    for (let i = 0; i < 8; i++) outDv.setUint32(i * 4, h[i], false);
+    return out;
+}
+
+function utf8Bytes(str: string): Uint8Array {
+    // Minimal UTF-8 encoder (TextEncoder may be absent in some RN engines).
+    const bytes: number[] = [];
+    for (let i = 0; i < str.length; i++) {
+        let code = str.charCodeAt(i);
+        if (code < 0x80) {
+            bytes.push(code);
+        } else if (code < 0x800) {
+            bytes.push(0xc0 | (code >> 6), 0x80 | (code & 0x3f));
+        } else if (code >= 0xd800 && code <= 0xdbff) {
+            // Surrogate pair.
+            const hi = code;
+            const lo = str.charCodeAt(++i);
+            code = 0x10000 + ((hi - 0xd800) << 10) + (lo - 0xdc00);
+            bytes.push(
+                0xf0 | (code >> 18),
+                0x80 | ((code >> 12) & 0x3f),
+                0x80 | ((code >> 6) & 0x3f),
+                0x80 | (code & 0x3f)
+            );
+        } else {
+            bytes.push(0xe0 | (code >> 12), 0x80 | ((code >> 6) & 0x3f), 0x80 | (code & 0x3f));
+        }
+    }
+    return new Uint8Array(bytes);
+}
+
+function toHex(bytes: Uint8Array): string {
+    let hex = "";
+    for (let i = 0; i < bytes.length; i++) {
+        hex += bytes[i].toString(16).padStart(2, "0");
+    }
+    return hex;
+}
+
+/** SHA-256 of a UTF-8 string → lowercase hex. */
+export function sha256Hex(message: string): string {
+    return toHex(sha256Bytes(utf8Bytes(message)));
+}
+
+const BLOCK_SIZE = 64;
+
+/** HMAC-SHA256(message, key) → lowercase hex. */
+export function hmacSha256Hex(message: string, key: string): string {
+    let keyBytes = utf8Bytes(key);
+    if (keyBytes.length > BLOCK_SIZE) {
+        keyBytes = sha256Bytes(keyBytes);
+    }
+
+    const block = new Uint8Array(BLOCK_SIZE);
+    block.set(keyBytes);
+
+    const ipad = new Uint8Array(BLOCK_SIZE);
+    const opad = new Uint8Array(BLOCK_SIZE);
+    for (let i = 0; i < BLOCK_SIZE; i++) {
+        ipad[i] = block[i] ^ 0x36;
+        opad[i] = block[i] ^ 0x5c;
+    }
+
+    const msgBytes = utf8Bytes(message);
+    const inner = new Uint8Array(BLOCK_SIZE + msgBytes.length);
+    inner.set(ipad);
+    inner.set(msgBytes, BLOCK_SIZE);
+    const innerHash = sha256Bytes(inner);
+
+    const outer = new Uint8Array(BLOCK_SIZE + innerHash.length);
+    outer.set(opad);
+    outer.set(innerHash, BLOCK_SIZE);
+
+    return toHex(sha256Bytes(outer));
+}
+
+/** Generate a hex nonce. Deterministic seed optional for tests. */
+export function generateNonce(length = 32, seed?: () => number): string {
+    const rand = seed ?? Math.random;
+    let hex = "";
+    for (let i = 0; i < length; i++) {
+        hex += Math.floor(rand() * 256)
+            .toString(16)
+            .padStart(2, "0");
+    }
+    return hex;
+}

package/src/crypto/index.ts

@@ -0,0 +1,3 @@
+export { SessionManager } from "./session-manager";
+export { generateFingerprint } from "./fingerprint";
+export { hmacSha256Hex, sha256Hex, generateNonce } from "./hmac";