deeplink-parity 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hosung Kang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,142 @@
+# deeplink-parity
+
+Checks that what your app **declares** about deep links matches what is actually **hosted** — on both iOS and Android, from one command.
+
+```bash
+npx deeplink-parity .
+```
+
+```
+deeplink-parity · 3 domain(s) checked
+
+ERROR  links.example.com
+       AASA responded with 404
+       Universal Links fall through to the browser
+       https://links.example.com/.well-known/apple-app-site-association
+
+WARN   promo.example.com
+       Declared on iOS but not on Android
+       The same link opens the app on iOS and the browser on Android
+
+1 error, 1 warn, 0 info
+```
+
+<br>
+
+## Why
+
+Deep links fail **silently**. There is no crash, no error log, no red test. A user taps a link, the browser opens instead of your app, and they shrug and move on. Nobody finds out for months.
+
+And the configuration is split across places with **different owners**:
+
+| | Owner |
+|---|---|
+| `*.entitlements` | iOS developer |
+| `AndroidManifest.xml` | Android developer |
+| `apple-app-site-association`, `assetlinks.json` | web / infra team, separate repo, separate deploy |
+| SHA256 signing fingerprint | release manager / Play Console |
+
+Each side is individually correct. Breakage happens **at the seams**, and no repo's CI covers a seam that spans two repos and a live domain.
+
+Existing validators check one hosted file at a time. None of them start from your app's own configuration, and none of them compare the two platforms — so a domain that works on iOS and quietly fails on Android goes unnoticed.
+
+<br>
+
+## What it checks
+
+No configuration file. Domains are discovered from your app, then the matching well-known files are fetched from those domains.
+
+**Errors** — the link is broken today
+
+- The AASA file is unreachable, redirects (iOS does not follow redirects), or does not parse
+- The AASA file does not list your `TeamID.bundleID`
+- `assetlinks.json` is unreachable, does not parse, or has no `handle_all_urls` statement
+- `assetlinks.json` does not list your `applicationId`
+- Your signing fingerprint is missing from `assetlinks.json` (with `--sha256`)
+
+**Warnings** — one platform works and the other does not
+
+- **A domain is declared on iOS but not Android, or the reverse**
+- An `https` intent-filter has no `autoVerify`
+- A manifest host reference could not be resolved
+
+**Info**
+
+- The declared path sets differ between platforms
+- The AASA file declares no paths or components
+
+<br>
+
+## Usage
+
+```bash
+npx deeplink-parity [path] [options]
+
+  --sha256 <fingerprint>   Android signing fingerprint to look for in assetlinks.json
+  --well-known <dir>       Read well-known files from <dir>/<domain>/ instead of the network
+  --json                   Machine-readable output
+```
+
+Exits `1` when there is at least one error, so it drops into CI unchanged.
+
+### Run it on a schedule — this is the point
+
+Your deep-link configuration changes a few times a year. The things that break it do not live in your repo at all:
+
+- the web team's deploy puts a redirect in front of `/.well-known/`
+- a domain expires or its DNS moves
+- the signing key is rotated, or the app moves to Play App Signing
+- an attribution vendor changes their hosting
+
+A pull-request check never sees any of this. **A daily scheduled run does.** See [`examples/scheduled.yml`](examples/scheduled.yml).
+
+### Validate before deploying
+
+`--well-known <dir>` reads the files from disk instead of the network, so the web team can check staged files before they ship — and CI can run with no egress.
+
+```bash
+npx deeplink-parity . --well-known ./staging/well-known
+```
+
+<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:
+
+- `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
+
+Each is now a regression test. A browser's `http`/`https` filters with no host are correctly
+read as browser registration rather than deep links.
+
+<br>
+
+## What it does not do
+
+- **Deferred deep links are out of scope.** Install-then-open attribution is decided at runtime by your attribution SDK's servers. No static check can confirm it, and reporting a pass would be worse than saying nothing.
+- **It does not prove path equivalence.** iOS and Android use different path-matching engines. Differing path sets are reported as `info` with both sides shown, for a human to judge — not asserted as a bug.
+- **It does not run your app.** Route handling inside the app is not inspected.
+
+<br>
+
+## Development
+
+```bash
+npm install
+npm test        # runs fully offline against fixtures/
+npm run typecheck
+```
+
+`fixtures/` holds synthetic iOS and Android projects covering literal hosts, chained
+`@string` references resolved through gradle `resValue` and `.properties`, flavor-specific
+values, and unresolvable references.
+
+<br>
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+import { resolve } from 'node:path';
+import { localSource, networkSource } from './fetch/wellKnown.js';
+import { exitCodeFor, printReport } from './report/console.js';
+import { run } from './run.js';
+const USAGE = `deeplink-parity — check that what your app declares about deep links
+matches what is actually hosted, across iOS and Android.
+
+Usage
+  deeplink-parity [path] [options]
+
+Options
+  --sha256 <fingerprint>   Android signing fingerprint to look for in assetlinks.json
+  --well-known <dir>       Read well-known files from <dir>/<domain>/ instead of the network
+  --json                   Machine-readable output
+  -h, --help               Show this message
+`;
+function parseArgs(argv) {
+    const args = argv.slice(2);
+    let root = '.';
+    let json = false;
+    let help = false;
+    let sha256;
+    let wellKnown;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--json')
+            json = true;
+        else if (arg === '-h' || arg === '--help')
+            help = true;
+        else if (arg === '--sha256')
+            sha256 = args[++i];
+        else if (arg === '--well-known')
+            wellKnown = args[++i];
+        else if (!arg.startsWith('-'))
+            root = arg;
+    }
+    return { root: resolve(root), json, help, sha256, wellKnown };
+}
+async function main() {
+    const { root, json, help, sha256, wellKnown } = parseArgs(process.argv);
+    if (help) {
+        console.log(USAGE);
+        return;
+    }
+    const source = wellKnown ? localSource(resolve(wellKnown)) : networkSource();
+    const result = await run({ root, source, sha256 });
+    if (result.iosApps.length === 0 && result.androidApps.length === 0) {
+        console.error(`No app configuration declaring deep links was found in ${root}`);
+        console.error('Expected a .entitlements file with applinks:, or an AndroidManifest.xml with intent-filters.');
+        process.exit(2);
+    }
+    if (json) {
+        console.log(JSON.stringify({
+            ios: result.iosApps.map((a) => ({
+                entitlements: a.entitlementsPath,
+                teamId: a.teamId,
+                bundleId: a.bundleId,
+                domains: a.domains,
+            })),
+            android: result.androidApps.map((a) => ({
+                manifest: a.manifestPath,
+                packageIds: a.packageIds,
+                hosts: a.hosts.map((h) => h.host),
+            })),
+            findings: result.findings,
+        }, null, 2));
+    }
+    else {
+        printReport(result.findings, result.domains);
+    }
+    process.exit(exitCodeFor(result.findings));
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(2);
+});

package/dist/discover/android.js

@@ -0,0 +1,133 @@
+import { readFile } from 'node:fs/promises';
+import { relative } from 'node:path';
+import { XMLParser } from 'fast-xml-parser';
+import { emptyIndex, indexProperties, indexResValues, indexStrings, resolveRef, } from '../resolve/androidResources.js';
+import { walk } from './walk.js';
+const VIEW_ACTION = 'android.intent.action.VIEW';
+const BROWSABLE = 'android.intent.category.BROWSABLE';
+/** fast-xml-parser hands back a single object when an element occurs once. */
+function asArray(value) {
+    if (value === undefined)
+        return [];
+    return Array.isArray(value) ? value : [value];
+}
+function attr(node, name) {
+    if (!node || typeof node !== 'object')
+        return undefined;
+    const value = node[`@_${name}`];
+    return typeof value === 'string' ? value : undefined;
+}
+function collectIntentFilters(node, out) {
+    if (!node || typeof node !== 'object')
+        return;
+    for (const [key, value] of Object.entries(node)) {
+        if (key.startsWith('@_'))
+            continue;
+        if (key === 'intent-filter')
+            out.push(...asArray(value));
+        else
+            for (const child of asArray(value))
+                collectIntentFilters(child, out);
+    }
+}
+function applicationIds(gradleSources) {
+    const ids = new Set();
+    for (const src of gradleSources) {
+        for (const m of src.matchAll(/applicationId\s*(?:=|\s)\s*["']([^"']+)["']/g)) {
+            ids.add(m[1]);
+        }
+    }
+    return [...ids];
+}
+export async function discoverAndroid(root) {
+    const manifests = (await walk(root, (n) => n === 'AndroidManifest.xml')).filter(
+    // androidTest/debug manifests rarely declare shipping deep links
+    (p) => !/src\/(androidTest|test)\//.test(p));
+    if (manifests.length === 0)
+        return [];
+    const index = emptyIndex();
+    const gradlePaths = await walk(root, (n) => n === 'build.gradle' || n === 'build.gradle.kts');
+    await indexStrings((await walk(root, (n) => n.endsWith('.xml'))).filter((p) => /res\/values[^/]*\//.test(p)), index);
+    await indexResValues(gradlePaths, index);
+    await indexProperties(await walk(root, (n) => n.endsWith('.properties')), index);
+    const gradleSources = await Promise.all(gradlePaths.map((p) => readFile(p, 'utf8')));
+    const packageIds = applicationIds(gradleSources);
+    const parser = new XMLParser({ ignoreAttributes: false, attributeNamePrefix: '@_' });
+    const apps = [];
+    for (const manifestPath of manifests) {
+        const parsed = parser.parse(await readFile(manifestPath, 'utf8'));
+        const filters = [];
+        collectIntentFilters(parsed, filters);
+        const hosts = new Map();
+        const unresolved = [];
+        for (const filter of filters) {
+            const node = filter;
+            const actions = asArray(node['action']).map((a) => attr(a, 'android:name'));
+            const categories = asArray(node['category']).map((c) => attr(c, 'android:name'));
+            if (!actions.includes(VIEW_ACTION))
+                continue;
+            if (!categories.includes(BROWSABLE))
+                continue;
+            const autoVerify = attr(node, 'android:autoVerify') === 'true';
+            const dataNodes = asArray(node['data']);
+            // scheme/host/path are declared across sibling <data> elements and merge per filter
+            const schemes = new Set();
+            const paths = new Set();
+            const rawHosts = [];
+            for (const data of dataNodes) {
+                for (const raw of [attr(data, 'android:scheme')].filter(Boolean)) {
+                    resolveRef(raw, index).values.forEach((v) => schemes.add(v));
+                }
+                for (const key of ['android:path', 'android:pathPrefix', 'android:pathPattern']) {
+                    const raw = attr(data, key);
+                    if (!raw)
+                        continue;
+                    // a prefix implicitly matches everything below it; make that explicit so it
+                    // lines up with the glob style AASA uses
+                    const suffix = key === 'android:pathPrefix' ? '*' : '';
+                    resolveRef(raw, index).values.forEach((v) => paths.add(`${v}${suffix}`));
+                }
+                const rawHost = attr(data, 'android:host');
+                if (rawHost)
+                    rawHosts.push(rawHost);
+            }
+            // Only http(s) filters are App Links. A custom scheme like `bitwarden://totp`
+            // also carries a host, but it has no assetlinks counterpart and nothing to verify.
+            if (!schemes.has('http') && !schemes.has('https'))
+                continue;
+            for (const raw of rawHosts) {
+                const resolution = resolveRef(raw, index);
+                if (resolution.values.length === 0) {
+                    unresolved.push({ raw, reason: resolution.unresolved ?? 'resolution failed' });
+                    continue;
+                }
+                for (const host of resolution.values) {
+                    const existing = hosts.get(host);
+                    if (existing) {
+                        existing.autoVerify ||= autoVerify;
+                        schemes.forEach((s) => existing.schemes.includes(s) || existing.schemes.push(s));
+                        paths.forEach((p) => existing.paths.includes(p) || existing.paths.push(p));
+                    }
+                    else {
+                        hosts.set(host, {
+                            host,
+                            raw,
+                            schemes: [...schemes],
+                            paths: [...paths],
+                            autoVerify,
+                        });
+                    }
+                }
+            }
+        }
+        if (hosts.size === 0 && unresolved.length === 0)
+            continue;
+        apps.push({
+            manifestPath: relative(root, manifestPath),
+            packageIds,
+            hosts: [...hosts.values()],
+            unresolved,
+        });
+    }
+    return apps;
+}

package/dist/discover/ios.js

@@ -0,0 +1,91 @@
+import { readFile } from 'node:fs/promises';
+import { relative } from 'node:path';
+import plist from 'plist';
+import { walk } from './walk.js';
+/**
+ * Associated Domains entries look like `applinks:example.com`. A domain may carry
+ * query-parameter options (`?mode=developer`) which are not part of the host.
+ */
+function parseAssociatedDomains(entries) {
+    if (!Array.isArray(entries))
+        return [];
+    const domains = [];
+    for (const raw of entries) {
+        if (typeof raw !== 'string')
+            continue;
+        if (!raw.startsWith('applinks:'))
+            continue;
+        const host = raw.slice('applinks:'.length).split('?')[0].trim();
+        if (host && !domains.includes(host))
+            domains.push(host);
+    }
+    return domains;
+}
+/**
+ * Build settings can be literals or `$(VARIABLE)` references. We only take literals —
+ * a reference means the real value lives in an xcconfig we are not resolving yet.
+ */
+function literalSetting(block, key) {
+    const m = block.match(new RegExp(`\\n\\s*${key}\\s*=\\s*"?([^";\\n]+)"?;`));
+    const value = m?.[1]?.trim();
+    if (!value || value.includes('$(') || value === '""')
+        return undefined;
+    return value;
+}
+/**
+ * A project has one bundle id per target, not one per project. The entitlements path
+ * and the bundle id live in the same `buildSettings` block, so pairing them there
+ * avoids attributing the widget's identifier to the app.
+ */
+function signingByEntitlements(pbxproj) {
+    const map = new Map();
+    for (const m of pbxproj.matchAll(/buildSettings = \{([\s\S]*?)\n\s*\};/g)) {
+        const block = m[1];
+        const entitlements = literalSetting(block, 'CODE_SIGN_ENTITLEMENTS');
+        if (!entitlements)
+            continue;
+        const existing = map.get(entitlements) ?? {};
+        map.set(entitlements, {
+            bundleId: existing.bundleId ?? literalSetting(block, 'PRODUCT_BUNDLE_IDENTIFIER'),
+            teamId: existing.teamId ?? literalSetting(block, 'DEVELOPMENT_TEAM'),
+        });
+    }
+    return map;
+}
+export async function discoverIos(root) {
+    const entitlementFiles = await walk(root, (n) => n.endsWith('.entitlements'));
+    if (entitlementFiles.length === 0)
+        return [];
+    const pbxprojPaths = await walk(root, (n) => n === 'project.pbxproj');
+    const signing = new Map();
+    for (const path of pbxprojPaths) {
+        for (const [k, v] of signingByEntitlements(await readFile(path, 'utf8'))) {
+            if (!signing.has(k))
+                signing.set(k, v);
+        }
+    }
+    const apps = [];
+    for (const path of entitlementFiles) {
+        let parsed;
+        try {
+            parsed = plist.parse(await readFile(path, 'utf8'));
+        }
+        catch {
+            continue;
+        }
+        const dict = parsed;
+        const domains = parseAssociatedDomains(dict['com.apple.developer.associated-domains']);
+        if (domains.length === 0)
+            continue;
+        // pbxproj records the entitlements path relative to SOURCE_ROOT
+        const rel = relative(root, path);
+        const target = signing.get(rel) ?? {};
+        apps.push({
+            entitlementsPath: rel,
+            domains,
+            bundleId: target.bundleId,
+            teamId: target.teamId,
+        });
+    }
+    return apps;
+}

package/dist/discover/walk.js

@@ -0,0 +1,36 @@
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+const SKIP_DIRS = new Set([
+    'node_modules',
+    'Pods',
+    'Carthage',
+    '.git',
+    'build',
+    'DerivedData',
+    'dist',
+    '.build',
+    '.gradle',
+    '.idea',
+]);
+/** Depth-first file scan that skips dependency and build output directories. */
+export async function walk(dir, match, out = []) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            if (SKIP_DIRS.has(entry.name))
+                continue;
+            // .xcodeproj is a directory but holds project.pbxproj
+            await walk(join(dir, entry.name), match, out);
+        }
+        else if (match(entry.name)) {
+            out.push(join(dir, entry.name));
+        }
+    }
+    return out;
+}

package/dist/fetch/wellKnown.js

@@ -0,0 +1,86 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const TIMEOUT_MS = 10_000;
+export const AASA_FILE = 'apple-app-site-association';
+export const ASSETLINKS_FILE = 'assetlinks.json';
+export function aasaUrl(domain) {
+    return `https://${domain}/.well-known/${AASA_FILE}`;
+}
+export function assetlinksUrl(domain) {
+    return `https://${domain}/.well-known/${ASSETLINKS_FILE}`;
+}
+/**
+ * Apple does not follow redirects when fetching an AASA file, so neither do we —
+ * a 3xx here is the finding, not something to chase.
+ */
+async function fetchRaw(url) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+    try {
+        const res = await fetch(url, {
+            redirect: 'manual',
+            signal: controller.signal,
+            headers: { accept: 'application/json' },
+        });
+        const redirected = res.status >= 300 && res.status < 400;
+        return {
+            url,
+            ok: res.status === 200,
+            status: res.status,
+            redirected,
+            location: res.headers.get('location') ?? undefined,
+            contentType: res.headers.get('content-type') ?? undefined,
+            body: redirected ? undefined : await res.text(),
+        };
+    }
+    catch (err) {
+        const aborted = err instanceof Error && err.name === 'AbortError';
+        return {
+            url,
+            ok: false,
+            redirected: false,
+            error: aborted
+                ? `timed out after ${TIMEOUT_MS / 1000}s`
+                : err instanceof Error
+                    ? err.message
+                    : String(err),
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export function networkSource() {
+    return {
+        aasa: (domain) => fetchRaw(aasaUrl(domain)),
+        assetlinks: (domain) => fetchRaw(assetlinksUrl(domain)),
+    };
+}
+/**
+ * Read well-known files from disk instead of the network, laid out as
+ * `<dir>/<domain>/<file>`. Lets CI run without egress, and lets a web team validate
+ * staged files before they are deployed. A missing file is reported as a 404 so the
+ * rules behave exactly as they would against a live host.
+ */
+export function localSource(dir) {
+    const read = async (domain, file) => {
+        const path = join(dir, domain, file);
+        try {
+            return {
+                url: path,
+                ok: true,
+                status: 200,
+                redirected: false,
+                contentType: 'application/json',
+                body: await readFile(path, 'utf8'),
+            };
+        }
+        catch {
+            return { url: path, ok: false, status: 404, redirected: false };
+        }
+    };
+    return {
+        aasa: (domain) => read(domain, AASA_FILE),
+        assetlinks: (domain) => read(domain, ASSETLINKS_FILE),
+    };
+}

package/dist/parse/aasa.js

@@ -0,0 +1,67 @@
+/**
+ * AASA has two shapes for `applinks.details`:
+ *   legacy   — an array of `{ appID, paths }`, or an object keyed by appID
+ *   current  — an array of `{ appIDs, components }`
+ * Both are still honoured by iOS, so we normalise rather than pick a side.
+ */
+export function parseAasa(body) {
+    let json;
+    try {
+        json = JSON.parse(body);
+    }
+    catch (err) {
+        return { error: err instanceof Error ? err.message : 'invalid JSON' };
+    }
+    const root = json;
+    const applinks = root?.['applinks'];
+    if (!applinks)
+        return { error: 'no "applinks" key' };
+    const rawDetails = applinks['details'];
+    const details = [];
+    const pushDetail = (entry, fallbackAppId) => {
+        const appIds = [];
+        if (Array.isArray(entry['appIDs'])) {
+            for (const id of entry['appIDs'])
+                if (typeof id === 'string')
+                    appIds.push(id);
+        }
+        if (typeof entry['appID'] === 'string')
+            appIds.push(entry['appID']);
+        if (appIds.length === 0 && fallbackAppId)
+            appIds.push(fallbackAppId);
+        details.push({
+            appIds,
+            paths: Array.isArray(entry['paths'])
+                ? entry['paths'].filter((p) => typeof p === 'string')
+                : undefined,
+            components: Array.isArray(entry['components']) ? entry['components'] : undefined,
+        });
+    };
+    if (Array.isArray(rawDetails)) {
+        for (const entry of rawDetails) {
+            if (entry && typeof entry === 'object')
+                pushDetail(entry);
+        }
+    }
+    else if (rawDetails && typeof rawDetails === 'object') {
+        // legacy object form: { "TEAMID.bundle.id": { paths: [...] } }
+        for (const [appId, entry] of Object.entries(rawDetails)) {
+            if (entry && typeof entry === 'object') {
+                pushDetail(entry, appId);
+            }
+        }
+    }
+    else {
+        return { error: '"applinks.details" missing or not an array/object' };
+    }
+    return { aasa: { details } };
+}
+/** An AASA appID may be `TEAMID.bundle.id` or the wildcard `TEAMID.*`. */
+export function appIdMatches(declared, teamId, bundleId) {
+    const expected = `${teamId}.${bundleId}`;
+    if (declared === expected)
+        return true;
+    if (declared === `${teamId}.*`)
+        return true;
+    return false;
+}

package/dist/parse/assetlinks.js

@@ -0,0 +1,40 @@
+export const HANDLE_ALL_URLS = 'delegate_permission/common.handle_all_urls';
+/**
+ * assetlinks.json is a top-level array of statements. Only `android_app` targets
+ * matter here; web targets in the same file are ignored rather than treated as errors.
+ */
+export function parseAssetlinks(body) {
+    let json;
+    try {
+        json = JSON.parse(body);
+    }
+    catch (err) {
+        return { error: err instanceof Error ? err.message : 'invalid JSON' };
+    }
+    if (!Array.isArray(json))
+        return { error: 'top level is not an array' };
+    const statements = [];
+    for (const entry of json) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const record = entry;
+        const target = record['target'];
+        if (!target || target['namespace'] !== 'android_app')
+            continue;
+        const fingerprints = Array.isArray(target['sha256_cert_fingerprints'])
+            ? target['sha256_cert_fingerprints'].filter((f) => typeof f === 'string')
+            : [];
+        statements.push({
+            relations: Array.isArray(record['relation'])
+                ? record['relation'].filter((r) => typeof r === 'string')
+                : [],
+            packageName: typeof target['package_name'] === 'string' ? target['package_name'] : undefined,
+            fingerprints,
+        });
+    }
+    return { statements };
+}
+/** Fingerprints are colon-separated hex; comparison ignores case and separators. */
+export function normalizeFingerprint(value) {
+    return value.replace(/[^a-fA-F0-9]/g, '').toUpperCase();
+}

package/dist/report/console.js

@@ -0,0 +1,40 @@
+const COLOR = {
+    error: '',
+    warn: '',
+    info: '',
+};
+const DIM = '';
+const BOLD = '';
+const RESET = '';
+const LABEL = { error: 'ERROR', warn: 'WARN ', info: 'INFO ' };
+const ORDER = ['error', 'warn', 'info'];
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const paint = (s, c) => (useColor ? `${c}${s}${RESET}` : s);
+export function printReport(findings, checkedDomains) {
+    console.log(`\n${paint('deeplink-parity', BOLD)} ${DIM}·${RESET} ${checkedDomains.length} domain(s) checked\n`);
+    if (findings.length === 0) {
+        console.log(paint('No problems found', ''));
+        console.log();
+        return;
+    }
+    for (const severity of ORDER) {
+        for (const f of findings.filter((x) => x.severity === severity)) {
+            const head = paint(LABEL[severity], COLOR[severity]);
+            // Not every finding is tied to a domain — fall back to the rule id so the line is never blank
+            const subject = f.domain ? paint(f.domain, BOLD) : paint(f.rule, DIM);
+            console.log(`${head}  ${subject}`);
+            console.log(`       ${f.message}`);
+            if (f.detail)
+                console.log(`       ${paint(f.detail, DIM)}`);
+            if (f.source)
+                console.log(`       ${paint(f.source, DIM)}`);
+            console.log();
+        }
+    }
+    const counts = ORDER.map((s) => `${findings.filter((f) => f.severity === s).length} ${s}`);
+    console.log(counts.join(', '));
+    console.log();
+}
+export function exitCodeFor(findings) {
+    return findings.some((f) => f.severity === 'error') ? 1 : 0;
+}

package/dist/resolve/androidResources.js

@@ -0,0 +1,120 @@
+import { readFile } from 'node:fs/promises';
+const MAX_DEPTH = 8;
+export function emptyIndex() {
+    return { strings: new Map(), resValues: new Map(), properties: new Map() };
+}
+function stripQuotes(value) {
+    const trimmed = value.trim();
+    const quoted = /^(["'])([\s\S]*)\1$/.exec(trimmed);
+    return quoted ? quoted[2] : trimmed;
+}
+export async function indexStrings(paths, index) {
+    for (const path of paths) {
+        const xml = await readFile(path, 'utf8');
+        for (const m of xml.matchAll(/<string\s+[^>]*name="([^"]+)"[^>]*>([\s\S]*?)<\/string>/g)) {
+            if (!index.strings.has(m[1]))
+                index.strings.set(m[1], m[2].trim());
+        }
+    }
+}
+/**
+ * Matches both the Kotlin DSL (`resValue(type = "string", name = "x", value = expr)`,
+ * arguments in any order) and the Groovy form (`resValue "string", "x", expr`).
+ * Flavor attribution is deliberately skipped — a name that differs across variants
+ * yields several candidates and we check all of them, which is what a checker wants.
+ */
+export async function indexResValues(paths, index) {
+    for (const path of paths) {
+        const src = await readFile(path, 'utf8');
+        for (const m of src.matchAll(/resValue\s*\(([\s\S]*?)\)\s*(?:\n|$)/g)) {
+            const args = m[1];
+            if (!/["']string["']/.test(args))
+                continue;
+            const name = /name\s*=\s*["']([^"']+)["']/.exec(args)?.[1];
+            const value = /value\s*=\s*([\s\S]+?)\s*$/.exec(args)?.[1];
+            if (!name || !value)
+                continue;
+            const list = index.resValues.get(name) ?? [];
+            list.push(value.trim());
+            index.resValues.set(name, list);
+        }
+        for (const m of src.matchAll(/resValue\s+["']string["']\s*,\s*["']([^"']+)["']\s*,\s*(.+)/g)) {
+            const list = index.resValues.get(m[1]) ?? [];
+            list.push(m[2].trim());
+            index.resValues.set(m[1], list);
+        }
+    }
+}
+export async function indexProperties(paths, index) {
+    for (const path of paths) {
+        const text = await readFile(path, 'utf8');
+        for (const line of text.split('\n')) {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith('#') || trimmed.startsWith('!'))
+                continue;
+            const eq = trimmed.indexOf('=');
+            if (eq <= 0)
+                continue;
+            const key = trimmed.slice(0, eq).trim();
+            if (!index.properties.has(key)) {
+                index.properties.set(key, stripQuotes(trimmed.slice(eq + 1)));
+            }
+        }
+    }
+}
+/**
+ * Reduce a gradle value expression to a literal.
+ * Handles string literals and property lookups — `props["KEY"]`, `props.getProperty("KEY")`,
+ * with or without a trailing cast. Anything else is left unresolved rather than guessed at.
+ */
+function resolveGradleExpression(expr, index) {
+    const literal = /^(["'])([^"']*)\1(?:\s+as\s+\w+)?$/.exec(expr.trim());
+    if (literal)
+        return literal[2];
+    const lookup = /\[\s*["']([^"']+)["']\s*\]/.exec(expr) ?? /getProperty\(\s*["']([^"']+)["']\s*\)/.exec(expr);
+    if (lookup)
+        return index.properties.get(lookup[1]);
+    return undefined;
+}
+/**
+ * Expand a manifest attribute value. `@string/x` may chain through another `@string/y`
+ * before landing on a literal, so resolution recurses with a depth guard.
+ */
+export function resolveRef(raw, index, depth = 0) {
+    const value = raw.trim();
+    if (!value.startsWith('@string/'))
+        return { values: value ? [value] : [] };
+    if (depth >= MAX_DEPTH)
+        return { values: [], unresolved: 'reference chain is too deep or circular' };
+    const name = value.slice('@string/'.length);
+    const candidates = [];
+    const fromStrings = index.strings.get(name);
+    if (fromStrings !== undefined)
+        candidates.push(fromStrings);
+    let sawUnresolvedExpression = false;
+    for (const expr of index.resValues.get(name) ?? []) {
+        const literal = resolveGradleExpression(expr, index);
+        if (literal === undefined)
+            sawUnresolvedExpression = true;
+        else
+            candidates.push(literal);
+    }
+    if (candidates.length === 0) {
+        return {
+            values: [],
+            unresolved: sawUnresolvedExpression
+                ? `could not resolve the gradle resValue expression for ${name}`
+                : `no definition found for @string/${name}`,
+        };
+    }
+    const values = new Set();
+    let unresolved = sawUnresolvedExpression
+        ? `some gradle resValue values for ${name} could not be resolved`
+        : undefined;
+    for (const candidate of candidates) {
+        const nested = resolveRef(candidate, index, depth + 1);
+        nested.values.forEach((v) => values.add(v));
+        unresolved ??= nested.unresolved;
+    }
+    return { values: [...values], unresolved: values.size > 0 ? undefined : unresolved };
+}

package/dist/rules/android.js

@@ -0,0 +1,109 @@
+import { HANDLE_ALL_URLS, normalizeFingerprint, parseAssetlinks } from '../parse/assetlinks.js';
+export function checkAndroidHost(app, entry, res, options) {
+    const findings = [];
+    const domain = entry.host;
+    const source = res.url;
+    // Only autoVerify hosts are verified by the system; the rest open a chooser by design
+    if (!entry.autoVerify) {
+        findings.push({
+            severity: 'warn',
+            rule: 'intent-filter-no-autoverify',
+            domain,
+            message: 'This https intent-filter has no autoVerify',
+            detail: 'App Links stay unverified, so the user sees a disambiguation dialog',
+            source: app.manifestPath,
+        });
+        return findings;
+    }
+    if (res.error || !res.ok) {
+        findings.push({
+            severity: 'error',
+            rule: 'assetlinks-unreachable',
+            domain,
+            message: res.error
+                ? `Could not fetch assetlinks.json — ${res.error}`
+                : `assetlinks.json responded with ${res.status}`,
+            detail: 'App Link verification fails and links fall through to the browser',
+            source,
+        });
+        return findings;
+    }
+    const { statements, error } = parseAssetlinks(res.body ?? '');
+    if (!statements) {
+        findings.push({
+            severity: 'error',
+            rule: 'assetlinks-invalid',
+            domain,
+            message: `Could not parse assetlinks.json — ${error}`,
+            source,
+        });
+        return findings;
+    }
+    const handling = statements.filter((s) => s.relations.includes(HANDLE_ALL_URLS));
+    if (handling.length === 0) {
+        findings.push({
+            severity: 'error',
+            rule: 'assetlinks-no-statement',
+            domain,
+            message: `assetlinks.json declares no ${HANDLE_ALL_URLS} statement`,
+            source,
+        });
+        return findings;
+    }
+    if (app.packageIds.length === 0) {
+        findings.push({
+            severity: 'info',
+            rule: 'package-unknown',
+            domain,
+            message: 'Skipped the package_name check — could not determine the applicationId',
+            source: app.manifestPath,
+        });
+        return findings;
+    }
+    const matched = handling.filter((s) => s.packageName && app.packageIds.includes(s.packageName));
+    if (matched.length === 0) {
+        findings.push({
+            severity: 'error',
+            rule: 'assetlinks-package-missing',
+            domain,
+            message: `assetlinks.json does not list ${app.packageIds.join(' / ')}`,
+            detail: `Declared package_name: ${handling.map((s) => s.packageName ?? '(none)').join(', ')}`,
+            source,
+        });
+        return findings;
+    }
+    if (options.sha256) {
+        const wanted = normalizeFingerprint(options.sha256);
+        const declared = matched.flatMap((s) => s.fingerprints.map(normalizeFingerprint));
+        if (!declared.includes(wanted)) {
+            findings.push({
+                severity: 'error',
+                rule: 'assetlinks-fingerprint-missing',
+                domain,
+                message: 'The signing fingerprint is not listed in assetlinks.json',
+                detail: `None of the ${declared.length} declared fingerprint(s) match`,
+                source,
+            });
+        }
+    }
+    else {
+        findings.push({
+            severity: 'info',
+            rule: 'fingerprint-skipped',
+            domain,
+            message: 'Skipped the signing fingerprint check',
+            detail: 'Pass --sha256 <fingerprint> to enable it',
+            source,
+        });
+    }
+    return findings;
+}
+export function checkAndroidUnresolved(app) {
+    return app.unresolved.map((u) => ({
+        severity: 'warn',
+        rule: 'host-unresolved',
+        message: `Could not resolve host ${u.raw}`,
+        detail: `${u.reason}. This host was skipped.`,
+        source: app.manifestPath,
+    }));
+}

package/dist/rules/cross.js

@@ -0,0 +1,79 @@
+/**
+ * Android declares prefixes and patterns; AASA declares glob-ish paths. Normalising both
+ * to a lowercase glob makes the common cases comparable without pretending the two
+ * matching engines are equivalent.
+ */
+function normalizePath(path) {
+    return path
+        .trim()
+        .toLowerCase()
+        .replace(/^not\s+/, '!')
+        // `.*` is the pathPattern spelling of a wildcard
+        .replace(/\.\*/g, '*')
+        .replace(/\*+$/, '*')
+        // `/item/*` and the prefix form `/item*` describe the same subtree
+        .replace(/\/\*$/, '*')
+        .replace(/\/$/, '');
+}
+function normalizeSet(paths) {
+    return new Set(paths.map(normalizePath).filter(Boolean));
+}
+/**
+ * The reason this tool exists: existing validators look at one platform, so a domain
+ * that works on iOS and silently fails on Android goes unnoticed.
+ */
+export function checkCrossPlatform(ios, android) {
+    const findings = [];
+    // A platform with no declarations at all is a single-platform repo, not a gap
+    if (ios.domains.size === 0 || android.domains.size === 0)
+        return findings;
+    for (const domain of ios.domains) {
+        if (android.domains.has(domain))
+            continue;
+        findings.push({
+            severity: 'warn',
+            rule: 'platform-domain-gap',
+            domain,
+            message: 'Declared on iOS but not on Android',
+            detail: 'The same link opens the app on iOS and the browser on Android',
+        });
+    }
+    for (const domain of android.domains) {
+        if (ios.domains.has(domain))
+            continue;
+        findings.push({
+            severity: 'warn',
+            rule: 'platform-domain-gap',
+            domain,
+            message: 'Declared on Android but not on iOS',
+            detail: 'The same link opens the app on Android and the browser on iOS',
+        });
+    }
+    for (const domain of ios.domains) {
+        if (!android.domains.has(domain))
+            continue;
+        const iosPaths = normalizeSet(ios.paths.get(domain) ?? []);
+        const androidPaths = normalizeSet(android.paths.get(domain) ?? []);
+        // Either side declaring nothing means "all paths", which is not a mismatch to report
+        if (iosPaths.size === 0 || androidPaths.size === 0)
+            continue;
+        const onlyIos = [...iosPaths].filter((p) => !androidPaths.has(p));
+        const onlyAndroid = [...androidPaths].filter((p) => !iosPaths.has(p));
+        if (onlyIos.length === 0 && onlyAndroid.length === 0)
+            continue;
+        findings.push({
+            severity: 'info',
+            rule: 'platform-path-gap',
+            domain,
+            message: 'The declared path sets differ between platforms',
+            detail: [
+                onlyIos.length ? `iOS only: ${onlyIos.join(', ')}` : '',
+                onlyAndroid.length ? `Android only: ${onlyAndroid.join(', ')}` : '',
+                'Path matching differs between the two systems, so review this by hand.',
+            ]
+                .filter(Boolean)
+                .join(' · '),
+        });
+    }
+    return findings;
+}

package/dist/rules/ios.js

@@ -0,0 +1,125 @@
+import { appIdMatches, parseAasa } from '../parse/aasa.js';
+/**
+ * Per-domain iOS checks. Each stage stops the chain when a later check could not
+ * possibly be meaningful — an unreachable AASA says nothing about its appIDs.
+ */
+export function checkIosDomain(app, domain, res) {
+    const findings = [];
+    const source = res.url;
+    if (res.error) {
+        findings.push({
+            severity: 'error',
+            rule: 'aasa-unreachable',
+            domain,
+            message: `Could not fetch the AASA file — ${res.error}`,
+            detail: 'Universal Links fall through to the browser',
+            source,
+        });
+        return { findings };
+    }
+    if (res.redirected) {
+        findings.push({
+            severity: 'error',
+            rule: 'aasa-redirect',
+            domain,
+            message: `AASA responded with ${res.status}${res.location ? ` → ${res.location}` : ''}`,
+            detail: 'iOS does not follow redirects when fetching an AASA file',
+            source,
+        });
+        return { findings };
+    }
+    if (!res.ok) {
+        findings.push({
+            severity: 'error',
+            rule: 'aasa-unreachable',
+            domain,
+            message: `AASA responded with ${res.status}`,
+            detail: 'Universal Links fall through to the browser',
+            source,
+        });
+        return { findings };
+    }
+    const { aasa, error } = parseAasa(res.body ?? '');
+    if (!aasa) {
+        findings.push({
+            severity: 'error',
+            rule: 'aasa-invalid',
+            domain,
+            message: `Could not parse the AASA file — ${error}`,
+            source,
+        });
+        return { findings };
+    }
+    if (res.contentType && !res.contentType.includes('application/json')) {
+        findings.push({
+            severity: 'warn',
+            rule: 'aasa-content-type',
+            domain,
+            message: `content-type is ${res.contentType}`,
+            detail: 'application/json is recommended',
+            source,
+        });
+    }
+    const declaredAppIds = aasa.details.flatMap((d) => d.appIds);
+    if (declaredAppIds.length === 0) {
+        findings.push({
+            severity: 'error',
+            rule: 'aasa-no-appids',
+            domain,
+            message: 'The AASA file declares no appIDs',
+            source,
+        });
+    }
+    else if (app.teamId && app.bundleId) {
+        const matched = declaredAppIds.some((id) => appIdMatches(id, app.teamId, app.bundleId));
+        if (!matched) {
+            findings.push({
+                severity: 'error',
+                rule: 'aasa-appid-missing',
+                domain,
+                message: `The AASA file does not list ${app.teamId}.${app.bundleId}`,
+                detail: `Declared appIDs: ${declaredAppIds.join(', ')}`,
+                source,
+            });
+        }
+    }
+    else {
+        findings.push({
+            severity: 'info',
+            rule: 'appid-unknown',
+            domain,
+            message: 'Skipped the appID check — could not determine the Team ID or bundle ID',
+            detail: 'The pbxproj value may be an xcconfig variable',
+            source: app.entitlementsPath,
+        });
+    }
+    const allEmpty = aasa.details.length > 0 &&
+        aasa.details.every((d) => (d.paths?.length ?? 0) === 0 && (d.components?.length ?? 0) === 0);
+    if (allEmpty) {
+        findings.push({
+            severity: 'info',
+            rule: 'aasa-no-paths',
+            domain,
+            message: 'The AASA file declares no paths or components',
+            detail: 'Depending on the format this opens every path in the app, or none of them',
+            source,
+        });
+    }
+    return { findings, aasa };
+}
+/** Flatten the legacy `paths` and current `components` forms into comparable strings. */
+export function aasaPaths(aasa) {
+    const paths = new Set();
+    for (const detail of aasa.details) {
+        for (const path of detail.paths ?? [])
+            paths.add(path);
+        for (const component of detail.components ?? []) {
+            if (!component || typeof component !== 'object')
+                continue;
+            const value = component['/'];
+            if (typeof value === 'string')
+                paths.add(value);
+        }
+    }
+    return [...paths];
+}

package/dist/rules/wildcard.js

@@ -0,0 +1,18 @@
+/**
+ * `applinks:*.example.com` (and the Android equivalent) is a valid declaration, but
+ * there is no host to fetch: the well-known file has to exist on each concrete
+ * subdomain, and we cannot enumerate those from the repo.
+ */
+export function isWildcardDomain(domain) {
+    return domain.startsWith('*.');
+}
+export function wildcardFinding(domain, source) {
+    return {
+        severity: 'info',
+        rule: 'wildcard-domain',
+        domain,
+        message: 'Wildcard domain — skipped',
+        detail: 'Every concrete subdomain must serve its own well-known file. Pass one explicitly to check it.',
+        source,
+    };
+}

package/dist/run.js

@@ -0,0 +1,57 @@
+import { discoverAndroid } from './discover/android.js';
+import { discoverIos } from './discover/ios.js';
+import { checkAndroidHost, checkAndroidUnresolved } from './rules/android.js';
+import { checkCrossPlatform } from './rules/cross.js';
+import { aasaPaths, checkIosDomain } from './rules/ios.js';
+import { isWildcardDomain, wildcardFinding } from './rules/wildcard.js';
+function emptyView() {
+    return { domains: new Set(), paths: new Map() };
+}
+export async function run({ root, source, sha256 }) {
+    const [iosApps, androidApps] = await Promise.all([discoverIos(root), discoverAndroid(root)]);
+    const findings = [];
+    const ios = emptyView();
+    const android = emptyView();
+    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));
+        fresh.forEach((d) => ios.domains.add(d));
+        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)));
+        pending.forEach((domain, i) => {
+            const { findings: domainFindings, aasa } = checkIosDomain(app, domain, results[i]);
+            findings.push(...domainFindings);
+            if (aasa)
+                ios.paths.set(domain, aasaPaths(aasa));
+        });
+    }
+    for (const app of androidApps) {
+        findings.push(...checkAndroidUnresolved(app));
+        const fresh = app.hosts.filter((h) => !android.domains.has(h.host));
+        fresh.forEach((h) => {
+            android.domains.add(h.host);
+            if (h.paths.length > 0)
+                android.paths.set(h.host, h.paths);
+        });
+        fresh
+            .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))));
+        pending.forEach((entry, i) => {
+            const res = results[i] ?? { url: '', ok: false, redirected: false };
+            findings.push(...checkAndroidHost(app, entry, res, { sha256 }));
+        });
+    }
+    findings.push(...checkCrossPlatform(ios, android));
+    return {
+        iosApps,
+        androidApps,
+        domains: [...new Set([...ios.domains, ...android.domains])],
+        findings,
+    };
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "deeplink-parity",
+  "version": "0.1.0",
+  "description": "Checks that what your mobile app declares about deep links matches what is actually hosted — across iOS and Android.",
+  "type": "module",
+  "bin": {
+    "deeplink-parity": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "tsx src/cli.ts",
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test tests/*.test.ts",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "keywords": [
+    "deeplink",
+    "universal-links",
+    "app-links",
+    "apple-app-site-association",
+    "assetlinks",
+    "ios",
+    "android"
+  ],
+  "author": "Hosung Kang (https://github.com/camosss)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/camosss/deeplink-parity.git"
+  },
+  "homepage": "https://github.com/camosss/deeplink-parity#readme",
+  "bugs": {
+    "url": "https://github.com/camosss/deeplink-parity/issues"
+  },
+  "dependencies": {
+    "fast-xml-parser": "^5.10.1",
+    "plist": "^3.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "@types/plist": "^3.0.5",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}