Deep Links skill for Claude Code

#!/usr/bin/env python3
"""Validate apple-app-site-association and assetlinks.json (stdlib only).

Live check (fetches https://DOMAIN/.well-known/... and refuses redirects, like the OS does):
  python3 check_association_files.py --domain example.com \
      [--app-id ABCDE12345.com.acme.app] [--package com.acme.app] \
      [--fingerprint AA:BB:...] [--path /orders/42 --path /account] [--apple-cdn]

Offline check of local files:
  python3 check_association_files.py --aasa-file aasa.json --assetlinks-file assetlinks.json [same options]

--apple-cdn also fetches Apple's cached copy (what devices actually receive).
Exit 1 on validation errors, 2 on network/usage errors.
"""
import argparse
import fnmatch
import json
import re
import sys
import urllib.error
import urllib.request

APP_ID_RE = re.compile(r"^[A-Z0-9]{10}\.[A-Za-z0-9.\-*]+$")
FP_RE = re.compile(r"^([0-9A-F]{2}:){31}[0-9A-F]{2}$")
HANDLE_ALL = "delegate_permission/common.handle_all_urls"
errors, warnings, infos = [], [], []
network_failures = []


class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        raise urllib.error.HTTPError(req.full_url, code, f"redirect to {newurl} (not allowed)", headers, fp)


def fetch(url):
    opener = urllib.request.build_opener(NoRedirect)
    req = urllib.request.Request(url, headers={"User-Agent": "association-check/1.0"})
    try:
        with opener.open(req, timeout=15) as r:
            body = r.read()
            return r.status, r.headers.get("Content-Type", ""), body
    except urllib.error.HTTPError as e:
        errors.append(f"{url}: HTTP {e.code} {e.reason}")
    except (urllib.error.URLError, TimeoutError) as e:
        network_failures.append(f"{url}: {e}")
    return None, None, None


def parse_json(label, body):
    try:
        return json.loads(body)
    except (ValueError, UnicodeDecodeError) as e:
        errors.append(f"{label}: invalid JSON ({e})")
        return None


def component_matches(comp, path, query, fragment):
    def m(pattern, value):
        return fnmatch.fnmatchcase(value, pattern) if comp.get("caseSensitive", True) \
            else fnmatch.fnmatchcase(value.lower(), pattern.lower())
    if "/" in comp and not m(comp["/"], path):
        return False
    q = comp.get("?")
    if isinstance(q, str) and not m(q, query):
        return False
    if isinstance(q, dict):
        params = dict(p.split("=", 1) if "=" in p else (p, "") for p in query.split("&") if p)
        for k, pat in q.items():
            if k not in params or not m(pat, params[k]):
                return False
    if "#" in comp and not m(comp["#"], fragment):
        return False
    return True


def check_aasa(data, app_id, paths):
    if not isinstance(data, dict):
        errors.append("AASA: top level must be an object"); return
    applinks = data.get("applinks")
    if not isinstance(applinks, dict):
        errors.append("AASA: missing 'applinks' object"); return
    details = applinks.get("details")
    if not isinstance(details, list) or not details:
        errors.append("AASA: applinks.details must be a non-empty array"); return
    found_app = False
    for i, d in enumerate(details):
        ids = d.get("appIDs") or ([d["appID"]] if "appID" in d else [])
        if "appID" in d:
            warnings.append(f"AASA details[{i}]: legacy 'appID'/'paths' format; prefer 'appIDs' + 'components' (iOS 13+)")
        if not ids:
            errors.append(f"AASA details[{i}]: no appIDs")
        for a in ids:
            if not APP_ID_RE.match(a):
                errors.append(f"AASA details[{i}]: '{a}' is not TEAMID.bundle.id (10-char uppercase Team ID)")
        comps = d.get("components")
        if comps is None and "paths" not in d:
            errors.append(f"AASA details[{i}]: needs 'components' (or legacy 'paths')")
        for j, c in enumerate(comps or []):
            if not isinstance(c, dict):
                errors.append(f"AASA details[{i}].components[{j}] must be an object"); continue
            for k in c:
                if k not in ("/", "?", "#", "exclude", "comment", "caseSensitive", "percentEncoded"):
                    warnings.append(f"AASA details[{i}].components[{j}]: unknown key '{k}'")
            if "/" in c and not str(c["/"]).startswith(("/", "*")):
                errors.append(f"AASA details[{i}].components[{j}]: path pattern must start with '/'")
        if app_id and app_id in ids:
            found_app = True
            for p in paths:
                path, _, rest = p.partition("?")
                query, _, frag = rest.partition("#")
                if "#" in path:
                    path, _, frag = path.partition("#")
                verdict = "no rule matched -> opens in browser"
                for c in comps or []:
                    if component_matches(c, path, query, frag):
                        verdict = "EXCLUDED -> opens in browser" if c.get("exclude") else "opens app"
                        break
                infos.append(f"AASA path {p}: {verdict}")
    if app_id and not found_app:
        errors.append(f"AASA: app ID {app_id} not listed in any applinks.details entry")
    wc = data.get("webcredentials", {}).get("apps") if isinstance(data.get("webcredentials"), dict) else None
    if wc is not None and app_id and app_id not in wc:
        warnings.append(f"AASA: webcredentials present but {app_id} not listed (password autofill association)")


def check_assetlinks(data, package, fingerprint):
    if not isinstance(data, list):
        errors.append("assetlinks: top level must be an array of statements"); return
    matched_pkg = False
    for i, s in enumerate(data):
        rel, tgt = s.get("relation", []), s.get("target", {})
        if tgt.get("namespace") != "android_app":
            continue
        if HANDLE_ALL not in rel:
            warnings.append(f"assetlinks[{i}]: relation lacks {HANDLE_ALL} (needed for App Links)")
        fps = tgt.get("sha256_cert_fingerprints", [])
        if not fps:
            errors.append(f"assetlinks[{i}]: no sha256_cert_fingerprints")
        for fp in fps:
            if not FP_RE.match(fp):
                errors.append(f"assetlinks[{i}]: fingerprint '{fp}' must be 32 uppercase hex bytes separated by colons")
        if package and tgt.get("package_name") == package:
            matched_pkg = True
            if fingerprint and fingerprint.upper() not in [f.upper() for f in fps]:
                errors.append(f"assetlinks: {package} found but fingerprint {fingerprint} missing "
                              "(with Play App Signing use the app signing key from Play Console)")
    if package and not matched_pkg:
        errors.append(f"assetlinks: no android_app statement for package {package}")


def main():
    ap = argparse.ArgumentParser(description="Validate AASA and assetlinks.json")
    ap.add_argument("--domain")
    ap.add_argument("--aasa-file")
    ap.add_argument("--assetlinks-file")
    ap.add_argument("--app-id", help="TEAMID.bundle.id")
    ap.add_argument("--package", help="Android applicationId")
    ap.add_argument("--fingerprint", help="SHA-256 signing cert fingerprint AA:BB:...")
    ap.add_argument("--path", action="append", default=[], help="URL path to test against AASA rules (repeatable)")
    ap.add_argument("--apple-cdn", action="store_true", help="also fetch Apple's CDN copy")
    args = ap.parse_args()
    if not (args.domain or args.aasa_file or args.assetlinks_file):
        ap.print_usage(sys.stderr); return 2

    if args.aasa_file:
        with open(args.aasa_file, "rb") as fh:
            d = parse_json("AASA", fh.read())
        if d is not None:
            check_aasa(d, args.app_id, args.path)
    elif args.domain:
        url = f"https://{args.domain}/.well-known/apple-app-site-association"
        status, ctype, body = fetch(url)
        if body is not None:
            if "json" not in (ctype or ""):
                warnings.append(f"AASA served as '{ctype}'; serve application/json")
            if len(body) > 128 * 1024:
                errors.append(f"AASA is {len(body)} bytes; Apple's limit is 128 KB")
            d = parse_json("AASA", body)
            if d is not None:
                check_aasa(d, args.app_id, args.path)
        if args.apple_cdn:
            cdn = f"https://app-site-association.cdn-apple.com/a/v1/{args.domain}"
            _, _, cbody = fetch(cdn)
            if cbody is not None and body is not None:
                same = parse_json("AASA (Apple CDN)", cbody) == parse_json("AASA", body)
                (infos if same else warnings).append(
                    "Apple CDN copy matches origin" if same else "Apple CDN copy differs from origin (CDN cache not refreshed yet)")

    if args.assetlinks_file:
        with open(args.assetlinks_file, "rb") as fh:
            d = parse_json("assetlinks", fh.read())
        if d is not None:
            check_assetlinks(d, args.package, args.fingerprint)
    elif args.domain and (args.package or args.fingerprint or not args.app_id):
        url = f"https://{args.domain}/.well-known/assetlinks.json"
        status, ctype, body = fetch(url)
        if body is not None:
            if "json" not in (ctype or ""):
                warnings.append(f"assetlinks.json served as '{ctype}'; serve application/json")
            d = parse_json("assetlinks", body)
            if d is not None:
                check_assetlinks(d, args.package, args.fingerprint)

    for i in infos:
        print(f"INFO  {i}")
    for w in warnings:
        print(f"WARN  {w}")
    for e in errors:
        print(f"ERROR {e}")
    for n in network_failures:
        print(f"NETWORK {n}")
    print(f"{len(errors)} error(s), {len(warnings)} warning(s), {len(network_failures)} network failure(s)")
    if errors:
        return 1
    return 2 if network_failures else 0


if __name__ == "__main__":
    sys.exit(main())