@necessarysdk/react-native 0.0.0-stage → 0.1.5

package/README.md

@@ -1,3 +1,430 @@
-# Temporary Holding Version
+# Necessary for React Native
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Device integrity for React Native apps on Android and iOS. The SDK gives your app a key it never
+exports — made in the phone's keystore, in secure hardware where the phone has it and in software where
+it does not — signed measurements of the phone and of the app running on it, and a proof on each request
+your app sends — and, if you turn them on, a second key the person must unlock to approve a request, and
+a PIN your backend checks. **It never scores and never decides: your backend does.**
+
+Android 7.0 (API 24) and later; iOS 15 and later; React Native 0.76 or later with the New Architecture
+(the default since 0.76, the only one since 0.82). It is built and tested with React Native 0.88, which
+the example app runs.
+
+## Documentation
+
+- [The integration guide](https://github.com/merajhasan88/necessary_reactnative/blob/main/doc/integration_guide.md)
+  (`doc/integration_guide.md`) — the protocol: what the SDK sends, and how your backend checks it.
+- [The measurements](https://github.com/merajhasan88/necessary_reactnative/blob/main/doc/measurements.md)
+  (`doc/measurements.md`) — everything the SDK measures on the phone, field by field: what each
+  measurement is, how it is taken, and what a complete answer holds.
+- [The measurement contract](https://github.com/merajhasan88/necessary_reactnative/tree/main/contract/report-1/android-8-ios-5)
+  (`contract/report-1/android-8-ios-5/`) — the report's schema, its rules and sample reports. The
+  folder's name is two versions: `report-1` is the report's format, and `android-8-ios-5` the lowest
+  versions of the measuring code, the collector, that the contract accepts — 8 on Android and 5 on iOS
+  (`collector_version`; this SDK's are 10 and 8). They are not the Android or iOS versions the SDK runs
+  on, which are above.
+- [The example app](https://github.com/merajhasan88/necessary_reactnative/tree/main/example)
+  (`example/`) puts every piece below in a working app, against the
+  [sample backends](https://github.com/merajhasan88/necessary_reactnative/tree/main/backend)
+  (in the repository, not the package). [Try the example app](#try-the-example-app), below, installs it
+  and tests it step by step, measurement by measurement.
+
+## Install
+
+```sh
+npm install @necessarysdk/react-native
+cd ios && pod install
+```
+
+The SDK's native modules link themselves (autolinking); rebuild the app after installing. The SDK
+declares what its own features need. Your app adds only what you choose to use:
+
+- **Location measurements**: on Android `ACCESS_COARSE_LOCATION` (and `ACCESS_FINE_LOCATION` for a
+  precise location) in your manifest; on iOS `NSLocationWhenInUseUsageDescription` in `Info.plist`.
+  The SDK never asks by itself: call `trust.requestLocationPermission()` from your own screen.
+- **Biometric step-up on iOS**: `NSFaceIDUsageDescription` in `Info.plist`.
+
+## Start
+
+```ts
+import { DeviceTrust, PersonalMeasurement } from '@necessarysdk/react-native';
+
+const trust = new DeviceTrust({
+  baseUrl: 'https://api.example.com',
+  // The personal measurements your app allows; your backend asks for what it needs of them.
+  personalMeasurements: [PersonalMeasurement.screenCapture],
+});
+
+await trust.start(); // loads or makes the key, registers it, proves it holds it
+```
+
+`start()` makes the guide's first three calls under `baseUrl`: register the installation, ask for a key
+challenge, answer it. Your backend answers each as the guide says. A new key is a new installation:
+`trust.identity?.createdThisLaunch` tells your app to forget what it kept for the old one.
+
+## Scan
+
+```ts
+const scan = await trust.scan();
+const answer = scan.answer; // your backend's answer, whole
+```
+
+The SDK measures what your backend's challenge asks for — and, of the personal measurements it asks
+for, the ones your app enabled — signs the report with the installation key and sends it. It acts on the
+guide's protocol errors once (a challenge expired, the installation session expired, the backend lost
+the installation, a short wait); any other refusal reaches your app as an `ApiException`.
+
+## Personal measurements
+
+Seven measurements identify a person's phone, network or habits. Each is collected only when your app
+enables it **and** your backend's challenge asks for it (`optional_probes`); otherwise the report says
+`not_enabled`. None is on unless your app turns it on:
+
+```ts
+trust.personalMeasurements = new Set([
+  PersonalMeasurement.screenCapture, // the screen recorded, mirrored or cast
+  PersonalMeasurement.location, // the last location the phone already knows
+]);
+```
+
+Set them in the constructor, or change them whenever the person does — in a privacy setting: the next
+scan follows, and the installation and its step-up key stay as they are.
+
+| `PersonalMeasurement` | What it reports | Platforms |
+|---|---|---|
+| `localAddresses` | the phone's own IP addresses, link-local ones left out | both |
+| `accessibility` | the Accessibility services that are on, and the keyboard in use | Android |
+| `notificationAccess` | the apps allowed to read notifications | Android |
+| `otherAccess` | device-administrator apps, and known remote-control apps installed | Android |
+| `screenCapture` | the screen being recorded, mirrored or cast | both |
+| `location` | the last location the phone already knows — never a fresh fix, never a prompt | both |
+| `mockLocation` | whether that location was faked | both |
+
+The location needs the person's permission as well: declare it (Install, above) and ask from your own
+screen with `await trust.requestLocationPermission()`, which answers `precise`, `approximate` or
+`none`. On iOS the three Android-only measurements answer `unsupported`.
+
+## Prove your own requests
+
+Every request your app sends to your own API can carry a proof that this installation's key signed it,
+so a copied session token is useless on another phone:
+
+```ts
+const body = JSON.stringify({ amount: 25, to: 'payee-7' });
+const proof = await trust.signRequest({
+  method: 'POST',
+  path: '/v1/transfer',
+  bearer: accountSession, // your backend's session for this installation
+  body, // sent exactly as signed
+});
+await fetch('https://api.example.com/v1/transfer', {
+  method: 'POST',
+  headers: {
+    Authorization: `Bearer ${accountSession}`,
+    'Content-Type': 'application/json',
+    ...proof.headers, // X-Access-Proof, X-Access-Signature
+  },
+  body,
+});
+```
+
+Each proof serves its request once. `trust.send(proof)` sends it through the SDK's transport instead.
+
+## A scan for one action
+
+For a request that matters — a payment, a new payee — have the scan name it, under the account session
+that will send it, and send the scan's report with the request:
+
+```ts
+import { describeOperation } from '@necessarysdk/react-native';
+
+const operation = describeOperation('POST', '/v1/transfer', body);
+const scan = await trust.scan({ session: accountSession, operation });
+const proof = await trust.signRequest({
+  method: 'POST',
+  path: '/v1/transfer',
+  bearer: accountSession,
+  body,
+  reportId: scan.reportId, // X-Integrity-Report
+});
+```
+
+## Step-up: the person approves one request
+
+Turn it on, and choose how the key is unlocked:
+
+```ts
+import { DeviceTrust, StepUpOptions } from '@necessarysdk/react-native';
+
+const trust = new DeviceTrust({
+  baseUrl: 'https://api.example.com',
+  stepUp: new StepUpOptions({ factor: 'passcode', mode: 'per_use' }),
+});
+await trust.start(); // registers the step-up key with the installation
+
+if (trust.stepUpUnavailable !== null) {
+  // This phone cannot make the key -- no screen lock, say. Step-up is off here.
+}
+
+const proof = await trust.signRequest({
+  method: 'POST',
+  path: '/v1/transfer',
+  bearer: accountSession,
+  body,
+  stepUp: true,
+  reason: 'Approve the transfer of 25', // what the phone shows the person
+});
+```
+
+| Option | Values |
+|---|---|
+| `factor` | `passcode` (the phone's PIN, pattern or password) or `biometric` (a fingerprint or face enrolled now) |
+| `mode` | `per_use` (unlocked for every signature) or `windowed` with `windowSeconds` (one unlock for a while; Android only) |
+
+Android 9 and 10 cannot ask for the passcode at every signature: there a passcode key is windowed, and
+says so to your backend. iOS makes per-use keys only. An app whose backend sets the policy assigns
+`trust.stepUp` before `start()`.
+
+Removing the screen lock, or enrolling another biometric for a biometric key, makes the key unusable:
+an approval then fails with `NativeKeyException` `STEPUP_KEY_INVALIDATED`. On Android the SDK deletes
+the key only when Android itself says so; when the keystore cannot establish whether the key is usable,
+or cannot be reached at all — a failure it may recover from — the approval fails with
+`STEPUP_KEY_UNAVAILABLE` and the key is kept: try again later. Android 9 does not say that a key the
+screen lock killed is dead, so there such a key answers `STEPUP_KEY_UNAVAILABLE`. The person re-enrols a
+new key with their own re-authentication, which also replaces a key that stays unavailable:
+
+```ts
+await trust.reenrolStepUp({
+  session: accountSession,
+  reauthentication: { password }, // as your backend requires
+});
+```
+
+A new key is made, the person unlocks it to sign its proof, and your backend takes it for that account
+alone; approvals use it from then on. The call goes to `/v1/installations/stepup-key`, or to your API's
+own path: `new StepUpOptions({ reenrolPath: ... })`. Until your backend has taken the new key — the
+person cancelled the prompt, the password was wrong, the answer was lost — approvals fail with
+`STEPUP_REENROL_PENDING`, across restarts too: call `reenrolStepUp` again. The same holds for a key the
+phone made after the installation was registered — the screen lock was off at the first `start()` and
+set later, say — since your backend takes a step-up key only at an installation's first registration:
+`start()` reports `stepUpUnavailable` `STEPUP_REENROL_PENDING`, and re-enrolment registers the key.
+
+## The app PIN: the person's PIN for one request
+
+Turn it on; the two paths default to the guide's and can be your API's own:
+
+```ts
+import { AppPinOptions, DeviceTrust } from '@necessarysdk/react-native';
+
+const trust = new DeviceTrust({
+  baseUrl: 'https://api.example.com',
+  appPin: new AppPinOptions(), // path: '/v1/account/app-pin', proofPath: '/v1/account/app-pin/proof'
+});
+
+// Setting it: with the person's own re-authentication, as your backend requires.
+await trust.setAppPin({ session: accountSession, pin, reauthentication: { password } });
+
+// Using it: your backend checks the PIN for this one request, and the request carries its proof.
+const proof = await trust.signRequest({
+  method: 'POST',
+  path: '/v1/transfer',
+  bearer: accountSession,
+  body,
+  appPin: pin,
+});
+```
+
+The PIN travels once, in a signed body, never in a header, and the SDK never stores it. Protect the
+screen while it is typed:
+
+```ts
+import { SecureScreen } from '@necessarysdk/react-native';
+
+await SecureScreen.protect(true); // Android: no screenshots or recording; iOS: covered while captured
+// ... the PIN is typed ...
+await SecureScreen.protect(false);
+```
+
+Calls nest — each `protect(true)` needs its `protect(false)` — and when the last one ends the window gets
+back what it had: a window your app keeps secure itself stays secure. On iOS the cover is over your app's
+window, not the system keyboard. Opening Control Center to start a recording closes the keyboard, so
+protect whenever the field has focus, as the example does.
+
+Your backend's refusals reach your app as `ApiException` with the guide's codes: `app_pin_not_set`,
+`app_pin_invalid` (it counts), `app_pin_locked` (a new PIN, set with the re-authentication, unlocks it).
+Step-up and the app PIN combine: your backend decides which requests need which.
+
+## What happens when
+
+| When | What the SDK does |
+|---|---|
+| The key is lost — an Android reinstall, a cleared keystore | `start()` makes a new key and a new installation ID; `trust.identity?.createdThisLaunch` is true, so forget what you kept for the old installation. Your backend links the two only provisionally, by the reinstall hint |
+| Android's keystore cannot be reached | its lookups answer "no such key" then too, so the SDK makes a key only where the keystore, answering, holds none: `start()` fails with `NativeKeyException` `KEY_UNAVAILABLE`, sends nothing and keeps the installation as it is — call it again later; if it persists, `reset()` starts a new installation. Signing answers the same, and a step-up key `STEPUP_KEY_UNAVAILABLE` |
+| iOS keeps the key across a reinstall | with its ID, the same installation comes back; without it, the SDK proposes a new ID, your backend answers with the one it holds for the key, and the SDK keeps that one |
+| The app's process restarts | nothing is kept in memory: `start()` again finds the same key and installation, and proves it for a new installation session |
+| The activity, a scene or a window is replaced | screen protection follows: Android sets it on each new window; on iOS the cover is placed again, on the window the person sees in each scene, whenever a window becomes key, visible or hidden or a scene comes to the foreground — and protection asked for before any window exists covers the first one. A step-up prompt the activity's end cancelled answers `STEPUP_CANCELLED`: ask again |
+| Two calls at once | `start()`, `prove()`, `loadIdentity()` and the same `scan()` run once, and the second caller gets the first's result; scans for different operations, or asked after the personal measurements changed, run apart |
+| A step-up prompt is open | on iOS the SDK's other calls — a scan, a request's signature — wait until the person answers it; Android runs them meanwhile |
+| `reset()` or `close()` while calls run | the calls end with `InterruptedCallException` and keep nothing — no session, no installation ID, no report sent, no request proof or app PIN answer handed out; a reset first waits for every write and key change still running, so none outlives it; after a reset, new calls wait for the deletion and never join one made before. A proof handed out before the reset, or a request already sent, is beyond it: reset is local |
+| A key cannot be deleted | `reset()` fails with that `NativeKeyException` (`KEY_DELETE_FAILED`): call it again. If it is the installation key, the installation stays as it was, its ID with it; if it is the step-up key, the installation itself is already gone. None to delete, or no step-up on the phone, is no failure |
+| A native call fails on Android | the `NativeKeyException`'s message says what failed, then everything beneath it — `[cause: …]`, each failure's kind and words down to the keystore's own answer, and from Android 13 the keystore's numeric code wherever Android passes it on — so a key that reads as unavailable or dead says what the keystore answered. A probe's `error` and each `unread` reason carry the same, within the contract's lengths |
+| A call abandoned, or its answer lost | a scan is simply asked for again — a challenge serves once; the SDK never sends a signed request twice: sign it again, and let your backend decide whether the first one reached it |
+| A report over 65,536 bytes | it is never sent: the app lists the contract lets a collector shorten are shortened, and say `truncated`; anything else answers an `ApiException` `report_too_large` |
+| The stored installation ID cannot be read | `start()` fails with `NativeKeyException` `STORAGE_UNREADABLE` and makes nothing new over it: call it again; `reset()` starts a new installation |
+
+## Your own transport
+
+```ts
+const trust = DeviceTrust.over(new MyTransport()); // implements DeviceTrustTransport
+```
+
+A transport sends each message the SDK builds and answers your backend's JSON object, or throws an
+`ApiException` with its `code`, `message` and `details`. To carry the messages over an API of your own
+shape instead, use the pieces directly — `trust.client`, `collectReport`, `signRequest` — and make the
+guide's checks in your backend.
+
+## What the SDK never does
+
+It never scores, decides, or tells your app a score; never stores your account session; never sends the
+PIN in a header; and uses no platform attestation (Play Integrity, SafetyNet, App Attest, DeviceCheck).
+It never exports a private key, but it cannot prove to your backend where a key is kept: the
+registration's `key_security` is the phone's own word, and where the secure hardware declines — the iOS
+Simulator, some configurations — the key is a software key, which a compromised phone can copy. A fully
+compromised phone can falsify what it measures and can use a genuine key to sign what it likes: the
+measurements raise the cost of fraud, and your backend weighs them with its own business logic.
+
+## Try the example app
+
+The example app (`example/`) puts every piece above in a working app, against a sample backend.
+Its own README carries the same steps.
+
+### Install it
+
+The sample backends live in the repository, not in the package, so start from a clone.
+
+1. Clone the repository:
+
+   ```sh
+   git clone https://github.com/merajhasan88/necessary_reactnative.git
+   cd necessary_reactnative
+   ```
+
+2. Start a sample backend on your computer. It answers on `127.0.0.1` only. In Python 3.10 or later:
+
+   ```sh
+   pip install --require-hashes -r backend/python/requirements.txt
+   python3 backend/python/server.py --port 8787 --schema contract/report-1/android-8-ios-5/report.schema.json
+   ```
+
+   The TypeScript and C# samples run the same way; their commands are in
+   [`backend/README.md`](https://github.com/merajhasan88/necessary_reactnative/blob/main/backend/README.md).
+3. Install the example's packages (Node.js 22 or later), from `example/`:
+
+   ```sh
+   cd example
+   npm ci
+   ```
+
+4. Name the backend in `example/src/backends.json`, then run the app:
+   - **On an Android emulator**, a debug build reaches your computer at `10.0.2.2`:
+     `{"Sample": "http://10.0.2.2:8787"}`, then `npx react-native run-android`.
+   - **On an Android phone** connected by USB with USB debugging on, forward the port first:
+     `adb reverse tcp:8787 tcp:8787`, name `{"Sample": "http://127.0.0.1:8787"}`, then
+     `npx react-native run-android`.
+   - **A release build**, on Android or iOS, talks only HTTPS: the SDK refuses an `http://` address in
+     a release build. Put the sample behind an HTTPS proxy on a name the phone can resolve, with a
+     certificate the phone trusts, and name that address:
+     `{"Sample": "https://backend.example.com"}`, then
+     `npx react-native run-android --mode release`.
+   - **On an iPhone**, run `pod install` in `example/ios`, open `example/ios/NecessaryExample.xcworkspace`
+     in Xcode on a Mac, choose your team under Signing & Capabilities, and run with the iPhone
+     connected. An iPhone reaches your computer over your network, so name the address of the HTTPS
+     proxy.
+
+   To offer several backends, name each: `{"Python": "https://…", "TypeScript": "https://…"}`. A debug
+   build measures itself as one — `debuggable` in `app_identity` — so judge the measurements on a release
+   build.
+
+### Test it on a phone, step by step
+
+With several backends, tap one at the top and run the steps once for each. Every result line carries a
+✓ when the backend did what it should, a red ! when it did not.
+
+1. **Installation → Start.** Expect: `Installation …, proved; step-up on.` On a phone without a screen
+   lock, step-up is off: `step-up off here (…)`, and step 7 cannot pass.
+2. **Measurements:** switch on **All of them**, tap **Ask for the location permission** and allow it.
+   Once is enough; the switches reset when the app restarts.
+3. **Scan.** Expect: `The backend answered next: allow, report …` — the sample backends answer
+   `scan_again` when a measurement could not be read, and `review` when its figures contradict each
+   other. Under **Hooks, gadgets and memory changes** every row reads `measured`, none `not asked`. Open
+   any row for the fields the phone sent.
+4. **Account → Sign in.** Expect: `An account session for this installation.`
+5. **Requests → Protected request.** Expect: ✓ `{"done":"/v1/demo/echo"}`.
+6. **Sensitive, without approval.** Expect: ✓ `Refused, as it should be: 403 needs_approval`.
+7. **Sensitive, with step-up**, then unlock with the phone's passcode. Expect: ✓
+   `{"done":"/v1/demo/sensitive"}`.
+8. Type 6 digits in **App PIN**, then **Set the app PIN**. Expect: ✓ `Set, with the account password.`
+9. **Sensitive, with the app PIN.** Expect: ✓ `{"done":"/v1/demo/sensitive"}`.
+10. **Requests a backend must refuse:** tap each of the four. Expect a ✓ on each: `Refused, as it should
+    be: 401 proof_reused` for the request sent twice, `401 proof_not_accepted` for the other three.
+
+If the phone's screen lock is removed and set again, the step-up key dies: step 7 then shows `The phone
+said STEPUP_KEY_INVALIDATED` (on Android 9, `STEPUP_KEY_UNAVAILABLE`). Tap **Re-enrol the step-up key**
+and unlock with the passcode — expect ✓ `{"stepup_key_registered":true}` — and step 7 passes again. The
+new key is that account's alone. If the lock was off at step 1 and set afterwards, **Start again** says
+`step-up off here (STEPUP_REENROL_PENDING)`: the backend took the installation without a step-up key, so
+re-enrol the same way after step 4.
+
+The app PIN belongs to the account, not to the phone. Phones signed in with the same handle share it: a
+PIN set on one unlocks requests on the other, and before any is set, step 9 answers `app_pin_not_set`.
+Sign in with another handle for an account of its own.
+
+### A session copied to another phone
+
+A session token copied off one phone must be useless on another. You need two phones running the
+example against the same backend.
+
+1. **Phone A:** steps 1 and 4 above, then **Requests a backend must refuse → Share this phone's
+   session**, and send the text to yourself.
+2. Get the text to phone B, for example in a note or a message to yourself. It holds phone A's session
+   and installation ID; the sample's sessions last ten minutes.
+3. **Phone B:** step 1 above, on the same backend.
+4. **Phone B:** paste the text into **A session from another phone**, then tap **Use it here**. Expect: ✓
+   `Refused, as it should be: 401 invalid_installation_signature`. Phone B's key cannot sign for phone A's
+   installation, even when the request names it.
+
+If step 4 reads `The session is no longer valid: sign in again`, phone A's session has expired: sign in
+again on phone A and share it again.
+
+### Measurement by measurement
+
+What each measurement is and every field it carries:
+[`doc/measurements.md`](https://github.com/merajhasan88/necessary_reactnative/blob/main/doc/measurements.md).
+On a phone of your own you can watch these change, one at a time: make the change, tap **Scan**, open the
+measurement's row, and change it back afterwards.
+
+| Measurement | Change | The row then shows |
+|---|---|---|
+| `developer_settings` (Android) | Settings → About phone → tap Build number seven times; then Developer options → USB debugging | `developer_options_enabled`, then `adb_enabled`, true |
+| `network` | turn on a VPN app; or set a manual proxy on your Wi-Fi network | `vpn_active` true, the tunnel's interface in `interfaces` (Android) or `scoped_interfaces` (iOS); `http_proxy_configured` true |
+| `local_addresses` | switch between Wi-Fi and mobile data | the phone's own addresses, per interface |
+| `screen_capture` | start the screen recorder (Android 15 and later; on iOS from Control Center); connect an external display | `recording` true; `external_displays` 1 |
+| `location` | tap **Ask for the location permission** and allow it | the `permission`, the coordinates and their `age_seconds` |
+| `mock_location` | Android: Developer options → Select mock location app, and run a mock-location app; iOS: simulate a location from Xcode while the app runs from it | `mock` true |
+| `accessibility` (Android) | Settings → Accessibility → turn on a service such as Select to Speak; or choose another keyboard | the service in `services`; the keyboard in `keyboard` |
+| `notification_access` (Android) | Settings → Notification access (under Special app access) → allow an app | the app in `listeners` |
+| `other_access` (Android) | install AnyDesk, TeamViewer QuickSupport, RustDesk or AirDroid; or make an app a device administrator | the app in `remote_access_apps`; in `device_admins` |
+| `app_identity` | install a build of the example made with other code | other hashes; a debug build reads `debuggable` true |
+| `debug_state` (Android) | in Android Studio, Run → Attach Debugger to Android Process, on a debug build | `debugger_connected` true |
+| `code_signing` (iOS) | run a development build from Xcode | `get_task_allow` true |
+
+The rest — root and jailbreak traces, Frida and other hooking tools, code changed in memory, an emulator
+or the Simulator — needs a device you are allowed to change: never a phone you depend on. On an Android
+emulator `emulator.suspected` is true, and a `userdebug` image shows a debuggable, test-keys build in
+`system_properties` and `root_files`; on the iOS Simulator `simulator.is_simulator` is true. Frida on a
+test device shows in `runtime_maps`, `frida_ports`, `instrumentation_threads`, `exec_mappings` and
+`code_integrity` on Android, and in `dyld_images` and `code_integrity` on iOS.
+
+## Licence
+
+Copyright 2026 Meraj Hasan. Licensed under the Apache License, Version 2.0 (`LICENSE`, `NOTICE`).

package/android/build.gradle

@@ -0,0 +1,83 @@
+// The SDK's native side on Android, built inside the app that links it: the app's root project
+// provides the Android and React Native Gradle plugins, and the plugin of the native modules'
+// language, and the versions below where it sets none.
+
+def extOrDefault(String name, Object fallback) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : fallback
+}
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+apply plugin: "com.facebook.react"
+
+android {
+  namespace "com.necessarysdk.reactnative"
+  compileSdkVersion extOrDefault("compileSdkVersion", 36)
+  if (rootProject.ext.has("ndkVersion")) {
+    ndkVersion rootProject.ext.get("ndkVersion")
+  }
+
+  defaultConfig {
+    minSdkVersion Math.max(24, extOrDefault("minSdkVersion", 24) as int)
+    targetSdkVersion extOrDefault("targetSdkVersion", 36)
+    externalNativeBuild {
+      cmake {
+        cppFlags "-std=c++17"
+      }
+    }
+  }
+
+  externalNativeBuild {
+    cmake {
+      path "src/main/cpp/CMakeLists.txt"
+    }
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  testOptions {
+    unitTests {
+      includeAndroidResources = true
+      all {
+        outputs.upToDateWhen { false }
+        testLogging {
+          events "passed", "skipped", "failed", "standardOut", "standardError"
+          showStandardStreams = true
+        }
+      }
+    }
+  }
+}
+
+kotlin {
+  compilerOptions {
+    jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17
+  }
+}
+
+repositories {
+  google()
+  mavenCentral()
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  // The collectors' failure handling, the step-up key's verdicts and the key lookups, tested on
+  // the JVM.
+  testImplementation "junit:junit:4.13.2"
+}
+
+react {
+  jsRootDir = file("../src/")
+  libraryName = "NecessarySpec"
+  codegenJavaPackageName = "com.necessarysdk.reactnative"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,41 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <!-- What the SDK's own features need; all normal permissions, granted at
+         install. The location permissions are the app's to declare and ask for:
+         the SDK measures the location only where the app has them. -->
+    <uses-permission android:name="android.permission.INTERNET" />
+    <!-- The network probe asks the connectivity service whether a VPN or a proxy
+         is in use. -->
+    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+    <!-- Step-up prompts (BiometricPrompt, device credential or biometric). -->
+    <uses-permission android:name="android.permission.USE_BIOMETRIC" />
+    <!-- screen_capture on Android 15 and later: whether this app's window is being
+         recorded. -->
+    <uses-permission android:name="android.permission.DETECT_SCREEN_RECORDING" />
+    <!-- Screen protection: other apps' windows are not drawn over the protected
+         window (Android 12 and later). -->
+    <uses-permission android:name="android.permission.HIDE_OVERLAY_WINDOWS" />
+    <queries>
+        <!-- The apps that can hold Accessibility, a keyboard, notification access
+             or device administration, so the accessibility, notification_access
+             and other_access measurements can read who installed each. -->
+        <intent>
+            <action android:name="android.accessibilityservice.AccessibilityService"/>
+        </intent>
+        <intent>
+            <action android:name="android.view.InputMethod"/>
+        </intent>
+        <intent>
+            <action android:name="android.service.notification.NotificationListenerService"/>
+        </intent>
+        <intent>
+            <action android:name="android.app.action.DEVICE_ADMIN_ENABLED"/>
+        </intent>
+        <!-- Remote-control apps scammers have victims install; the same list as
+             IntegrityProbeManager.remoteAccessPackages. -->
+        <package android:name="com.anydesk.anydeskandroid"/>
+        <package android:name="com.teamviewer.quicksupport.market"/>
+        <!-- RustDesk, by its own package name. -->
+        <package android:name="com.carriez.flutter_hbb"/>
+        <package android:name="com.sand.airdroid"/>
+    </queries>
+</manifest>

package/android/src/main/cpp/CMakeLists.txt

@@ -0,0 +1,7 @@
+cmake_minimum_required(VERSION 3.22.1)
+project(codeintegrity)
+
+add_library(codeintegrity SHARED code_integrity.cpp)
+
+find_library(log-lib log)
+target_link_libraries(codeintegrity ${log-lib})