deeplink-parity 0.2.1 → 0.3.1

package/README.md

@@ -120,17 +120,40 @@ npx deeplink-parity . --well-known ./staging/well-known
 
 <br>
 
+## Native, Flutter and React Native
+
+Whatever the app is written in, deep links are declared in the same two native files and
+verified against the same two hosted files. The scan looks for those, so a Flutter or
+React Native checkout works with no extra setup:
+
+```bash
+npx deeplink-parity .          # ios/ and android/ live in one repo
+```
+
+**Expo is the exception.** `expo prebuild` generates `ios/` and `android/` at build time
+and they are normally gitignored, so there is nothing to scan. Run the check after a
+prebuild, or on CI after the prebuild step. Pointed at an un-prebuilt Expo project the
+scan says so rather than reporting a clean run — a static `app.json` also lists the
+domains it found, though a JavaScript config is never evaluated.
+
+<br>
+
 ## Hardened against real projects
 
 Synthetic fixtures agree with whatever the author assumed. Real apps do not — so this was
-run against several open-source iOS and Android apps (Wikipedia, Mastodon, Bitwarden,
-DuckDuckGo), which turned up three bugs that fixtures never would have:
+run against open-source apps across all four stacks (Wikipedia, Mastodon, Bitwarden,
+DuckDuckGo, Bluesky, Open Food Facts). Every one of these came from that exercise, and
+none would have surfaced against fixtures alone:
 
 - `applinks:*.example.com` is a valid wildcard declaration, and there is no such host to fetch
 - `myapp://callback` carries a host too, but a custom scheme is not an App Link
 - an entitlements file belongs to one target, so the app must not inherit the widget's bundle id
+- a dev domain's assetlinks names the `applicationIdSuffix` variant, which is still our app
+- an app can declare a domain per country, and firing every request at once caused the very
+  timeouts it then reported — requests are now pooled
+- an Expo checkout has no native project to scan, which read as a clean run
 
-Each is now a regression test. A browser's `http`/`https` filters with no host are correctly
+Each is a regression test. A browser's `http`/`https` filters with no host are correctly
 read as browser registration rather than deep links.
 
 <br>

package/dist/cli.js

@@ -55,8 +55,18 @@ async function main() {
         return;
     }
     const source = wellKnown ? localSource(resolve(wellKnown)) : networkSource();
-    const result = await run({ roots, source, sha256 });
-    if (result.iosApps.length === 0 && result.androidApps.length === 0) {
+    const result = await run({
+        roots,
+        source,
+        sha256,
+        onDiscovered: (count) => {
+            // some apps declare a domain per country; say so before spending minutes on it
+            if (!wellKnown && count > 50) {
+                console.error(`Checking ${count} domains — requests are pooled, so this will take a while.`);
+            }
+        },
+    });
+    if (result.iosApps.length === 0 && result.androidApps.length === 0 && result.findings.length === 0) {
         console.error(`No app configuration declaring deep links was found in ${roots.join(', ')}`);
         console.error('Expected a .entitlements file with applinks:, or an AndroidManifest.xml with intent-filters.');
         process.exit(2);

package/dist/discover/expo.js

@@ -0,0 +1,44 @@
+import { readFile } from 'node:fs/promises';
+import { displayPath, walk } from './walk.js';
+const CONFIG_FILES = new Set(['app.json', 'app.config.js', 'app.config.ts', 'app.config.json']);
+/**
+ * Expo projects declare deep links in the Expo config rather than in the native files,
+ * and `expo prebuild` generates `ios/` and `android/` at build time — they are usually
+ * gitignored. Scanning such a checkout finds nothing, which would read as "all clear".
+ *
+ * Static JSON config is parsed directly. A JavaScript config is not evaluated: doing so
+ * means executing arbitrary code from the repository being inspected, which a checker
+ * should not do. Those projects are pointed at `expo prebuild` instead.
+ */
+export async function detectExpo(root, foundNative) {
+    if (foundNative)
+        return [];
+    const configs = await walk(root, (n) => CONFIG_FILES.has(n));
+    if (configs.length === 0)
+        return [];
+    const findings = [];
+    for (const path of configs) {
+        const source = await readFile(path, 'utf8');
+        if (!/associatedDomains|intentFilters/.test(source))
+            continue;
+        const isStatic = path.endsWith('.json');
+        const domains = isStatic ? staticDomains(source) : [];
+        findings.push({
+            severity: 'warn',
+            rule: 'expo-config-only',
+            message: 'Deep links are declared in the Expo config and no native project was found',
+            detail: domains.length
+                ? `Declared: ${domains.join(', ')}. Run \`npx expo prebuild\` and scan again to verify them.`
+                : 'Run `npx expo prebuild` to generate ios/ and android/, then scan again. A JavaScript config is not evaluated.',
+            source: displayPath(path),
+        });
+    }
+    return findings;
+}
+/** Pull `applinks:` entries out of a static Expo config without executing it. */
+function staticDomains(source) {
+    const domains = new Set();
+    for (const m of source.matchAll(/"applinks:([^"]+)"/g))
+        domains.add(m[1].split('?')[0]);
+    return [...domains];
+}

package/dist/fetch/pool.js

@@ -0,0 +1,21 @@
+/**
+ * Run tasks with a bounded number in flight.
+ *
+ * Some apps declare a domain per country, and firing every request at once looks
+ * like an attack from the receiving end — it also causes the timeouts it then
+ * reports as findings. Results keep input order.
+ */
+export async function mapLimit(items, limit, task) {
+    const results = new Array(items.length);
+    let next = 0;
+    const worker = async () => {
+        while (next < items.length) {
+            const index = next++;
+            results[index] = await task(items[index], index);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+    return results;
+}
+/** Concurrent requests per run. Low enough to stay polite on a shared host. */
+export const FETCH_CONCURRENCY = 6;

package/dist/fetch/wellKnown.js

@@ -1,6 +1,12 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 const TIMEOUT_MS = 10_000;
+/**
+ * Identify the tool to the hosts being read. An operator seeing these requests in a log
+ * should be able to tell what they are and who to ask, rather than finding an anonymous
+ * Node default.
+ */
+const USER_AGENT = 'deeplink-parity (+https://github.com/camosss/deeplink-parity)';
 export const AASA_FILE = 'apple-app-site-association';
 export const ASSETLINKS_FILE = 'assetlinks.json';
 export function aasaUrl(domain) {
@@ -20,7 +26,7 @@ async function fetchRaw(url) {
         const res = await fetch(url, {
             redirect: 'manual',
             signal: controller.signal,
-            headers: { accept: 'application/json' },
+            headers: { accept: 'application/json', 'user-agent': USER_AGENT },
         });
         const redirected = res.status >= 300 && res.status < 400;
         return {

package/dist/run.js

@@ -1,5 +1,7 @@
 import { discoverAndroid } from './discover/android.js';
+import { detectExpo } from './discover/expo.js';
 import { discoverIos } from './discover/ios.js';
+import { FETCH_CONCURRENCY, mapLimit } from './fetch/pool.js';
 import { checkAndroidHost, checkAndroidUnresolved } from './rules/android.js';
 import { checkCrossPlatform } from './rules/cross.js';
 import { aasaPaths, checkIosDomain } from './rules/ios.js';
@@ -7,13 +9,22 @@ import { isWildcardDomain, wildcardFinding } from './rules/wildcard.js';
 function emptyView() {
     return { domains: new Set(), paths: new Map() };
 }
-export async function run({ roots, source, sha256 }) {
+export async function run({ roots, source, sha256, onDiscovered }) {
     const discovered = await Promise.all(roots.map(async (root) => Promise.all([discoverIos(root), discoverAndroid(root)])));
     const iosApps = discovered.flatMap(([ios]) => ios);
     const androidApps = discovered.flatMap(([, android]) => android);
     const findings = [];
+    // an Expo checkout has no native project committed; say so rather than report nothing
+    if (iosApps.length === 0 && androidApps.length === 0) {
+        for (const root of roots)
+            findings.push(...(await detectExpo(root, false)));
+    }
     const ios = emptyView();
     const android = emptyView();
+    onDiscovered?.(new Set([
+        ...iosApps.flatMap((a) => a.domains),
+        ...androidApps.flatMap((a) => a.hosts.map((h) => h.host)),
+    ]).size);
     for (const app of iosApps) {
         // the same domain can be declared by several targets; fetch it once
         const fresh = app.domains.filter((d) => !ios.domains.has(d));
@@ -21,7 +32,7 @@ export async function run({ roots, source, sha256 }) {
         const wildcards = fresh.filter(isWildcardDomain);
         wildcards.forEach((d) => findings.push(wildcardFinding(d, app.entitlementsPath)));
         const pending = fresh.filter((d) => !isWildcardDomain(d));
-        const results = await Promise.all(pending.map((d) => source.aasa(d)));
+        const results = await mapLimit(pending, FETCH_CONCURRENCY, (d) => source.aasa(d));
         pending.forEach((domain, i) => {
             const { findings: domainFindings, aasa } = checkIosDomain(app, domain, results[i]);
             findings.push(...domainFindings);
@@ -41,9 +52,8 @@ export async function run({ roots, source, sha256 }) {
             .filter((h) => isWildcardDomain(h.host))
             .forEach((h) => findings.push(wildcardFinding(h.host, app.manifestPath)));
         const pending = fresh.filter((h) => !isWildcardDomain(h.host));
-        const results = await Promise.all(
         // an unverified host is never checked by the system, so there is nothing to fetch
-        pending.map((h) => (h.autoVerify ? source.assetlinks(h.host) : Promise.resolve(null))));
+        const results = await mapLimit(pending, FETCH_CONCURRENCY, (h) => h.autoVerify ? source.assetlinks(h.host) : Promise.resolve(null));
         pending.forEach((entry, i) => {
             const res = results[i] ?? { url: '', ok: false, redirected: false };
             findings.push(...checkAndroidHost(app, entry, res, { sha256 }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deeplink-parity",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Checks that what your mobile app declares about deep links matches what is actually hosted — across iOS and Android.",
   "type": "module",
   "bin": {