When Universal Links Break Silently — Catching Association Drift with an Agent-Run Verification Gate

The verifier that reconciles all three

Generating the files does not guarantee the server actually serves them correctly, or that they truly match the app's declaration. So build a check that fetches the published files and reconciles them with the definition. This is the body of both gates.

// verify-associations.mjs — fetch published files, confirm they match the definition
import { readFileSync } from "node:fs";
 
const cfg = JSON.parse(readFileSync("link-routes.json", "utf8"));
const base = `https://${cfg.domain}/.well-known`;
const problems = [];
 
async function fetchJson(url) {
  const res = await fetch(url, { redirect: "manual" });
  if (res.status !== 200) throw new Error(`HTTP ${res.status}`);
  const ct = res.headers.get("content-type") || "";
  if (!ct.includes("application/json")) {
    problems.push(`${url}: Content-Type is ${ct} (not application/json)`);
  }
  return JSON.parse(await res.text());
}
 
try {
  const aasa = await fetchJson(`${base}/apple-app-site-association`);
  const detail = aasa.applinks?.details?.[0];
  if (detail?.appID !== cfg.ios.appID) {
    problems.push(`AASA appID mismatch: published=${detail?.appID} defined=${cfg.ios.appID}`);
  }
  const publishedPaths = new Set(detail?.paths || []);
  for (const r of cfg.routes) {
    if (!publishedPaths.has(r.path)) problems.push(`AASA missing path: ${r.path}`);
  }
} catch (e) {
  problems.push(`AASA fetch failed: ${e.message}`);
}
 
try {
  const links = await fetchJson(`${base}/assetlinks.json`);
  const target = links[0]?.target;
  if (target?.package_name !== cfg.android.package) {
    problems.push(`assetlinks package mismatch: ${target?.package_name}`);
  }
  const fps = new Set((target?.sha256_cert_fingerprints || []).map((s) => s.toUpperCase()));
  for (const want of cfg.android.sha256) {
    if (!fps.has(want.toUpperCase())) problems.push(`assetlinks missing fingerprint: ${want.slice(0, 17)}...`);
  }
} catch (e) {
  problems.push(`assetlinks fetch failed: ${e.message}`);
}
 
if (problems.length) {
  console.error("Association drift detected:");
  for (const p of problems) console.error(`  - ${p}`);
  process.exit(1);
}
console.log("Associations match the definition");

If you can halt a release while this script returns exit 1, the app declaration and the published files never ship out of sync. In my own runs, adding the fingerprint check let me catch — ahead of time — the Android verification failure that tends to happen right after a Play App Signing certificate swap.

What to hand the agent, and how far

The verification itself is mechanical; the script handles it. Where an agent earns its keep is triage on failure and proposing the next move. But I keep irreversible actions — rewriting published files, changing domain settings — out of the agent's hands.

When you hand triage to an agent, pass the verifier's output verbatim — which path is missing, which fingerprint doesn't match — and cap it at three candidate causes. Let it guess broadly from an ambiguous prompt and it drifts toward plausible misdiagnoses, mistaking a CDN cache issue for a certificate problem. The tighter the constraint, the faster and more accurate the triage.

A two-stage gate: pre-release and weekly

Run the check at two moments. The pre-release gate runs the verifier just before you cut a release build and stops the build on failure. That secures the app declaration against the published files.

The second stage is a weekly unattended run. Published files break independently of your app releases. A domain move, a CDN configuration change, a certificate renewal — any of these can detach the association while you've touched nothing. So even on weeks with no release, something has to fetch the published files on a schedule and merely notify when they drift. Have Antigravity's CLI agent run the verifier weekly and leave a triage summary only when it returns exit 1; that catches the silent breakage within a few days.

What six weeks of running it taught me

I put this two-stage gate into a handful of my own wallpaper and calming apps and ran it for about six weeks. The measured results:

Both of the two cases I caught happened at moments unrelated to any release. One was a CDN cache setting that served a stale association file; the other was an assetlinks.json entry that hadn't kept up with a Play App Signing certificate renewal. Neither crashed, and both were the kind of failure I'd never have noticed if I'd left them alone.

If you're weighing where to start, begin with the weekly run of the verifier. You can add the generation step later, but building the ability to know it's broken first pays back more than the effort it costs. Links are assumed to just work, which is exactly why a silent detachment erodes trust so sharply. I'll be glad if it spares someone the same quiet half a day.