maccrab:// URL scheme

This page specifies the URL contract between rave.maccrab.com/ and the MacCrab app. Any link of the form maccrab://<host>/<path>?<query> is a deep link into the app; clicking one on the rave site (or anywhere else) opens MacCrab and routes to the right place.

The scheme exists so the catalog can do “Install” with one click instead of asking operators to copy-paste a CLI command. The fallback when the app isn’t installed is to surface the copy-command UI on the same plugin page.

Status

The site emits these URLs today. Plugin detail pages always show the copy-clipboard maccrabctl plugin install <id> flow as well, so installation works whether or not your MacCrab build handles the maccrab:// scheme.

This doc is the contract the platform-side handler must implement.

URL forms

Install a single plugin

maccrab://install/plugin/<plugin-id>?version=<semver>&catalog=<base-url>

App behaviour:

1. Switch to the Catalog tab.
2. Open the plugin detail panel for <plugin-id>.
3. Present the install confirmation sheet (capability summary + publisher key fingerprint + version).
4. On confirm → run the same install path as maccrabctl plugin install <plugin-id> (HTTP catalog-fetch + verify + install).

Install a kit

maccrab://install/kit/<kit-id>?version=<semver>&catalog=<base-url>

Same shape as plugins. App expands the kit, prompts once with the union of all bundled plugins’ capability summaries, then installs each.

Open a plugin detail (no install)

maccrab://open/plugin/<plugin-id>
maccrab://open/kit/<kit-id>

Used when the rave site wants to deep-link operators to a plugin they already have installed — opens the Catalog tab focused on that entry.

Open the catalog tab

maccrab://open/catalog
maccrab://open/catalog?category=<cat>
maccrab://open/catalog?search=<query>

Pre-filters the in-app catalog browser. Useful for editorial links from rave.maccrab.com/ (“see all collectors” → maccrab://open/catalog?category=collector).

Security expectations

Deep-link URLs must NOT bypass the existing trust gates:

1. Capability confirmation is still required. Install URLs always present the standard capability sheet; they never trigger silent installs.
2. Publisher key check is still required. A revoked publisher key still refuses install. A previously-trusted key still gets the existing “auto-install for trusted publishers” UX choice; the URL doesn’t change that.
3. Catalog signature check is still required. Even with a custom catalog= override, the catalog at that URL must be Ed25519-signed by the bundled catalog public key (or, for enterprise mirrors, a key registered via the enterprise mirror docs).

The URL is a UX accelerator, not a security bypass.

Web side — how the rave site emits these

Plugin detail pages render an <a href="maccrab://install/plugin/<id>">Install</a> button next to the copy-clipboard fallback. The button is always visible; if MacCrab is installed the OS routes the click into the app. If nothing handles the scheme, plugin-detail.js detects that the page never backgrounded and surfaces the copy-command — focusing and highlighting it with a “MacCrab not detected” note — so the click always has a working outcome.

For mirror operators, the install button can be re-pointed by setting a per-deployment build var that rewrites the URL’s catalog= parameter to the mirror URL.

Reverse direction — outbound from app to web

The app emits one URL into the web side: the homepage https://rave.maccrab.com/ opens when the operator clicks the “Browse on the web” affordance in the Catalog tab footer. No deep-link from the app to a specific web page is planned.