Mobile Deep Links skill for Codex

Gives the Codex app a display name, a one-line description and a starter prompt for this skill.

interface:
  display_name: "Mobile Deep Links"
  short_description: "Links that open the app, not the browser"
  default_prompt: "$mobile-deep-links Our universal links open Safari instead of the app, figure out why"

#!/usr/bin/env python3
"""Validate iOS apple-app-site-association and Android assetlinks.json files.

Usage:
  python3 check_link_files.py aasa  <path-or-https-url> [--app-id TEAMID.bundle.id]
  python3 check_link_files.py assetlinks <path-or-https-url> [--package com.example] [--sha256 AA:BB:...]

Given an https URL, the file is fetched without following redirects (both platforms
reject redirected association files) and the status and Content-Type are checked.
Fetching needs network access. Exits 0 when no errors are found, 1 otherwise.
"""
import argparse
import json
import re
import sys
import urllib.error
import urllib.request

errors: list[str] = []
warnings: list[str] = []

APP_ID = re.compile(r"^[A-Z0-9]{10}\.[A-Za-z0-9.\-]+$")
FINGERPRINT = re.compile(r"^([0-9A-F]{2}:){31}[0-9A-F]{2}$")
PACKAGE = re.compile(r"^[a-zA-Z][a-zA-Z0-9_]*(\.[a-zA-Z][a-zA-Z0-9_]*)+$")


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}", headers, fp)


def load(source: str):
    if not source.startswith(("http://", "https://")):
        with open(source, "rb") as fh:
            raw = fh.read()
    else:
        if source.startswith("http://"):
            errors.append("association files must be served over https")
        opener = urllib.request.build_opener(NoRedirect)
        req = urllib.request.Request(source, headers={"User-Agent": "link-file-check/1.0"})
        try:
            with opener.open(req, timeout=15) as resp:
                ctype = resp.headers.get("Content-Type", "")
                if "application/json" not in ctype:
                    errors.append(f"Content-Type is '{ctype}', expected application/json")
                raw = resp.read()
        except urllib.error.HTTPError as exc:
            errors.append(f"HTTP {exc.code} for {source}: {exc.reason}")
            return None
        except urllib.error.URLError as exc:
            errors.append(f"could not fetch {source}: {exc.reason}")
            return None
    if len(raw) > 128 * 1024:
        errors.append(f"file is {len(raw)} bytes; Apple rejects AASA files over 128 KB")
    try:
        return json.loads(raw.decode("utf-8"))
    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
        errors.append(f"not valid UTF-8 JSON: {exc}")
        return None


def check_aasa(data, want_app_id):
    applinks = data.get("applinks") if isinstance(data, dict) else None
    if not isinstance(applinks, dict):
        errors.append("missing top-level 'applinks' object")
        return
    details = applinks.get("details")
    if not isinstance(details, list) or not details:
        errors.append("'applinks.details' must be a non-empty array")
        return
    if "apps" in applinks:
        warnings.append("'applinks.apps' is a legacy key and can be removed")
    seen_ids = set()
    for i, entry in enumerate(details):
        ids = entry.get("appIDs") or ([entry["appID"]] if "appID" in entry else [])
        if "appID" in entry:
            warnings.append(f"details[{i}] uses legacy 'appID'; prefer 'appIDs'")
        if not ids:
            errors.append(f"details[{i}] has no appIDs")
        for app_id in ids:
            if not APP_ID.match(app_id):
                errors.append(f"details[{i}] app ID '{app_id}' is not TEAMID.bundle.id")
            seen_ids.add(app_id)
        comps = entry.get("components")
        paths = entry.get("paths")
        if comps is None and paths is None:
            errors.append(f"details[{i}] has neither 'components' nor 'paths'")
        if paths is not None:
            warnings.append(f"details[{i}] uses legacy 'paths'; 'components' is the current format")
        for j, comp in enumerate(comps or []):
            if not isinstance(comp, dict):
                errors.append(f"details[{i}].components[{j}] must be an object")
                continue
            path = comp.get("/")
            if path is not None and not str(path).startswith(("/", "*", "?")):
                errors.append(f"details[{i}].components[{j}] path '{path}' should start with /")
            if comp.get("exclude") and j == len(comps) - 1 and len(comps) > 1:
                warnings.append(
                    f"details[{i}] ends with an exclude rule; rules match in order, so put excludes before broad includes"
                )
    if want_app_id and want_app_id not in seen_ids:
        errors.append(f"app ID {want_app_id} is not listed (found: {', '.join(sorted(seen_ids)) or 'none'})")


def check_assetlinks(data, want_package, want_sha):
    if not isinstance(data, list) or not data:
        errors.append("assetlinks.json must be a non-empty JSON array")
        return
    found = {}
    for i, stmt in enumerate(data):
        rel = stmt.get("relation", [])
        if "delegate_permission/common.handle_all_urls" not in rel:
            warnings.append(f"[{i}] lacks relation delegate_permission/common.handle_all_urls (no App Links)")
        target = stmt.get("target", {})
        if target.get("namespace") != "android_app":
            continue
        pkg = target.get("package_name", "")
        if not PACKAGE.match(pkg):
            errors.append(f"[{i}] package_name '{pkg}' is not a valid application ID")
        prints = target.get("sha256_cert_fingerprints", [])
        if not prints:
            errors.append(f"[{i}] has no sha256_cert_fingerprints")
        for fp in prints:
            if not FINGERPRINT.match(fp):
                errors.append(f"[{i}] fingerprint '{fp}' must be 32 uppercase hex bytes separated by colons")
        found.setdefault(pkg, set()).update(prints)
    if want_package:
        if want_package not in found:
            errors.append(f"package {want_package} not listed (found: {', '.join(sorted(found)) or 'none'})")
        elif want_sha and want_sha.upper() not in found[want_package]:
            errors.append(f"fingerprint {want_sha} not listed for {want_package}")
    for pkg, prints in found.items():
        if len(prints) == 1:
            warnings.append(
                f"{pkg} lists one fingerprint; with Play App Signing include the Play signing key (and debug/upload keys if those builds must verify)"
            )


def main() -> int:
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("kind", choices=["aasa", "assetlinks"])
    ap.add_argument("source", help="local file path or https URL")
    ap.add_argument("--app-id", help="expected TEAMID.bundle.id (aasa)")
    ap.add_argument("--package", help="expected Android application ID (assetlinks)")
    ap.add_argument("--sha256", help="expected signing certificate fingerprint (assetlinks)")
    args = ap.parse_args()

    data = load(args.source)
    if data is not None:
        if args.kind == "aasa":
            check_aasa(data, args.app_id)
        else:
            check_assetlinks(data, args.package, args.sha256)

    for w in warnings:
        print(f"WARN  {w}")
    for e in errors:
        print(f"ERROR {e}")
    print(f"{args.kind}: {len(errors)} error(s), {len(warnings)} warning(s)")
    return 1 if errors else 0


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