carms-auth-sdk-react-native

React Native SDK for the implemented CARMS v2 mobile auth flow: customer-key enrollment, intent creation, factor submission, and proof approval.

baseUrl must point at the v2 prefix, for example https://example.test/api/v2.

Install

From npm:

npm install carms-auth-sdk-react-native

For local testing before publish, consume it from the repo or a packed tarball:

npm install ../path-to-kyc_sdk/packages/carms-auth-react-native

Usage

import AsyncStorage from "@react-native-async-storage/async-storage";
import { NativeModules, Platform } from "react-native";
import CarmsAuthClient, { createCarmsAuthClient } from "carms-auth-sdk-react-native";

const client = new CarmsAuthClient({
  baseUrl: "https://your-carms-server.example/api/v2",
  acid: "DEMO001234567890",
  bankId: "DEMO00",
  storage: AsyncStorage,
  nativeBridge: NativeModules.CarmsAuthReactNative,
  platform: Platform.OS,
  locationProvider: async () => {
    // The host app owns permission prompts and location-library selection.
    return await getCurrentPositionAfterPermission();
  },
});

await client.enroll();

const deviceInformation = await client.getDeviceInformation();
console.log(deviceInformation.manufacturer, deviceInformation.model);

await client.performFaceEnrollment({
  frameCount: 5,
  quality: 0.75,
  maxWidth: 720,
  captureFrames: async (options) => {
    return await captureFaceFrames(options);
  },
});

await client.performFaceVideoEnrollment({
  captureEnrollmentVideo: async (options) => {
    return await captureFaceEnrollmentVideo(options);
  },
});

const intent = await client.createIntent({
  actionType: "login",
  requiredFactors: ["customer_key", "totp"],
});

await client.performTotpFactor(intent.intentId, {
  maxAttempts: 3,
  getOtp: async () => {
    return await showYourOtpPrompt();
  },
});

if (Platform.OS === "ios") {
  await client.performDeviceBiometricsFactor(intent.intentId, {
    reason: "Confirm this action",
    allowDeviceCredentials: false,
  });
} else {
  await client.performDeviceBiometricsFactor(intent.intentId, {
    reason: "Confirm this action",
    allowDeviceCredentials: false,
    biometricType: "fingerprint",
  });
}

await client.performFaceLivenessFactor(intent.intentId, {
  frameCount: 5,
  quality: 0.75,
  maxWidth: 720,
  captureFrames: async (options) => {
    return await captureFaceFrames(options);
  },
});

const proof = await client.submitProof({
  intentId: intent.intentId,
  nonce: intent.nonce,
  actionType: "login",
});

Remote Auth Listener

For bank-triggered remote approvals, the app can open a foreground websocket listener. The bank creates the remote auth request on its backend, CARMS dispatches it, and the SDK surfaces it to the app.

const listener = await client.connectRemoteAuthListener({
  onRequest: async (request) => {
    console.log(request.intentId, request.medium, request.reference);

    await client.performTotpFactor(request.intentId, {
      getOtp: async () => await showYourOtpPrompt(),
    });

    await client.submitProof({
      intentId: request.intentId,
      nonce: request.nonce,
      actionType: request.actionType,
    });
  },
  onUpdate: async (update) => {
    console.log(update.intentId, update.status);
  },
  onError: (error) => {
    console.error(error);
  },
});

// Later, when the app no longer wants to listen:
await listener.close();

// Or reject a request explicitly:
await client.rejectRemoteAuthRequest("int_123", {
  reason: "customer_rejected",
});

You can also use the factory helper:

const client = createCarmsAuthClient({
  baseUrl: "https://your-carms-server.example/api/v2",
  acid: "DEMO001234567890",
  bankId: "DEMO00",
  storage: AsyncStorage,
  nativeBridge: NativeModules.CarmsAuthReactNative,
  platform: Platform.OS,
});

Notes

• baseUrl is intentionally app-provided. It must include the CARMS v2 prefix, for example https://your-carms-server.example/api/v2.
• enroll() automatically submits a bounded device-information snapshot and an app-installation ID when the bundled native bridge is available. It does not collect IMEI, serial number, MAC address, advertising ID, or the user-assigned device name.
• getDeviceInformation() returns the same sanitized native device context used by enrollment. The app-installation ID is supporting context; the enrolled customer key remains the trusted device credential.
• locationProvider is optional and is called only when submitProof() runs. It should return { latitude, longitude } after app-managed permission checks. Denial or provider failure does not block proof submission.
• Submitted coordinates are client-provided supporting context stored after a successful proof. They are not a verified CARMS factor and are not part of the signed proof envelope.
• realtimeUrl is optional. If omitted, the SDK derives the websocket endpoint from baseUrl.
• createIntent() is included for parity and local or test flows. In production, intent creation should usually happen on your backend.
• submitProof() accepts explicit intentId, nonce, and actionType so apps can complete proofs for backend-created intents and after app restarts.
• connectRemoteAuthListener() is a foreground websocket listener only in this release. Closed-app or push-notification delivery is out of scope.
• rejectRemoteAuthRequest() lets the app explicitly reject a remote request and clear the matching cached intent context.
• performTotpFactor() is the recommended high-level TOTP helper. The app supplies its own OTP UI with getOtp; the SDK validates, retries, and submits the factor.
• performFaceEnrollment() and performFaceLivenessFactor() require an app-provided captureFrames callback in this release. The SDK validates, normalizes, and submits the frame files.
• performFaceVideoEnrollment() requires an app-provided captureEnrollmentVideo callback. Use explicit user-approved MP4 capture, ideally 5 seconds at 640x480 and 15 fps.
• Face video enrollment can return status: "partial" with reviewRequired: true. Use totalStored and enrollmentComplete to decide whether another capture is needed while bank review remains pending.
• performDeviceBiometricsFactor() supports biometric-auth flows only in this release. Pass allowDeviceCredentials: false.
• On Android, performDeviceBiometricsFactor() also requires an explicit biometricType because Android biometric prompts do not expose the enrolled modality reliably.
• isDeviceBiometricsAvailable() may still be called with allowDeviceCredentials, but the high-level helper rejects device-credential fallback until the CARMS factor contract evolves.
• submitFaceEnrollment() remains available for advanced integrations that already capture face enrollment frames.
• submitFaceVideoEnrollment() remains available for advanced integrations that already capture video evidence, frames, and quality metadata.
• submitFaceFactor() remains available for advanced integrations that already capture React Native file parts shaped like { uri, name?, type? }.
• Voice uses CARMS challenges and audio uploads: call createVoiceChallenge(), then submitVoiceEnrollment() or submitVoiceFactor().
• submitDeviceBiometricsFactor() remains available for advanced integrations that already handle device authentication.

Publish

Run the test suite and inspect the package contents before publishing:

npm test
npm run verify:release
npm run pack:npm
npm run smoke:npm-install
npm run publish:npm