nativekeel 0.1.8 → 0.1.10

package/README.md

@@ -6,7 +6,7 @@ Health check for React Native and Expo apps. One command, no install, no account
 npx nativekeel
 ```
 
-**What's new in 0.1.8:** known vulnerabilities in the exact dependency versions you ship, passwords that leak into crash reports, databases or AsyncStorage, unsafe WebViews, and setups that build fine but crash at runtime. Tuned on 280+ open-source React Native and Expo apps to keep false alarms out. [All releases →](https://nativekeel.com/changelog)
+**What's new in 0.1.10:** every report opens with *Start here*, the three most urgent first steps; missing iOS permission texts (a crash and an App Review rejection) are caught. Recent releases added known vulnerabilities in the exact versions you ship, password leaks into logs and databases, unsafe WebViews, open Android components, plain-HTTP API calls and runtime crash risks. Tuned on 280+ open-source React Native and Expo apps to keep false alarms out. [All releases →](https://nativekeel.com/changelog)
 
 It answers the questions that decide whether your app can still ship:
 
@@ -18,8 +18,8 @@ It answers the questions that decide whether your app can still ship:
 - **Are secrets shipped inside your app?** AWS, Stripe, OpenAI, Anthropic, GitHub, Slack, SendGrid, Twilio, Shopify, Google OAuth keys, private keys and Supabase `service_role` keys (anon keys are fine), plus `.env` values that `react-native-config` or `EXPO_PUBLIC_` compile into the bundle. Server-side folders are reported separately.
 - **Is transport security off?** Cleartext HTTP or `debuggable` in the release Android manifest, `NSAllowsArbitraryLoads` on iOS.
 - **Do you ship known vulnerabilities?** Advisories from the GitHub Advisory Database for the exact versions in your lockfile or `node_modules`. Advisories that only affect Node.js servers are kept, at low severity.
-- **Can someone read your users' data?** Passwords that flow into crash reports, analytics, remote databases or plain AsyncStorage (followed through intermediate variables), WebViews that let page scripts read local files or load HTTP into HTTPS, Android backups that copy tokens.
-- **Will it crash at runtime?** Reanimated without its Babel plugin or `react-native-worklets`, mixed `@react-native-firebase/*` or `@react-navigation/*` majors, a second copy of React or React Native inside a dependency, Kotlin modules that cannot load through the New Architecture interop layer, AppDelegate setups that crash in Release.
+- **Can someone read your users' data?** Passwords that flow into crash reports, analytics, remote databases or plain AsyncStorage (followed through intermediate variables), WebViews that let page scripts read local files or load HTTP into HTTPS, Android backups that copy tokens, Android components any app can start, API calls over plain HTTP.
+- **Will it crash at runtime?** Reanimated without its Babel plugin or `react-native-worklets`, mixed `@react-native-firebase/*` or `@react-navigation/*` majors, a second copy of React or React Native inside a dependency, Kotlin modules that cannot load through the New Architecture interop layer, AppDelegate setups that crash in Release, camera/photos/location access without the Info.plist description iOS requires.
 - **Leftovers from old templates?** Flipper, JavaScriptCore instead of Hermes.
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nativekeel",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Health check for React Native and Expo apps: upgrade blockers, store deadlines, crash risks, vulnerable dependencies and leaked secrets, with a step-by-step upgrade plan.",
   "type": "module",
   "bin": {

package/src/analyze.js

@@ -1,11 +1,11 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { cleanVersion, findPackageDir, installedVersion } from './project.js';
+import { cleanVersion, findPackageDir, installedVersion, versionFromSpec } from './project.js';
 import { createRegistry, fetchJson } from './registry.js';
 import { scanSecrets } from './secrets.js';
 import { nativeChecks } from './native.js';
 import { stabilityChecks } from './stability.js';
-import { vulnerableDependencies, passwordLeaks, webViewRisks, androidBackup } from './security.js';
+import { vulnerableDependencies, passwordLeaks, webViewRisks, androidBackup, exportedComponents, plainHttpCalls } from './security.js';
 import { lockedVersions } from './lockfile.js';
 import { findUnused, filesImportingWith } from './usage.js';
 import { matchKnownIssues, compareVersions } from './known-issues.js';
@@ -226,7 +226,7 @@ export async function analyze(project, { get, now = new Date(), offline: forcedO
   const daysSince = (date) => (date ? Math.floor((now - new Date(`${date}T00:00:00Z`)) / 86400000) : null);
 
   const nativeOf = Object.fromEntries(names.map((n) => [n, isNativeModule(project.root, n, directory[n])]));
-  const versionOf = (n) => cleanVersion(installedVersion(project.root, n) || declaredRange(n));
+  const versionOf = (n) => cleanVersion(installedVersion(project.root, n) || versionFromSpec(n, declaredRange(n)) || '');
   const archSuspects = names.filter((n) => nativeOf[n] && directory[n] && directory[n].newArchitecture === false);
   const codegen = forcedOffline ? {} : await registry.codegenSupport(archSuspects.map((n) => ({ name: n, version: versionOf(n) })));
 
@@ -405,7 +405,7 @@ export async function analyze(project, { get, now = new Date(), offline: forcedO
   for (const f of stabilityChecks(project)) add(f);
 
   // Security beyond leaked keys.
-  for (const f of [...passwordLeaks(project.root), ...webViewRisks(project.root), ...androidBackup(project.root)]) add(f);
+  for (const f of [...passwordLeaks(project.root), ...webViewRisks(project.root), ...androidBackup(project.root), ...exportedComponents(project.root), ...plainHttpCalls(project.root)]) add(f);
   if (!forcedOffline) {
     // Exact versions only (installed, else the lockfile): a range would be a guess.
     const locked = lockedVersions(project.root, project.deps);

package/src/plan.js

@@ -177,7 +177,7 @@ export function buildPlan(result) {
   // In Expo projects `npx expo install` picks the version that matches the SDK.
   const pm = isExpo ? { ...basePm, add: 'npx expo install' } : basePm;
   const pinned = isExpo ? expoPinnedNames(result.project.root) : new Set();
-  const movesWithExpo = (name) => isExpo && (/^(expo-|@expo\/)/.test(name) || name === 'expo' || name === 'jest-expo' || pinned.has(name));
+  const movesWithExpo = (name) => isExpo && (/^(expo-|@expo\/)/.test(name) || ['expo', 'jest-expo', 'react-native', 'react', 'react-dom'].includes(name) || pinned.has(name));
   const installed = new Set(result.deps.map((d) => d.name));
   const byKind = (kind) => result.findings.filter((f) => f.fix && f.fix.kind === kind).map((f) => f.fix);
   const phases = [];
@@ -481,8 +481,18 @@ export function buildPlan(result) {
   const expo = byKind('upgrade-expo')[0];
   if (expo) {
     const steps = [];
+    if (expo.to - expo.from >= 6) {
+      steps.push(`**${expo.to - expo.from} SDKs is a long way.** Weigh it against starting a fresh project on SDK ${expo.to} (\`npx create-expo-app\`) and moving your screens, assets and app config over: with few custom native modules that is often faster than ${expo.to - expo.from} upgrades.`);
+    }
     for (let v = expo.from + 1; v <= expo.to; v++) {
-      steps.push(`SDK ${v - 1} → ${v}: \`npx expo install expo@^${v}.0.0 --fix\`, read the SDK ${v} changelog, run \`npx expo-doctor\`, build.`);
+      // The local Expo CLI (`npx expo`) exists from SDK 46; older SDKs upgrade with expo-cli.
+      steps.push(
+        v < 46
+          ? `SDK ${v - 1} → ${v}: \`npx expo-cli upgrade ${v}\` (the legacy CLI; the local \`npx expo\` CLI arrives with SDK 46), read the SDK ${v} changelog, build.`
+          : v === 46
+            ? `SDK 45 → 46: \`${basePm.add} expo@^46.0.0\`, then \`npx expo install --fix\` (the first SDK with the local CLI), read the SDK 46 changelog, build.`
+            : `SDK ${v - 1} → ${v}: \`npx expo install expo@^${v}.0.0 --fix\`, read the SDK ${v} changelog, run \`npx expo-doctor\`, build.`,
+      );
       // SDK 52 ships React Native 0.76, the first version where switching is practical.
       if (deferredArch && v >= 52) {
         steps.push(`**At SDK ${v}, turn on the New Architecture** before going further (it is the default from SDK 53, and React Native 0.${NEW_ARCH_ONLY_MINOR} removed the legacy one):`, ...deferredArch.map((x) => `New Architecture: ${x}`));
@@ -532,6 +542,11 @@ export function buildPlan(result) {
     });
   }
 
+  // Store deadlines sit together, right after the target SDK.
+  const storeAt = phases.findIndex((p) => p.title === 'Meet App Store and Google Play requirements');
+  const targetAt = phases.findIndex((p) => p.title === 'Meet the Google Play target SDK');
+  if (storeAt > targetAt + 1 && targetAt >= 0) phases.splice(targetAt + 1, 0, ...phases.splice(storeAt, 1));
+
   // Only worth it when the plan changes code: secrets alone do not need UI tests.
   const leaksFirst = phases[0] && phases[0].title === 'Stop the leaks' ? 1 : 0;
   if (phases.length > leaksFirst) {
@@ -572,3 +587,18 @@ export function planToMarkdown(result, plan) {
   lines.push('---', `No time to do it yourself? We do fixed-price upgrades on a branch of your repo: ${SITE_URL}/#services`);
   return `${lines.join('\n')}\n`;
 }
+
+// The first concrete step of the first few phases: what to do today. Shown at the top of the
+// HTML report and under the summary in the terminal.
+const URGENCY = ['Stop the leaks', 'Fix crash risks', 'Meet the Google Play target SDK', 'Meet App Store and Google Play requirements', 'Close security gaps', 'Avoid known traps'];
+
+export function startHere(result, count = 3) {
+  const skip = new Set(['Set up a safety net', 'Verify before you ship']);
+  const rank = (t) => (URGENCY.indexOf(t) >= 0 ? URGENCY.indexOf(t) : URGENCY.length);
+  return buildPlan(result)
+    .phases.filter((p) => !skip.has(p.title) && p.steps.length)
+    .map((p, i) => ({ p, i }))
+    .sort((a, b) => rank(a.p.title) - rank(b.p.title) || a.i - b.i)
+    .slice(0, count)
+    .map(({ p }) => ({ phase: p.title, step: p.steps[0].replace(/ The [^.]* phase below gets you there;.*$/, '') }));
+}

package/src/project.js

@@ -99,6 +99,23 @@ function resolveCatalogRefs(deps, catalogs) {
   return out;
 }
 
+// Expo SDKs up to 44 installed React Native from Expo's fork, declared as a tarball URL such as
+// https://github.com/expo/react-native/archive/sdk-37.0.1.tar.gz. The number there is the SDK,
+// not React Native. React Native version per SDK, from Expo's SDK history.
+const EXPO_FORK_RN = { 31: '0.57.1', 32: '0.57.1', 33: '0.59.8', 34: '0.59.8', 35: '0.59.8', 36: '0.61.4', 37: '0.61.4', 38: '0.62.2', 39: '0.63.2', 40: '0.63.2', 41: '0.63.2', 42: '0.63.2', 43: '0.64.3', 44: '0.64.3' };
+
+// A version number from a dependency spec, or null when the spec is a URL or git reference
+// whose numbers are not the package version.
+export function versionFromSpec(name, spec) {
+  if (!spec) return null;
+  const s = String(spec);
+  if (/:\/\/|^(github|git|file|link|workspace):|#|\.tgz$|\.tar\.gz$/.test(s)) {
+    const sdk = name === 'react-native' && s.match(/expo\/react-native\/archive\/sdk-(\d+)/);
+    return sdk && EXPO_FORK_RN[Number(sdk[1])] ? EXPO_FORK_RN[Number(sdk[1])] : null;
+  }
+  return s;
+}
+
 export function loadProject(root) {
   const pkg = readJson(path.join(root, 'package.json'));
   if (!pkg) throw new Error(`No package.json found in ${root}`);
@@ -128,7 +145,7 @@ export function loadProject(root) {
     isLibrary,
     deps,
     devDeps,
-    rnVersion: cleanVersion(installedVersion(root, 'react-native') || declared('react-native') || ''),
+    rnVersion: cleanVersion(installedVersion(root, 'react-native') || versionFromSpec('react-native', declared('react-native')) || ''),
     expoVersion: declared('expo') ? cleanVersion(installedVersion(root, 'expo') || declared('expo')) : null,
     // Expo "managed" apps generate android/ and ios/ at build time (Continuous Native Generation).
     managed: !!declared('expo') && !hasAndroid && !hasIos,

package/src/report-html.js

@@ -1,5 +1,6 @@
 import { SEVERITIES, countBySeverity } from './analyze.js';
 import { SITE_URL } from './config.js';
+import { startHere } from './plan.js';
 
 const esc = (s) => String(s ?? '').replace(/[&<>"']/g, (ch) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[ch]);
 // Turns `code` spans from finding text into <code>.
@@ -58,6 +59,7 @@ h1{font-size:26px;margin:0 0 4px}h2{font-size:19px;margin:32px 0 12px}h2 small{f
 .stat.critical b{color:var(--critical)}.stat.high b{color:var(--high)}
 .facts{background:var(--card);border:1px solid var(--line);border-radius:10px;padding:12px 16px;margin-top:12px;display:flex;flex-wrap:wrap;gap:6px 24px;font-size:14px}
 ul.list{list-style:none;padding:0;margin:0;display:grid;gap:8px}
+.start{background:var(--card);border:1px solid var(--line);border-left:4px solid var(--accent);border-radius:8px;padding:6px 18px 10px;margin-top:20px}.start h2{margin:10px 0 6px}.start li{margin:6px 0}
 details.bumps{margin-top:8px;background:var(--card);border:1px solid var(--line);border-left:4px solid var(--low);border-radius:8px;padding:10px 14px}details.bumps summary{cursor:pointer;font-weight:600}details.bumps table{width:100%;border-collapse:collapse;margin-top:10px;font-size:14px}details.bumps th,details.bumps td{text-align:left;padding:4px 8px;border-top:1px solid var(--line)}.muted{color:var(--muted);font-weight:400}
 .f{display:flex;gap:12px;background:var(--card);border:1px solid var(--line);border-left:4px solid var(--low);border-radius:8px;padding:10px 14px}
 .f p{margin:2px 0 0;color:var(--muted);font-size:14px}.f strong{overflow-wrap:anywhere}
@@ -88,6 +90,7 @@ ${p.expo ? `<span>Expo SDK <b>${esc(p.expo.split('.')[0])}</b></span>` : ''}
 ${p.android && p.android.targetSdk ? `<span>targetSdk <b>${p.android.targetSdk}</b></span>` : ''}
 <span>${result.deps.length} dependencies (${result.deps.filter((d) => d.native).length} native)</span>
 </div>
+${n.critical + n.high > 0 ? `<section class="start"><h2>Start here</h2><ol>${startHere(result).map((x) => `<li>${rich(x.step)} <span class="muted">(${esc(x.phase)})</span></li>`).join('')}</ol><p class="muted">The full, ordered plan: <code>npx nativekeel plan</code>.</p></section>` : ''}
 <h2>Findings</h2>
 ${result.findings.length ? `${rows ? `<ul class="list">${rows}</ul>` : ''}${bumpTable}` : '<p>No issues found.</p>'}
 ${planHtml}

package/src/report-text.js

@@ -1,5 +1,6 @@
 import { SEVERITIES, countBySeverity } from './analyze.js';
 import { SITE_URL } from './config.js';
+import { startHere } from './plan.js';
 
 export function textReport(result, { color = true, verbose = false } = {}) {
   const paint = (code) => (s) => (color ? `\x1b[${code}m${s}\x1b[0m` : s);
@@ -64,7 +65,12 @@ export function textReport(result, { color = true, verbose = false } = {}) {
 
   if (n.critical + n.high > 0) {
     out.push('');
-    out.push(`Next: ${c.bold('npx nativekeel plan')} writes a step-by-step upgrade plan.`);
+    out.push(c.bold('Start here'));
+    const plain = (t) => t.replace(/\*\*/g, '').replace(/`/g, '');
+    const cut = (t) => (t.length > 150 ? `${t.slice(0, 147).replace(/\s+\S*$/, '')}…` : t);
+    startHere(result).forEach((s, i) => out.push(`  ${i + 1}. ${cut(plain(s.step))}`));
+    out.push('');
+    out.push(`Next: ${c.bold('npx nativekeel plan')} writes the full step-by-step plan.`);
     out.push(c.gray(`No time to do it yourself? Fixed-price upgrades: ${SITE_URL}/#services`));
   } else if (!result.findings.length) {
     out.push(c.green('Nothing to fix. This app is in good shape.'));

package/src/security.js

@@ -19,7 +19,7 @@ function* jsFiles(dir) {
   for (const e of entries) {
     if (e.isDirectory()) {
       if (!SKIP_DIRS.has(e.name) && !e.name.startsWith('.')) yield* jsFiles(path.join(dir, e.name));
-    } else if (JS_EXT.test(e.name) && !/\.(test|spec)\./.test(e.name)) {
+    } else if (JS_EXT.test(e.name) && !/\.(test|spec)[._]/.test(e.name)) {
       yield path.join(dir, e.name);
     }
   }
@@ -257,3 +257,79 @@ export function androidBackup(root) {
     },
   ];
 }
+
+const SYSTEM_ACTIONS = new Set([
+  'android.appwidget.action.APPWIDGET_UPDATE',
+  'android.intent.action.BOOT_COMPLETED',
+  'android.intent.action.LOCKED_BOOT_COMPLETED',
+  'android.intent.action.QUICKBOOT_POWERON',
+  'com.htc.intent.action.QUICKBOOT_POWERON',
+  'android.intent.action.MY_PACKAGE_REPLACED',
+  'android.intent.action.PACKAGE_REPLACED',
+  'android.intent.action.DOWNLOAD_COMPLETE',
+  'android.intent.action.REBOOT',
+]);
+
+// Services, receivers and providers in the app's own manifest that other apps can start or
+// query: exported without a permission. (Launcher activities are meant to be exported.)
+export function exportedComponents(root) {
+  const file = path.join(root, 'android', 'app', 'src', 'main', 'AndroidManifest.xml');
+  const text = read(file);
+  if (!text) return [];
+  const open = [];
+  for (const m of text.matchAll(/<(service|receiver|provider)\b([^>]*?)(?:\/>|>([\s\S]*?)<\/\1>)/g)) {
+    const attrs = m[2];
+    if (!/android:exported\s*=\s*"true"/.test(attrs) || /android:(?:permission|readPermission|writePermission)\s*=/.test(attrs)) continue;
+    // Widgets and receivers for system broadcasts (boot, package replaced, download complete)
+    // have to be exported for Android to reach them.
+    const actions = [...(m[3] || '').matchAll(/<action\s+android:name\s*=\s*"([^"]+)"/g)].map((a) => a[1]);
+    const isWidget = /android\.appwidget\.provider/.test(m[3] || '');
+    if (isWidget || (actions.length && actions.every((a) => SYSTEM_ACTIONS.has(a) || (m[1] === 'receiver' && /^android\.(?:intent\.action|appwidget\.action)\./.test(a))))) continue;
+    const name = (attrs.match(/android:name\s*=\s*"([^"]+)"/) || [])[1] || m[1];
+    open.push(`${m[1]} ${name}`);
+  }
+  if (!open.length) return [];
+  return [
+    {
+      id: 'android-exported-components',
+      severity: 'medium',
+      area: 'security',
+      title: `${open.length} Android component${open.length === 1 ? '' : 's'} open to every other app`,
+      detail: `${open.slice(0, 4).join(', ')}${open.length > 4 ? ', …' : ''}: exported="true" without a permission, so any installed app can start it or read from it. Set exported="false" unless another app must call it, or protect it with android:permission.`,
+      fix: { kind: 'security', step: 'In `android/app/src/main/AndroidManifest.xml`, set `android:exported="false"` on services/receivers/providers no other app needs, or add `android:permission`.' },
+    },
+  ];
+}
+
+// API calls over plain HTTP/WS to a real host. Android (API 28+) and iOS block these unless
+// security is turned off, so they either fail in production or travel unencrypted.
+const LOCAL_HOST = /^(?:localhost|127\.|10\.|192\.168\.|172\.(?:1[6-9]|2\d|3[01])\.|0\.0\.0\.0|\[?::1)/;
+export function plainHttpCalls(root) {
+  const hosts = new Map();
+  for (const file of jsFiles(root)) {
+    const text = read(file);
+    if (!text || !/(?:http|ws):\/\//.test(text)) continue;
+    const lines = text.split('\n');
+    lines.forEach((line, i) => {
+      if (/Linking\.|openURL|openBrowser|WebBrowser\.|href=|xmlns|schemas\.|w3\.org|example\.(?:com|org)/.test(line)) return;
+      if (!/\bfetch\s*\(|axios|baseURL|baseUrl|BASE_URL|API_URL|apiUrl|new WebSocket\s*\(|\.get\s*\(|\.post\s*\(/.test(line)) return;
+      for (const m of line.matchAll(/['"`](?:http|ws):\/\/([^/'"`:\s$]+)/g)) {
+        // Real hosts only: not local addresses, not placeholders like http://dummy used for URL parsing.
+        if (LOCAL_HOST.test(m[1]) || /^\$\{/.test(m[1]) || !m[1].includes('.')) continue;
+        if (!hosts.has(m[1])) hosts.set(m[1], `${path.relative(root, file)}:${i + 1}`);
+      }
+    });
+  }
+  if (!hosts.size) return [];
+  const list = [...hosts].map(([h, at]) => `${h} (${at})`);
+  return [
+    {
+      id: 'plain-http-calls',
+      severity: 'medium',
+      area: 'security',
+      title: `API calls over plain HTTP to ${hosts.size} host${hosts.size === 1 ? '' : 's'}`,
+      detail: `${list.slice(0, 4).join(', ')}${list.length > 4 ? ', …' : ''}. Anyone on the same network can read or change this traffic, and Android and iOS block it unless cleartext is allowed. Use https:// (wss:// for sockets).`,
+      fix: { kind: 'security', step: `Switch ${[...hosts.keys()].slice(0, 3).map((h) => `\`${h}\``).join(', ')}${hosts.size > 3 ? ' and the others' : ''} to https:// (wss:// for sockets), then remove any cleartext exceptions you added for them.` },
+    },
+  ];
+}

package/src/stability.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { cleanVersion, findPackageDir, installedVersion } from './project.js';
+import { cleanVersion, findPackageDir, installedVersion, versionFromSpec } from './project.js';
 import { filesImportingWith } from './usage.js';
 
 // Static checks for setups that build fine and then crash at runtime. Each one is a known,
@@ -48,7 +48,7 @@ export function stabilityChecks(project) {
   const root = project.root;
   const pkgJson = JSON.parse(readText(path.join(root, 'package.json')) || '{}');
   const deps = { ...project.devDeps, ...project.deps };
-  const versionOf = (name) => cleanVersion(installedVersion(root, name) || deps[name] || '');
+  const versionOf = (name) => cleanVersion(installedVersion(root, name) || versionFromSpec(name, deps[name]) || '');
 
   // Reanimated needs its Babel plugin: without it, worklets are not compiled and the first
   // animation throws ("Failed to create a worklet" / "Reanimated 2 failed to create a worklet").
@@ -158,6 +158,7 @@ export function stabilityChecks(project) {
     }
   }
 
+  for (const f of iosUsageDescriptions(project)) add(f);
   return findings;
 }
 
@@ -184,3 +185,64 @@ function listPackages(nm) {
   }
   return out;
 }
+
+// iOS terminates an app that touches a protected resource without the matching usage
+// description in Info.plist, and App Review rejects it. Expo managed apps get these from config
+// plugins, so only projects with their own ios/ folder are checked.
+const USAGE_KEYS = [
+  { key: 'NSCameraUsageDescription', what: 'the camera', pkgs: ['react-native-vision-camera', 'react-native-camera', 'expo-camera', 'react-native-camera-kit', 'react-native-qrcode-scanner'] },
+  { key: 'NSPhotoLibraryUsageDescription', what: 'the photo library', pkgs: ['@react-native-camera-roll/camera-roll', '@react-native-community/cameraroll', 'expo-media-library', 'react-native-image-crop-picker'] },
+  { key: 'NSLocationWhenInUseUsageDescription', what: 'location', pkgs: ['@react-native-community/geolocation', 'react-native-geolocation-service', 'expo-location', 'react-native-background-geolocation', '@mauron85/react-native-background-geolocation'] },
+  { key: 'NSMicrophoneUsageDescription', what: 'the microphone', pkgs: ['@react-native-voice/voice', 'react-native-audio-recorder-player', 'expo-audio', 'react-native-audio-record'] },
+  { key: 'NSContactsUsageDescription', what: 'contacts', pkgs: ['react-native-contacts', 'expo-contacts'] },
+  { key: 'NSCalendarsUsageDescription', what: 'calendars', pkgs: ['react-native-calendar-events', 'expo-calendar'] },
+  { key: 'NSBluetoothAlwaysUsageDescription', what: 'Bluetooth', pkgs: ['react-native-ble-plx', 'react-native-ble-manager'] },
+  { key: 'NSFaceIDUsageDescription', what: 'Face ID', pkgs: ['react-native-biometrics', '@sbaiahmed1/react-native-biometrics', 'expo-local-authentication', 'react-native-touch-id'] },
+];
+
+export function iosUsageDescriptions(project) {
+  const iosDir = path.join(project.root, 'ios');
+  if (!fs.existsSync(iosDir) || project.managed) return [];
+  const plists = [];
+  const walk = (dir, depth) => {
+    let entries = [];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (e.isDirectory() && depth < 2 && !['Pods', 'build', 'DerivedData'].includes(e.name) && !/Tests?$|Extension$|Widget/.test(e.name)) walk(path.join(dir, e.name), depth + 1);
+      else if (e.name === 'Info.plist') plists.push(path.join(dir, e.name));
+    }
+  };
+  walk(iosDir, 0);
+  if (!plists.length) return [];
+  const text = plists.map(readText).join('\n');
+  // Expo projects can add the keys at prebuild from app.json/app.config (infoPlist or a config
+  // plugin of the same package): count those too.
+  const expoConfig = project.expoVersion ? ['app.json', 'app.config.js', 'app.config.ts'].map((f) => readText(path.join(project.root, f)) || '').join('\n') : '';
+  const deps = { ...project.deps };
+  const missing = [];
+  for (const u of USAGE_KEYS) {
+    // In Expo projects, prebuild applies the config plugins of installed expo-* packages on its
+    // own, and they add default usage strings.
+    const used = u.pkgs.filter((p) => deps[p] && !(project.expoVersion && p.startsWith('expo-')));
+    if (!used.length) continue;
+    const keys = u.key === 'NSPhotoLibraryUsageDescription' ? [u.key, 'NSPhotoLibraryAddUsageDescription'] : [u.key];
+    const inPlist = keys.some((k) => text.includes(`<key>${k}</key>`));
+    const inExpo = keys.some((k) => expoConfig.includes(k)) || used.some((p) => expoConfig.includes(`"${p}"`) || expoConfig.includes(`'${p}'`));
+    if (!inPlist && !inExpo) missing.push({ ...u, used });
+  }
+  if (!missing.length) return [];
+  return [
+    {
+      id: 'crash-ios-usage-description',
+      severity: 'high',
+      area: 'crash',
+      title: `Info.plist is missing ${missing.length === 1 ? 'a usage description' : `${missing.length} usage descriptions`} (${missing.map((m) => m.key).join(', ')})`,
+      detail: `${missing.map((m) => `${m.used[0]} uses ${m.what}`).join('; ')}. iOS terminates the app the moment it asks for access without the matching key, and App Review rejects the build. Add each key with a sentence that says why the app needs it.`,
+      fix: { kind: 'crash', step: `Add ${missing.map((m) => `\`${m.key}\``).join(', ')} to the app's Info.plist, each with a user-facing reason.` },
+    },
+  ];
+}