feat(pilotctl): one-command install + canonical catalogue.json + live smoke test (#235)

Closes the new-user gap: instead of "find a bundle tarball, untar it,
pass the path to install", a user runs:

    pilotctl appstore catalogue
    pilotctl appstore install io.pilot.wallet

and the tool fetches the bundle from the URL pinned in the
catalogue, sha-checks it, extracts it, and hands it to the existing
install path (which validates the manifest + verifies the embedded
ed25519 signature). The supervisor's rescan picks it up within 2 s.

## What ships

- catalogue/catalogue.json — the canonical list of installable apps.
  Schema-versioned (catalogue.version=1). Pilotctl refuses unknown
  versions so a future migration can't silently misbehave on old
  pilotctl binaries. Each entry pins bundle_url + bundle_sha256.
- catalogue/README.md — schema + how-to-publish-a-new-version doc.
- cmd/pilotctl/appstore_catalogue.go — loads catalogue from
  $PILOT_APPSTORE_CATALOG_URL (override), default the raw GitHub URL
  for catalogue/catalogue.json on main. Supports file://, https://,
  and http:// on loopback only (refuses plaintext install artifacts
  from anywhere else).
- cmd/pilotctl/appstore.go — install accepts a catalogue ID
  alongside the existing bundle-dir path; catalogue / catalog
  subcommand dispatches to the new lister.

## Chain of trust

  User trusts pilotctl (release-pipeline-signed binary).
  pilotctl fetches catalogue from a URL hardcoded in the binary
    (auditable in the public repo). Future: signed catalogue
    verified against appstore.EmbeddedCatalogPubkey.
  Catalogue pins each bundle's sha256 — a compromised CDN can't
    substitute different bytes (mismatch errors out).
  Bundle's manifest has an ed25519 signature against an embedded
    publisher pubkey; supervisor verifies at install + every rescan.

Defence-in-depth: tarball-unpack refuses any entry with "../" path
traversal, mirroring the supervisor's manifest.binary.path guard.

## Live smoke test

scripts/smoke-test-appstore.sh runs the entire flow end-to-end
against HEAD: builds pilotctl + daemon + wallet, gen-key, sign,
stage a catalogue pointing at the local tarball, start the daemon
(which loads the app-store unconditionally per #PR_1), list +
install by ID, daemon spawns it, run a 50 USDC payment between two
wallet processes, verify replay-guard, uninstall, verify clean. Eight
steps, each with explicit assertions.

scripts/smoke-pay-driver — the wallet-side IPC client. Notably does
NOT import the wallet package; talks to any installed app over raw
ipc.Call with map[string]any payloads. Proves the appstore stays
dynamic: a third-party tool needs no compile-time knowledge of the
app to drive its exposed methods.

Co-authored-by: Teodor Calin <teodor@vulturelabs.io>

Author: TeoSlayer

catalogue/README.md

@@ -0,0 +1,76 @@
+# Pilot app store catalogue
+
+This directory holds `catalogue.json` — the canonical list of apps installable via
+`pilotctl appstore install <app-id>`.
+
+## Schema
+
+```json
+{
+  "version": 1,
+  "updated_at": "<RFC3339 timestamp>",
+  "apps": [
+    {
+      "id": "<reverse-DNS app id, must match manifest.id>",
+      "version": "<semver>",
+      "description": "<one-line, shown in `pilotctl appstore catalogue`>",
+      "bundle_url": "https://<host>/<path>.tar.gz",
+      "bundle_sha256": "<hex sha256 of the tarball>"
+    }
+  ]
+}
+```
+
+The schema is intentionally flat — `pilotctl` decodes it directly into
+`catalogueEntry` in `cmd/pilotctl/appstore_catalogue.go`. Any field added
+here must also land there.
+
+## Where pilotctl loads it from
+
+By default, `pilotctl appstore catalogue` and `pilotctl appstore install
+<id>` fetch this file from the URL hardcoded in `appstore_catalogue.go`
+(`defaultCatalogueURL`, pointing at this file's raw URL on `main`). Override
+with `PILOT_APPSTORE_CATALOG_URL` for local dev or for staging a release:
+
+```bash
+# point at a local file while staging a release
+export PILOT_APPSTORE_CATALOG_URL=file:///path/to/staging/catalogue.json
+pilotctl appstore catalogue
+```
+
+`http://` is rejected unless the host is loopback (no plaintext install
+from a remote — operators relying on a catalogue do so over `https` only).
+
+## Publishing a new app version
+
+1. Bump the version in the app's `manifest.json`. Re-sign:
+   ```bash
+   pilotctl appstore sign --key /secure/path/publisher.key path/to/manifest.json
+   ```
+2. Build the bundle dir (`manifest.json` + `bin/<name>`) and tar it:
+   ```bash
+   tar czf io.pilot.wallet-X.Y.Z.tar.gz manifest.json bin/wallet
+   ```
+3. Compute the sha256:
+   ```bash
+   shasum -a 256 io.pilot.wallet-X.Y.Z.tar.gz
+   ```
+4. Upload the tarball as a release artifact (`gh release upload` or
+   equivalent — GitHub releases, Cloudflare R2, anywhere reachable over
+   HTTPS).
+5. Update this `catalogue.json` with the new `version`, `bundle_url`, and
+   `bundle_sha256`. Commit. The change goes live the moment the commit
+   lands on `main` and the raw URL serves the new bytes — no daemon
+   restart, no pilotctl release.
+
+## Trust model
+
+| Layer | Trust anchor | Verifies |
+|---|---|---|
+| User trusts pilotctl | Project release pipeline (signed pilotctl binary) | The catalogue URL is correct |
+| pilotctl trusts the catalogue | Future: signed against `EmbeddedCatalogPubkey`; today: the raw URL itself | App IDs map to specific bundle URLs + SHAs |
+| pilotctl trusts the bundle | Embedded `bundle_sha256` matches downloaded bytes | A CDN substitute is rejected |
+| Daemon trusts the manifest | Embedded ed25519 publisher pubkey verifies the signature | The bundle's manifest hasn't been tampered with |
+
+Every layer is checked at install time, and the manifest signature is
+re-verified at every supervisor rescan (every 2 s).

catalogue/catalogue.json

@@ -0,0 +1,13 @@
+{
+  "version": 1,
+  "updated_at": "2026-06-08T10:25:00Z",
+  "apps": [
+    {
+      "id": "io.pilot.wallet",
+      "version": "0.3.0",
+      "description": "On-overlay USDC payments — ed25519 + EIP-3009 receipts.",
+      "bundle_url": "https://github.com/TeoSlayer/pilotprotocol/releases/download/wallet-v0.3.0/io.pilot.wallet-0.3.0.tar.gz",
+      "bundle_sha256": "REPLACE_AT_RELEASE_TIME"
+    }
+  ]
+}

cmd/pilotctl/appstore.go

@@ -67,6 +67,8 @@ func cmdAppStore(args []string) {
 		cmdAppStoreGenKey(args[1:])
 	case "sign":
 		cmdAppStoreSign(args[1:])
+	case "catalogue", "catalog":
+		cmdAppStoreCatalogue(args[1:])
 	case "restart":
 		cmdAppStoreRestart(args[1:])
 	case "caps":
@@ -77,7 +79,7 @@ func cmdAppStore(args []string) {
 		appStoreHelp()
 	default:
 		fatalHint("invalid_argument",
-			"available: list, status, audit, uninstall, verify, install, gen-key, sign, restart, caps, actions, call",
+			"available: list, status, audit, uninstall, verify, install, gen-key, sign, catalogue, restart, caps, actions, call",
 			"unknown appstore subcommand: %s", args[0])
 	}
 }
@@ -99,8 +101,10 @@ Usage:
                                              duration: Go syntax (e.g. 10m, 1h, 24h)
   pilotctl appstore uninstall <id> --yes     remove an installed app from the install root
   pilotctl appstore verify <bundle-dir>      sha256-check a pre-install bundle against its manifest
-  pilotctl appstore install <bundle-dir> [--force]
-                                             stage + atomically place a verified bundle into the install root
+  pilotctl appstore catalogue                list apps available for one-command install
+  pilotctl appstore install <app-id-or-dir> [--force]
+                                             install by catalogue ID (fetches + verifies + extracts)
+                                             OR by local bundle directory (offline / dev path)
   pilotctl appstore gen-key <key-file>       generate a fresh ed25519 publisher keypair; prints the public side
   pilotctl appstore sign --key <key-file> <manifest>
                                              sign (or re-sign) a manifest's store.signature so the supervisor accepts it
@@ -967,10 +971,10 @@ type installReport struct {
 func cmdAppStoreInstall(args []string) {
 	if len(args) < 1 {
 		fatalHint("invalid_argument",
-			"usage: pilotctl appstore install <bundle-dir> [--force]",
-			"missing bundle dir")
+			"usage: pilotctl appstore install <app-id-or-dir> [--force]",
+			"missing app id or bundle dir")
 	}
-	bundleDir := args[0]
+	target := args[0]
 	force := false
 	for i := 1; i < len(args); i++ {
 		switch args[i] {
@@ -983,6 +987,17 @@ func cmdAppStoreInstall(args []string) {
 		}
 	}
 
+	// Resolve `target` to a local bundle dir. If it's a catalogue ID
+	// (e.g. "io.pilot.wallet"), fetch + verify the tarball and unpack
+	// into a tempdir. If it's already a directory, use it as-is. The
+	// rest of this function operates only on the directory.
+	bundleDir, err := resolveInstallTarget(target)
+	if err != nil {
+		fatalHint("invalid_argument",
+			"the argument must be either a catalogue ID (`pilotctl appstore catalogue` to list) or a path to a bundle dir containing manifest.json",
+			"%v", err)
+	}
+
 	// 1. Validate the bundle — same shape as verify. Reusing the
 	//    surface manifest.Parse + sha256File makes the trust check
 	//    identical to what the supervisor runs at every spawn.