@glomopay/react-native-sdk 4.0.0 → 5.0.0

package/src/utils/device-compliance.ts

@@ -1,75 +1,185 @@
 /**
- * Device compliance utilities for the GlomoPay RN SDK
+ * Device compliance for the GlomoPay RN SDK
  *
- * These utilities check device security compliance using jail-monkey (if available).
- * If jail-monkey is not installed, compliance checks are skipped.
+ * Whether a checkout may run on this device, from `jail-monkey`'s root/jailbreak detection.
  *
- * Merchants are STRONGLY encouraged to install peerDependencies for better security compliance.
+ * The gate exists to protect a **compromised customer device**: malware on a real user's rooted
+ * phone reading cached KYC documents. That framing is what decides the two judgement calls below -
+ * which root signals to trust, and when not to gate at all.
  */
 
+import { isMockModeKey } from "./validation";
+
+/** The package name, so a missing dependency can be named in a warning and in telemetry */
+export const COMPLIANCE_PACKAGE = "jail-monkey";
+
+/**
+ * rootBeer checks deliberately excluded from our verdict.
+ *
+ * Both fire on a stock AOSP emulator image - `ro.build.tags=test-keys`, and `ro.debuggable=1` /
+ * `ro.secure=0` - so an Android emulator reports as rooted through `isJailBroken()`, which is a
+ * hardcoded OR over every check and is not configurable. Merchants integration-test with live keys
+ * on emulators; blocking that turns integration into a support ticket, and an emulator is not the
+ * threat this gate exists for - there is no unwitting victim whose documents are being read.
+ *
+ * What this costs is custom-ROM detection on physical devices, the weakest signal in the set. Every
+ * strong indicator is kept: a genuinely rooted handset trips su, Magisk or a root-manager app
+ * essentially always.
+ */
+export const IGNORED_ROOT_SIGNALS = ["detectTestKeys", "checkForDangerousProps"];
+
+/** How the verdict below was reached. Rides telemetry, because the three are not equally strong. */
+export type ComplianceSource =
+    /** Per-check rootBeer breakdown, with IGNORED_ROOT_SIGNALS excluded. Android only. */
+    | "decomposed"
+
+    /** jail-monkey's own `isJailBroken()`. iOS, and Android builds that expose no breakdown. */
+    | "aggregate"
+
+    /** jail-monkey could not be loaded at all. */
+    | "unavailable";
+
+/** What the probe concluded */
+export interface DeviceComplianceResult {
+    /** True if compromised, false if clean, **null if it could not be determined** - never "clean" */
+    compromised: boolean | null;
+
+    source: ComplianceSource;
+
+    /** Names of the checks that tripped. Never the device identifiers behind them. */
+    trippedSignals: string[];
+}
+
 /**
- * Safely checks if jail-monkey is available
- * Returns null if the library is not installed
+ * The subset of jail-monkey this SDK uses.
+ *
+ * Fields are pulled from the real package's declarations rather than restated, so a rename upstream
+ * - `androidRootedDetectionMethods` in particular - is a compile error here instead of a probe that
+ * silently falls back to the aggregate check forever. `typeof import(...)` is erased, so this costs
+ * no runtime import of an optional dependency.
+ */
+type PublishedJailMonkey = typeof import("jail-monkey").default;
+
+interface JailMonkeyModule {
+    isJailBroken: PublishedJailMonkey["isJailBroken"];
+    androidRootedDetectionMethods?: PublishedJailMonkey["androidRootedDetectionMethods"];
+}
+
+/**
+ * Loads jail-monkey, or null.
+ *
+ * Literal `require` directly inside the `try`, resolved once at module init. Both are what Metro
+ * requires of an optional dependency, and the second is the one that is easy to get wrong: a lazy
+ * first `require` runs outside Metro's `inGuard`, where a failed load is reported through
+ * `ErrorUtils.reportFatalError` and raises a full-screen LogBox in dev builds even though the
+ * `catch` here degrades correctly. See the full note in capabilities/file-save.ts.
+ *
+ * Also catches the installed-but-not-rebuilt case: jail-monkey reads
+ * `NativeModules.JailMonkey.rootedDetectionMethods` at module scope, so an unlinked native module
+ * throws on import rather than degrading.
  */
-function getJailMonkey(): { isJailBroken: () => boolean } | null {
+const jailMonkeyModule: JailMonkeyModule | null = (() => {
     try {
-        const JailMonkey = require("jail-monkey");
-        if (JailMonkey && typeof JailMonkey.isJailBroken === "function") {
-            return JailMonkey;
-        }
-        return null;
+        const loaded = require("jail-monkey");
+        const module = (loaded?.default ?? loaded) as JailMonkeyModule | undefined;
+        return module && typeof module.isJailBroken === "function" ? module : null;
     } catch {
-        // jail-monkey is not installed
         return null;
     }
+})();
+
+function loadJailMonkey(): JailMonkeyModule | null {
+    return jailMonkeyModule;
 }
 
 /**
- * Checks if the device is rooted or jailbroken
- * Returns null if jail-monkey is not available (compliance check skipped)
- * Returns true if device is compromised, false if device is safe
+ * Whether this device is compromised.
  *
- * @param devMode - Whether to log debug information
- * @returns true if device is compromised, false if safe, null if check unavailable
+ * Prefers the per-check breakdown over `isJailBroken()`, because the aggregate is a hardcoded OR
+ * that includes the two emulator-tripping checks. Falls back to the aggregate whenever the
+ * breakdown is absent - iOS never reports one, and a future jail-monkey that stops exporting it
+ * degrades to today's behaviour rather than to "clean".
  */
-export function checkDeviceCompliance(devMode: boolean = false): boolean | null {
-    const JailMonkey = getJailMonkey();
+export function resolveDeviceCompliance(devMode: boolean = false): DeviceComplianceResult {
+    const jailMonkey = loadJailMonkey();
 
-    if (!JailMonkey) {
+    if (!jailMonkey) {
         if (devMode) {
             console.log(
-                "[Glomo-RN-SDK] jail-monkey not available. Device compliance check skipped. " +
-                    "Install jail-monkey for enhanced security compliance."
+                `[Glomo-RN-SDK] ${COMPLIANCE_PACKAGE} not available. Device compliance could not be determined.`
             );
         }
-
-        // Check unavailable - allowing checkout to proceed
-        return null;
+        return { compromised: null, source: "unavailable", trippedSignals: [] };
     }
 
     try {
-        const isCompromised = JailMonkey.isJailBroken();
-        if (devMode) {
-            console.log(
-                `[Glomo-RN-SDK] Device compliance check: ${isCompromised ? "FAILED (device compromised)" : "PASSED"}`
+        const breakdown = jailMonkey.androidRootedDetectionMethods;
+        // Read as an open map: the checks are iterated, and a jail-monkey that adds one should have
+        // it counted rather than ignored for being absent from a hardcoded list
+        const rootBeer = breakdown?.rootBeer as Record<string, boolean> | undefined;
+
+        if (rootBeer && typeof rootBeer === "object") {
+            const trippedSignals = Object.keys(rootBeer).filter(
+                (signal) => rootBeer[signal] === true && !IGNORED_ROOT_SIGNALS.includes(signal)
             );
+
+            // jail-monkey's own non-rootBeer signal sits beside the map rather than inside it
+            if (breakdown?.jailMonkey === true) {
+                trippedSignals.push("jailMonkey");
+            }
+
+            if (devMode) {
+                console.log(
+                    `[Glomo-RN-SDK] Device compliance (decomposed): ${
+                        trippedSignals.length > 0 ? `FAILED via ${trippedSignals.join(", ")}` : "PASSED"
+                    }`
+                );
+            }
+            return { compromised: trippedSignals.length > 0, source: "decomposed", trippedSignals };
         }
-        return isCompromised;
+
+        const compromised = jailMonkey.isJailBroken();
+        if (devMode) {
+            console.log(`[Glomo-RN-SDK] Device compliance (aggregate): ${compromised ? "FAILED" : "PASSED"}`);
+        }
+        return {
+            compromised,
+            source: "aggregate",
+            trippedSignals: compromised ? ["isJailBroken"] : [],
+        };
     } catch (error) {
         if (devMode) {
-            const errorMessage = error instanceof Error ? error.message : String(error);
-            console.error("[Glomo-RN-SDK] Error checking device compliance:", errorMessage);
+            const message = error instanceof Error ? error.message : String(error);
+            console.error("[Glomo-RN-SDK] Error checking device compliance:", message);
         }
-        // On error, allowing checkout to proceed (fail open strategy)
-        return null;
+        // Unknown, not clean. The caller decides what to do with that, and on a live key it blocks.
+        return { compromised: null, source: "unavailable", trippedSignals: [] };
+    }
+}
+
+/**
+ * Whether a checkout must be refused on this device.
+ *
+ * **Fails closed on a live key**: unknown blocks, because on RN unknown overwhelmingly means the
+ * merchant did not install `jail-monkey` rather than that a platform probe failed. That is why the
+ * package stopped being an optional peer dependency in v5 - a dependency cannot be optional and
+ * load-bearing at once, and an install-time warning beats a silent runtime outage.
+ *
+ * **Never gates mock or test traffic.** Measured, never blocked - matching the Flutter SDK's
+ * `enforced` model, and so QA on a rooted handset or an emulator image stays possible.
+ */
+export function blocksCheckout(result: DeviceComplianceResult, publicKey?: string): boolean {
+    if (isMockModeKey(publicKey)) {
+        return false;
     }
+    return result.compromised !== false;
 }
 
 /**
- * Checks if compliance checking is possible in the current environment
+ * Whether the device compliance check could run at all
  *
- * @returns true if peerDependencies for compliance checking are installed and available
+ * @returns true if jail-monkey is installed and its native module is linked
  */
 export function isComplianceCheckAvailable(): boolean {
-    return getJailMonkey() !== null;
+    return loadJailMonkey() !== null;
 }

package/src/utils/event-projections.ts

@@ -0,0 +1,74 @@
+/**
+ * Runtime allowlists for what a callback payload may contribute to telemetry
+ *
+ * **Every tracker that reports a payload takes one of these, never the payload itself.**
+ *
+ * The rule exists because TypeScript types are erased. A `Pick<>`, a cast or a projection
+ * *interface* removes nothing from the object at runtime - the value still carries every field, and
+ * `client.post("/track", payload)` serialises all of them. So "pass the payload, constrain it with a
+ * type" compiles cleanly, reviews cleanly, and ships `signature` to Segment on every payment. A
+ * signature is a bearer credential.
+ *
+ * Constructing the outbound object field by field is what actually enforces the allowlist, and
+ * keeping it here rather than at each call site is what keeps the callback and the event assembled
+ * from one source, so a field added to a payload cannot reach an event unless someone adds it here
+ * deliberately.
+ */
+
+import { type GlomoCheckoutPayload, type GlomoTerminationPayload } from "../types/checkout";
+
+/** What a payment payload may say about itself */
+export interface PaymentEventData {
+    orderId: string;
+    paymentId?: string;
+}
+
+/**
+ * Projection of a success or failure payload.
+ *
+ * `signature` is excluded and must stay excluded - it is the field this whole module exists for.
+ */
+export function toPaymentEventData(payload: GlomoCheckoutPayload): PaymentEventData {
+    return { orderId: payload.orderId, paymentId: payload.paymentId };
+}
+
+/** What a termination payload may say about itself */
+export interface TerminationEventData {
+    source: string;
+}
+
+/** Projection of a termination payload. Everything it carries today is safe; that is not a licence. */
+export function toTerminationEventData(payload: GlomoTerminationPayload): TerminationEventData {
+    return { source: payload.source };
+}
+
+/** What an asynchronous journey payload may say about itself */
+export interface JourneyEventData {
+    journeyType: string;
+    journeyStatus?: string;
+
+    /**
+     * Whether the page sent bank details, not what they were.
+     *
+     * `senderAccountNumber` is a customer bank account number and `transactionReference` identifies
+     * a specific transfer; neither belongs in analytics. Presence is what triage actually needs - it
+     * separates "the page reported a transfer without details" from "the SDK dropped them".
+     */
+    hasSenderAccountNumber: boolean;
+    hasTransactionReference: boolean;
+}
+
+/** Projection of an asynchronous journey payload */
+export function toJourneyEventData(payload: {
+    journeyType: string;
+    status?: string;
+    senderAccountNumber?: string;
+    transactionReference?: string;
+}): JourneyEventData {
+    return {
+        journeyType: payload.journeyType,
+        journeyStatus: payload.status,
+        hasSenderAccountNumber: Boolean(payload.senderAccountNumber),
+        hasTransactionReference: Boolean(payload.transactionReference),
+    };
+}

package/src/utils/file-metadata.ts

@@ -0,0 +1,140 @@
+/**
+ * Shapes what a saved or picked file may say about itself in telemetry
+ *
+ * Extension and byte count only - never the file name, which is the user's data
+ * (`passport_A1234567.pdf`) where these two are not.
+ *
+ * Values are sentinels rather than nulls so an event always carries the same shape and a missing
+ * value is something to filter on. Ported from the Flutter SDK's `FileMetadata` so the two report
+ * the same vocabulary on the same events.
+ */
+
+/**
+ * Length could not be read. Negative because `0` is legitimate: a zero-byte file is a real failure
+ * that would otherwise look like an unexplained bank rejection.
+ */
+export const SIZE_UNAVAILABLE = -1;
+
+/** The file had no extension. User behaviour, not an error. */
+export const EXTENSION_NONE = "FILE_WITH_NO_EXTENSION";
+
+/**
+ * The tail was rejected: too long, or not purely alphanumeric. In the field this is ordinary user
+ * naming (`scan.jpeg (1)`), not an SDK fault. Do not alert on it.
+ */
+export const EXTENSION_EXTRACTION_FAILED = "EXTRACTION_FAILED";
+
+/**
+ * A well-formed extension that is not one we know. Reports that something novel was handled without
+ * carrying the value, so a new format is still visible as an event.
+ */
+export const EXTENSION_UNKNOWN = "UNKNOWN_EXTENSION";
+
+/** First of two gates. Rejects a long tail early; KNOWN_EXTENSIONS is what actually bounds this. */
+const MAX_EXTENSION_LENGTH = 5;
+
+/**
+ * Extensions reported verbatim, and the MIME type each one maps to.
+ *
+ * Anything outside this map becomes a sentinel, so no part of a filename can reach telemetry by
+ * being short enough to look plausible. The MIME side exists because Android's save dialog is an
+ * `ACTION_CREATE_DOCUMENT` intent that wants a type: deriving it here rather than forwarding the
+ * `mimeType` the page sends keeps untrusted page input out of an Intent, and is the same call the
+ * Flutter SDK makes when it declines to forward that field to `file_picker`.
+ */
+const KNOWN_EXTENSIONS: Record<string, string> = {
+    pdf: "application/pdf",
+    epdf: "application/pdf",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    png: "image/png",
+    gif: "image/gif",
+    webp: "image/webp",
+    bmp: "image/bmp",
+    tiff: "image/tiff",
+    tif: "image/tiff",
+    heic: "image/heic",
+    heif: "image/heif",
+    jfif: "image/jpeg",
+    pjpeg: "image/jpeg",
+    doc: "application/msword",
+    docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    xls: "application/vnd.ms-excel",
+    xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    csv: "text/csv",
+    txt: "text/plain",
+    rtf: "application/rtf",
+    odt: "application/vnd.oasis.opendocument.text",
+    zip: "application/zip",
+};
+
+/** Hoisted - extensionOf runs on every save. */
+const ALPHANUMERIC = /^[a-z0-9]+$/;
+
+/**
+ * Lowercased extension of a path, or a sentinel.
+ *
+ * Not `split(".").pop()`, which returns the whole filename when there is no dot - shipping exactly
+ * what this exists to keep out.
+ */
+export function extensionOf(path?: string | null): string {
+    if (!path) {
+        return EXTENSION_EXTRACTION_FAILED;
+    }
+
+    // A staging directory can carry dots, so the basename is isolated before looking for one
+    const name = path.split("/").pop() ?? "";
+    if (name.length === 0) {
+        return EXTENSION_EXTRACTION_FAILED;
+    }
+
+    const dot = name.lastIndexOf(".");
+    // `dot === 0` is a dotfile (`.bank_statement`), not an extension
+    if (dot <= 0 || dot === name.length - 1) {
+        return EXTENSION_NONE;
+    }
+
+    /**
+     * Rejected, not stripped. Stripping separators first let a 15-character filename tail collapse
+     * into a plausible 8-character extension (`aadhaar.9876-5432` -> `98765432`), which is filename
+     * content on a KYC upload. A real extension has no separators to remove.
+     */
+    const raw = name.slice(dot + 1).toLowerCase();
+    if (raw.length === 0 || raw.length > MAX_EXTENSION_LENGTH || !ALPHANUMERIC.test(raw)) {
+        return EXTENSION_EXTRACTION_FAILED;
+    }
+
+    return raw in KNOWN_EXTENSIONS ? raw : EXTENSION_UNKNOWN;
+}
+
+/**
+ * The MIME type to declare for a file, from the extension extensionOf resolved.
+ *
+ * Falls back to the generic type for every sentinel: an unrecognised extension is exactly the case
+ * where a guess would be wrong, and Android will still let the user save with a generic type.
+ */
+export function mimeTypeFor(fileExtension: string): string {
+    return KNOWN_EXTENSIONS[fileExtension] ?? "application/octet-stream";
+}
+
+/**
+ * Normalises a raw HTML `accept` attribute for telemetry.
+ *
+ * The injected JS reads the attribute verbatim (`".pdf, .jpeg"`) where a native layer may hand over
+ * an already-parsed list (`".pdf,.jpeg"`), so without this the request event and anything reported
+ * later for the same click will not join on it.
+ *
+ * Never used to decide what may be picked - the bank owns that.
+ */
+export function normalizeAcceptTypes(acceptTypes?: string | null): string | undefined {
+    if (!acceptTypes || acceptTypes.trim().length === 0) {
+        return undefined;
+    }
+    const parts = acceptTypes
+        .toLowerCase()
+        .split(",")
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0)
+        .sort();
+    return parts.length === 0 ? undefined : parts.join(",");
+}

package/src/utils/use-sdk-session.ts

@@ -0,0 +1,41 @@
+/** Binds one checkout attempt's telemetry context for as long as the component is mounted */
+
+import { useEffect, useRef } from "react";
+
+import { bindCheckoutStatus, releaseSdkSession, setSdkSession } from "./analytics";
+
+/** Distinguishes two mounts in the same process without reaching for a uuid dependency */
+let mountCounter = 0;
+
+/**
+ * Mints a session id and binds a checkout-status getter, both for the mounted lifetime.
+ *
+ * Deliberately a hook rather than something `start()` calls, so a merchant who retries produces two
+ * `start_attempted` events inside one session instead of two unrelated sessions.
+ *
+ * The status getter is held in a ref and re-read on every event, so a status that changes mid-session
+ * reaches later events without anything re-binding.
+ */
+export function useSdkSession(readStatus: () => string): void {
+    const readStatusRef = useRef(readStatus);
+    readStatusRef.current = readStatus;
+
+    useEffect(() => {
+        const sessionId = `sess-${Date.now().toString(36)}-${(++mountCounter).toString(36)}-${Math.random()
+            .toString(36)
+            .slice(2, 8)}`;
+
+        setSdkSession(sessionId);
+        bindCheckoutStatus(() => readStatusRef.current());
+
+        return () => {
+            /**
+             * Cleared rather than left dangling, so an event from an unmounted checkout carries
+             * neither - but only if this mount's session is still the active one. A merchant with
+             * two checkouts alive would otherwise have the one unmounting silence the one still
+             * taking a payment.
+             */
+            releaseSdkSession(sessionId);
+        };
+    }, []);
+}

package/src/utils/validation.ts

@@ -19,6 +19,28 @@ export function isValidPublicKey(publicKey: string): boolean {
     );
 }
 
+/**
+ * Prefixes that run the checkout against mocks instead of taking a live payment.
+ *
+ * `isValidPublicKey` has always accepted all three prefixes while every mock-mode check tested only
+ * `test_`, so a `mock_` key passed validation and then had `mode=live` built into its checkout URL -
+ * a mock key taking a real payment. Declared once here so the two cannot drift again.
+ */
+const MOCK_MODE_PREFIXES = ["test_", "mock_"];
+
+/**
+ * Whether this public key should run in mock mode.
+ *
+ * Case-insensitive, matching what the call sites already did.
+ */
+export function isMockModeKey(publicKey?: string): boolean {
+    const normalized = publicKey?.toLowerCase();
+    if (!normalized) {
+        return false;
+    }
+    return MOCK_MODE_PREFIXES.some((prefix) => normalized.startsWith(prefix));
+}
+
 /**
  * Validates that an order ID has the correct format
  * @param orderId - The order ID to validate
@@ -46,27 +68,65 @@ export function isValidUrl(url: string): boolean {
     return url.startsWith("http://") || url.startsWith("https://");
 }
 
+/**
+ * The fields a payment payload may be missing and still be usable
+ *
+ * `paymentId` and `signature` are resolved by the checkout backend, and a page can report a
+ * terminal outcome before that has happened - open banking completes on the bank's side first.
+ * Requiring them meant the SDK dropped a real payment outcome on the floor rather than reporting an
+ * incomplete one, so the merchant learned nothing at all.
+ */
+const OPTIONAL_PAYMENT_FIELDS = ["paymentId", "signature"] as const;
+
 /**
  * Validates the payment payload structure
+ *
+ * `orderId` is the only field the SDK can route on and the only one required. The other two are
+ * reported when present and named in telemetry when absent - see missingPaymentFields.
+ *
+ * Relaxed in v5. Before this, a payload missing either optional field failed here and the whole
+ * outcome was dropped behind a devMode-only log: no callback, no telemetry, no trace in a release
+ * build. `strict: true` in tsconfig is what makes the looser shape safe for merchants - an optional
+ * field cannot reach anything expecting a `string` without a narrowing check, so this lands as a
+ * compile error rather than a runtime surprise.
+ *
+ * An empty `orderId` is accepted, and must stay accepted. Open banking and pay-via-bank post
+ * `payment.success` with empty fields when the payment completes on the bank's side before the
+ * checkout backend has resolved ids - so rejecting `""` here would drop a payment that actually
+ * succeeded, which is the exact failure the widening above exists to remove. v4 carried the same
+ * rule in a comment; a length check briefly reintroduced the bug in v5 before review caught it.
+ * Type is the only thing checked: a non-string `orderId` is malformed, an empty one is early.
+ *
  * @param payload - The payload to validate
- * @returns true if valid, false otherwise
+ * @returns true if the payload carries a usable orderId
  */
 export function isValidPaymentPayload(payload: unknown): payload is {
     orderId: string;
-    paymentId: string;
-    signature: string;
+    paymentId?: string;
+    signature?: string;
 } {
     if (!payload || typeof payload !== "object") {
         return false;
     }
     const p = payload as Record<string, unknown>;
-    /**
-     * Accept payloads where orderId, paymentId, and signature are strings.
-     * Empty strings are allowed because some flows (e.g. open banking / pay via bank)
-     * send payment.success with empty fields when the payment completes on the
-     * bank's side before the checkout backend has resolved ids.
-     */
-    return typeof p.orderId === "string" && typeof p.paymentId === "string" && typeof p.signature === "string";
+
+    if (typeof p.orderId !== "string") {
+        return false;
+    }
+
+    // Present-but-wrong-type is a malformed payload, unlike absent, which is merely incomplete
+    return OPTIONAL_PAYMENT_FIELDS.every((field) => p[field] === undefined || typeof p[field] === "string");
+}
+
+/**
+ * Which optional fields a valid payload did not carry.
+ *
+ * Empty for a complete payload. Treats the empty string as missing: the page sends `""` rather than
+ * omitting the key when the backend has not resolved an id, and the two mean the same thing to
+ * anyone reading the event.
+ */
+export function missingPaymentFields(payload: { paymentId?: string; signature?: string }): string[] {
+    return OPTIONAL_PAYMENT_FIELDS.filter((field) => !payload[field]);
 }
 
 /**

package/src/webview/capability-props.ts

@@ -0,0 +1,86 @@
+/** Shared WebView configuration for every GlomoPay checkout WebView */
+
+import { type WebViewProps } from "react-native-webview";
+
+import { type WebViewPermissionRequest } from "./use-permission-request";
+
+/**
+ * react-native-webview's props plus the Android-only permission handler, which is
+ * missing from its type definitions. Declaring it here removes the @ts-expect-error
+ * each call site used to carry.
+ */
+export type CapabilityWebViewProps = Partial<WebViewProps> & {
+    onPermissionRequest?: (request: WebViewPermissionRequest) => void;
+};
+
+/** The options for buildCapabilityProps */
+export interface CapabilityPropsOptions {
+    devMode?: boolean;
+
+    /** From usePermissionRequest. Omit only for WebViews that render our own content. */
+    onPermissionRequest?: (request: WebViewPermissionRequest) => void;
+}
+
+/**
+ * Configuration shared by every WebView the SDK renders, regardless of flow.
+ *
+ * Only configuration belongs here - things that describe how a WebView behaves. Per-WebView
+ * concerns (source, refs, message handlers, injected scripts, styles) stay at the call site,
+ * and defensive patches against a bank's markup stay in the flow injection script, since the
+ * WebViews that render our own pages have no third-party markup to defend against.
+ */
+export function buildCapabilityProps({
+    devMode = false,
+    onPermissionRequest,
+}: CapabilityPropsOptions): CapabilityWebViewProps {
+    return {
+        webviewDebuggingEnabled: __DEV__ && devMode,
+        javaScriptEnabled: true,
+        domStorageEnabled: true,
+        javaScriptCanOpenWindowsAutomatically: true,
+        setSupportMultipleWindows: true,
+        incognito: true,
+        cacheEnabled: false,
+        cacheMode: "LOAD_NO_CACHE",
+        pullToRefreshEnabled: false,
+        limitsNavigationsToAppBoundDomains: false,
+        menuItems: [],
+        showsHorizontalScrollIndicator: false,
+        showsVerticalScrollIndicator: false,
+        mixedContentMode: "always",
+        thirdPartyCookiesEnabled: true,
+        sharedCookiesEnabled: true,
+        allowsInlineMediaPlayback: true,
+        mediaPlaybackRequiresUserAction: false,
+
+        /**
+         * Camera for bank authentication. iOS raises its own prompt; Android routes through
+         * onPermissionRequest below.
+         */
+        mediaCapturePermissionGrantType: "prompt",
+        onPermissionRequest,
+
+        /**
+         * File access props.
+         *
+         * These only apply to JavaScript running inside a file:// document, and no file://
+         * document can load here - neither factory sets originWhitelist, so
+         * react-native-webview's default of ['http://*', 'https://*'] applies and a file://
+         * navigation is never taken. Every WebView loads remote https under incognito. So
+         * these are inert, and kept for uniformity across flows rather than because anything
+         * needs them.
+         *
+         * Note allowFileAccess is not inert in the same way: rnw defaults it to false on
+         * Android, so we are the ones turning it on. Deliberate, and safe only because of the
+         * originWhitelist default above.
+         *
+         * If originWhitelist is ever set to admit file://, all three become live and this
+         * needs revisiting.
+         */
+        allowFileAccess: true,
+        allowUniversalAccessFromFileURLs: true,
+        allowFileAccessFromFileURLs: true,
+
+        androidLayerType: "hardware",
+    };
+}