maslink

===

Forked from jaywcjlove/maslink, added config-free app lookup via iTunes Search API.

maslink is a tiny static redirect page for Apple App Store deep links.

GitHub README previews often strip custom protocols such as macappstore://, which makes direct Mac App Store links unclickable. This project provides a normal https:// URL that can be used in README files and then converted back into a native App Store deep link in the browser.

Security Model / Trust Boundary

maslink is a static redirect helper, not a package downloader, installer, update service, or dependency distribution channel.

What it does:

• Accept id, platform, and optional locale query parameters.
• Build an App Store deep link or Apple web fallback URL in the browser.
• Attempt a client-side redirect.

What it does not do:

• Download executable files, archives, or installers from GitHub or third-party servers.
• Inject third-party scripts, ads, trackers, or package manager dependencies.
• Proxy App Store traffic through a backend service.

Trust boundary:

• A user must trust the hosted maslink page to generate only the expected Apple App Store target URL.
• This means maslink introduces an additional redirect trust point compared with linking directly to an App Store URL.
• That risk is real, but it is different from a classic software supply-chain attack because this project does not ship runtime dependencies or distribute binaries.

Threats this project can help with:

• GitHub README stripping custom protocols such as macappstore://.
• Providing a clickable HTTPS entry point that still opens the App Store natively.

Threats this project does not solve:

• A compromised hosting account or repository changing the redirect target.
• DNS, CDN, or static hosting compromise.
• User trust decisions about whether the hosted redirect page operator is trustworthy.

Ways to reduce trust risk:

• Self-host the static page if you need full control over the redirect surface.
• Keep the project dependency-free and static.
• Keep redirect logic small and auditable.
• Restrict generated targets to Apple App Store deep links and Apple web fallback URLs only.

Use Case

Instead of linking to:

macappstore://itunes.apple.com/app/6768043307

link to:

https://maslink.hocgin.top/?id=6768043307&l=cn&platform=ios

When the page opens, it will:

1. Read the query parameters.
2. Build the correct App Store deep link.
3. Attempt to redirect automatically.
4. Show manual buttons for native open and web fallback.

Query Parameters

• id: Apple app ID, numeric only, required.
• l: Apple storefront/locale segment, optional. If omitted, the page will infer it from the browser language, then fall back to us.
• platform: Target platform, optional, default is mac.

Supported platform values:

• mac
• ios
• iphone
• ipad

Locale detection examples:

• zh-CN -> cn
• en-US -> us
• ja-JP -> jp
• If the browser language cannot be resolved, fallback is us

Generated Links

For macOS:

macappstore://itunes.apple.com/app/id<ID>?mt=12&l=<LOCALE>

For iOS:

itms-apps://itunes.apple.com/app/id<ID>?l=<LOCALE>

Web fallback:

https://apps.apple.com/<LOCALE>/app/id<ID>

Deploy

This repository is a plain static site.

To self-host it, deploy the contents of docs/ as static files:

• docs/index.html
• docs/data.json
• docs/appicon/*

Keep the relative file layout unchanged, and expose index.html at the site root or a subpath.

For GitHub Pages, set the publish folder to /docs.

Example:

https://YOUR-DOMAIN/PATH/?id=6768043307&platform=mac

Config-free Lookup

When an app ID is not found in the local data.json, this page automatically falls back to the iTunes Search API to fetch app name, icon, and platform info. No manual configuration required.

Lookup priority:

1. Local config (data.json)
2. Browser cache (localStorage, 7-day TTL)
3. iTunes Search API (https://itunes.apple.com/lookup?id=xxx)

Any API result is cached in localStorage so subsequent visits skip the network request.