@openparachute/hub 0.5.14-rc.2 → 0.5.14-rc.21

package/src/api-revoke-token.ts

@@ -1,38 +1,73 @@
 /**
  * `POST /api/auth/revoke-token` — HTTP companion to `parachute auth
- * revoke-token <jti>` (hub#221) and the missing piece behind the future
- * admin UI's revoke action.
+ * revoke-token <jti>` (hub#221) and the backing endpoint for the admin
+ * UI's revoke action. Closes hub#220.
  *
- * Same auth shape as `POST /api/auth/mint-token`: bearer-gated on
- * `parachute:host:auth` (admin scope-set tokens carry it as a superset;
- * narrow `--scope-set auth` operator tokens carry it directly). Closes
- * hub#220.
+ * Auth — capability attenuation, SYMMETRIC to mint-token (hub#452): you may
+ * revoke exactly what you could have minted. After validating the bearer
+ * (signature / issuer / expiry — same as today):
+ *
+ *   1. If the bearer holds `parachute:host:auth` → it may revoke ANY jti
+ *      (the original, broadest behavior — preserved unchanged).
+ *   2. Otherwise the bearer must clear the entry gate — it must hold at least
+ *      one minting authority (`parachute:host:auth`, `parachute:host:admin`,
+ *      or some `vault:<*>:admin`, via `hasMintingAuthority`). A bearer with
+ *      none (e.g. a read-only token) gets 403 up front — it can revoke
+ *      nothing, just as it can mint nothing.
+ *   3. The per-jti authority check then governs what such a bearer may
+ *      actually revoke: the target jti is revocable iff EVERY one of its
+ *      recorded scopes satisfies `canGrant(bearerScopes, scope)` — i.e. the
+ *      bearer could have minted that exact token. A `vault:work:admin` bearer
+ *      can revoke a `vault:work:write` or `vault:work:admin` jti, but NOT a
+ *      `vault:other:*` jti and NOT a `parachute:host:*` jti — the same
+ *      cross-vault / host-escalation walls mint enforces.
+ *
+ * Idempotency / no-info-leak: an UNKNOWN jti (no `tokens` row — never minted
+ * or already purged) returns the SAME 404 `not_found` the endpoint has always
+ * returned, for every caller including host:auth. The per-jti authority check
+ * only runs when the row is FOUND. So an attenuated bearer probing a jti it
+ * doesn't own cannot distinguish "exists but not yours" from "doesn't exist"
+ * by the unknown-jti path — it gets the identical 404 a host:auth bearer
+ * would. A jti that EXISTS but is out of the bearer's authority returns 403
+ * (and is NOT revoked): the caller already knows the jti string, so "exists
+ * but not yours" leaks nothing beyond what it already holds — and returning
+ * idempotent-ok there would be a lie (it revoked nothing).
  *
  * Body: `{ jti: string }`.
  *
- * Responses (matching the OAuth 2.0 error-shape vocabulary used by
- * mint-token and the rest of the hub's bearer-protected admin API):
+ * Responses (OAuth 2.0 error-shape vocabulary, matching mint-token):
  *
  *   - 200 `{ jti, revoked_at }` — success. Idempotent: re-revoking an
- *     already-revoked jti returns the existing `revoked_at` and 200,
- *     same as the CLI's exit-0-with-existing-timestamp behavior.
+ *     already-revoked jti returns the existing `revoked_at` and 200.
  *   - 400 `invalid_request` — missing/malformed body, missing jti.
  *   - 401 `unauthenticated` — missing or invalid bearer.
- *   - 403 `insufficient_scope` — bearer lacks `parachute:host:auth`.
+ *   - 403 `insufficient_scope` — bearer holds no minting authority (entry
+ *     gate), or the target jti carries a scope the bearer couldn't have
+ *     minted (per-jti authority check).
  *   - 404 `not_found` — no `tokens` row matches the jti.
  *   - 405 `method_not_allowed` — non-POST.
  *
  * Identity field in audit-friendly success: not echoed in the response
  * body (the JSON shape is intentionally minimal — `jti` + `revoked_at`
  * is all a UI consumer needs); operator-side audit lives in hub logs.
- * Mirrors the CLI's design where `identity=` was added for stdout but
- * the wire response stays narrow.
  */
 import type { Database } from "bun:sqlite";
 import { findTokenRowByJti, revokeTokenByJti, validateAccessToken } from "./jwt-sign.ts";
+import { MINT_HOST_AUTH_SCOPE, canGrant, hasMintingAuthority } from "./scope-attenuation.ts";
 
-/** Scope required on the bearer token to call this endpoint. */
-export const API_REVOKE_TOKEN_REQUIRED_SCOPE = "parachute:host:auth";
+/**
+ * Scope that authorises revoking ANY jti unconditionally (rule 1). A bearer
+ * without it may still revoke via attenuation (rule 3) if it clears the
+ * `hasMintingAuthority` entry gate.
+ */
+export const API_REVOKE_TOKEN_REQUIRED_SCOPE = MINT_HOST_AUTH_SCOPE;
+
+/**
+ * Maximum accepted length of a caller-supplied `jti`. A real jti is a UUID or
+ * short opaque token; anything materially longer is malformed input. Capping
+ * it keeps the verbatim-echoed value out of structured logs from bloating.
+ */
+export const MAX_JTI_LENGTH = 256;
 
 export interface ApiRevokeTokenDeps {
   db: Database;
@@ -80,12 +115,19 @@ export async function handleApiRevokeToken(
     return jsonError(401, "unauthenticated", `bearer token invalid — ${msg}`);
   }
 
-  // 3. Scope gate.
-  if (!bearerScopes.includes(API_REVOKE_TOKEN_REQUIRED_SCOPE)) {
+  // 3. Entry gate. A `parachute:host:auth` bearer may revoke anything
+  //    (rule 1) and skips the per-jti authority check below. Any other
+  //    bearer must hold SOME minting authority (host:admin or a
+  //    `vault:<*>:admin`) to attempt a revoke at all — a bearer with none
+  //    can revoke nothing under attenuation, so we 403 it here rather than
+  //    looking up the jti. Whether such a bearer may revoke a SPECIFIC jti
+  //    is decided per-jti in step 5 via `canGrant`.
+  const bearerHasHostAuth = bearerScopes.includes(API_REVOKE_TOKEN_REQUIRED_SCOPE);
+  if (!bearerHasHostAuth && !hasMintingAuthority(bearerScopes)) {
     return jsonError(
       403,
       "insufficient_scope",
-      `bearer token lacks ${API_REVOKE_TOKEN_REQUIRED_SCOPE}`,
+      `bearer token holds no revoke authority (need ${API_REVOKE_TOKEN_REQUIRED_SCOPE}, parachute:host:admin, or vault:<name>:admin)`,
     );
   }
 
@@ -103,15 +145,59 @@ export async function handleApiRevokeToken(
   if (typeof body.jti !== "string" || body.jti.length === 0) {
     return jsonError(400, "invalid_request", "jti is required and must be a non-empty string");
   }
+  // Cap the jti length. It's echoed verbatim into `error_description` and
+  // structured log lines; a real jti is a UUID/short token (well under 256
+  // chars), so a longer value is malformed input — reject it before it can
+  // bloat log lines. JSON-encoded responses already neutralize injection;
+  // this is a size guard, not an escaping one.
+  if (body.jti.length > MAX_JTI_LENGTH) {
+    return jsonError(400, "invalid_request", `jti exceeds ${MAX_JTI_LENGTH}-character maximum`);
+  }
   const jti = body.jti;
 
-  // 5. Lookup + revoke. Order: row-existence first (404 if missing), then
-  // attempt revoke. Idempotent: if already revoked, surface the existing
-  // revoked_at — same CLI semantics from hub#221.
+  // 5. Lookup + per-jti authority + revoke. Order: row-existence first
+  // (404 if missing — same response for every caller, no leak), then the
+  // attenuation authority check (for non-host:auth bearers), then attempt
+  // revoke. Idempotent: if already revoked, surface the existing revoked_at
+  // — same CLI semantics from hub#221.
   const existing = findTokenRowByJti(deps.db, jti);
   if (!existing) {
     return jsonError(404, "not_found", `no token with jti ${jti} found in registry`);
   }
+
+  // Per-jti authority (rule 3 / symmetric to mint attenuation). A host:auth
+  // bearer skips this — it may revoke anything. Any other bearer may revoke
+  // this jti only if EVERY one of its recorded scopes is one the bearer could
+  // have minted (`canGrant`). One out-of-authority scope (cross-vault, a
+  // host:* scope, etc.) blocks the whole revoke with 403 — and the token is
+  // left intact. The caller already knows the jti, so "exists but not yours"
+  // leaks nothing beyond what it holds; idempotent-ok would falsely imply a
+  // revoke happened.
+  if (!bearerHasHostAuth) {
+    // A scopeless target (recorded `scopes: []`) would otherwise pass the
+    // `canGrant` filter vacuously — `[].filter(...)` is empty, so
+    // `ungrantable.length === 0`. That's silently permissive: any bearer
+    // clearing the entry gate could revoke a zero-scope token. Such tokens
+    // shouldn't exist (the CLI/SPA never mint them), but if one does, only a
+    // host:auth bearer may revoke it — a non-host:auth bearer has no
+    // attenuation authority that "covers" the empty scope set.
+    if (existing.scopes.length === 0) {
+      return jsonError(
+        403,
+        "insufficient_scope",
+        `bearer token cannot revoke jti ${jti}: target has no recorded scopes (only ${API_REVOKE_TOKEN_REQUIRED_SCOPE} may revoke a scopeless token)`,
+      );
+    }
+    const ungrantable = existing.scopes.filter((s) => !canGrant(bearerScopes, s));
+    if (ungrantable.length > 0) {
+      return jsonError(
+        403,
+        "insufficient_scope",
+        `bearer token cannot revoke jti ${jti}: its scope(s) ${ungrantable.join(", ")} are outside the bearer's authority`,
+      );
+    }
+  }
+
   if (existing.revokedAt) {
     return ok({ jti, revoked_at: existing.revokedAt });
   }

package/src/api-users.ts

@@ -336,7 +336,16 @@ export async function handleCreateUser(req: Request, deps: ApiUsersDeps): Promis
   }
 }
 
-/** DELETE /api/users/:id — hard-delete + token revocation + session/grant cleanup. */
+/**
+ * DELETE /api/users/:id — hard-delete + token revocation + session/grant
+ * cleanup.
+ *
+ * Success returns `200 { ok: true, revocation_lag_seconds: 60 }` (was a bare
+ * 204 pre-consistency-fix) so the SPA can warn that the deleted user's
+ * tokens linger ~60s on resource-server revocation caches — same surface
+ * the reset-password path carries. The race-tolerant "row already gone"
+ * path stays a bodyless 204 (nothing was revoked here, no lag to report).
+ */
 export async function handleDeleteUser(
   req: Request,
   userId: string,
@@ -390,11 +399,28 @@ export async function handleDeleteUser(
   if (!removed) {
     // Race: row deleted by a concurrent request. Operator's intent
     // (no such user) is already satisfied — same shape as the grant-
-    // revoke race in `admin-grants.ts`.
+    // revoke race in `admin-grants.ts`. No tokens were revoked by THIS
+    // call, so there's no revocation lag to warn about; keep the bodyless
+    // 204 for the race path.
     return new Response(null, { status: 204 });
   }
   console.log(`user deleted: id=${userId} username=${target.username}`);
-  return new Response(null, { status: 204 });
+  // `revocation_lag_seconds`: same consistency fix the reset-password path
+  // got (smoke 2026-05-27 finding 3). Deleting a user revokes their tokens
+  // in hub's DB immediately, but resource servers (vault, scribe, …) cache
+  // the revocation list via scope-guard's `REVOCATION_CACHE_TTL_MS = 60_000`
+  // — a deleted user's tokens linger for up to ~60s on those caches. Surface
+  // that so the admin isn't surprised when a just-deleted user's client can
+  // still read for a minute (relevant in the stolen-device / compromise
+  // threat model). 200 + body instead of the old bare 204 so the SPA can
+  // render the warning banner.
+  return new Response(
+    JSON.stringify({ ok: true, revocation_lag_seconds: REVOCATION_LAG_SECONDS }),
+    {
+      status: 200,
+      headers: { "content-type": "application/json", "cache-control": "no-store" },
+    },
+  );
 }
 
 /**

package/src/cli.ts

@@ -6,10 +6,12 @@
  * Run `parachute --help` or `parachute <subcommand> --help` for usage.
  */
 
+import { MissingDependencyError } from "@openparachute/depcheck";
 import pkg from "../package.json" with { type: "json" };
 import { CloudflaredStateError } from "./cloudflare/state.ts";
 import { auth } from "./commands/auth.ts";
 import { exposePublic, exposeTailnet } from "./commands/expose.ts";
+import { init } from "./commands/init.ts";
 import { install } from "./commands/install.ts";
 import { logs, restart, start, stop } from "./commands/lifecycle.ts";
 import { migrate } from "./commands/migrate.ts";
@@ -18,15 +20,18 @@ import { setup } from "./commands/setup.ts";
 import { status } from "./commands/status.ts";
 import { upgrade } from "./commands/upgrade.ts";
 import { dispatchVault } from "./commands/vault.ts";
+import { runSetupWizardCommand } from "./commands/wizard.ts";
 import { ExposeStateError } from "./expose-state.ts";
 import {
   exposeHelp,
+  initHelp,
   installHelp,
   logsHelp,
   migrateHelp,
   restartHelp,
   serveHelp,
   setupHelp,
+  setupWizardHelp,
   startHelp,
   statusHelp,
   stopHelp,
@@ -305,6 +310,76 @@ async function main(argv: string[]): Promise<number> {
       return await setup(setupOpts);
     }
 
+    case "setup-wizard": {
+      // hub#168 Cut 3 — the in-terminal mirror of /admin/setup. Distinct
+      // from `parachute setup` (which is the multi-pick install
+      // walk-through, not a wizard-handler frontend). Both surfaces stay
+      // — `parachute setup` is the historical "install + configure
+      // services" entry; `parachute setup-wizard` drives the same
+      // handlers the browser wizard uses.
+      if (isHelpFlag(rest[0])) {
+        console.log(setupWizardHelp());
+        return 0;
+      }
+      return await runSetupWizardCommand(rest);
+    }
+
+    case "init": {
+      if (isHelpFlag(rest[0])) {
+        console.log(initHelp());
+        return 0;
+      }
+      const exposeExtract = extractNamedFlag(rest, "--expose");
+      if (exposeExtract.error) {
+        console.error(`parachute init: ${exposeExtract.error}`);
+        return 1;
+      }
+      if (
+        exposeExtract.value !== undefined &&
+        exposeExtract.value !== "none" &&
+        exposeExtract.value !== "tailnet" &&
+        exposeExtract.value !== "cloudflare"
+      ) {
+        console.error(
+          `parachute init: --expose must be one of none|tailnet|cloudflare (got "${exposeExtract.value}")`,
+        );
+        return 1;
+      }
+      const noBrowser = exposeExtract.rest.includes("--no-browser");
+      const noExposePrompt = exposeExtract.rest.includes("--no-expose-prompt");
+      const cliWizard = exposeExtract.rest.includes("--cli-wizard");
+      const browserWizard = exposeExtract.rest.includes("--browser-wizard");
+      const known = new Set([
+        "--no-browser",
+        "--no-expose-prompt",
+        "--cli-wizard",
+        "--browser-wizard",
+      ]);
+      const unknown = exposeExtract.rest.find((a) => !known.has(a));
+      if (unknown !== undefined) {
+        console.error(`parachute init: unknown argument "${unknown}"`);
+        console.error(
+          "usage: parachute init [--no-browser] [--no-expose-prompt]\n" +
+            "                     [--expose none|tailnet|cloudflare]\n" +
+            "                     [--cli-wizard | --browser-wizard]",
+        );
+        return 1;
+      }
+      if (cliWizard && browserWizard) {
+        console.error("parachute init: --cli-wizard and --browser-wizard are mutually exclusive.");
+        return 1;
+      }
+      const initOpts: Parameters<typeof init>[0] = {};
+      if (noBrowser) initOpts.noBrowser = true;
+      if (noExposePrompt) initOpts.noExposePrompt = true;
+      if (exposeExtract.value) {
+        initOpts.exposeChoice = exposeExtract.value as "none" | "tailnet" | "cloudflare";
+      }
+      if (cliWizard) initOpts.wizardChoice = "cli";
+      else if (browserWizard) initOpts.wizardChoice = "browser";
+      return await init(initOpts);
+    }
+
     case "install": {
       if (isHelpFlag(rest[0])) {
         console.log(installHelp());
@@ -398,12 +473,21 @@ async function main(argv: string[]): Promise<number> {
         return 1;
       }
       const exposeArgs = flagExtract.rest;
-      const layer = exposeArgs[0];
+      let layer = exposeArgs[0];
       const mode = exposeArgs[1];
       if (isHelpFlag(layer)) {
         console.log(exposeHelp());
         return 0;
       }
+      // Alias: `parachute expose cloudflare [--domain X] [off]` is shorthand for
+      // `parachute expose public --cloudflare …`. Cloudflare is a public-internet
+      // provider, so we rewrite the layer to `public` and force the cloudflare
+      // flag — the rest of the dispatch (domain prompt, off-path, etc.) is
+      // identical to the canonical form.
+      if (layer === "cloudflare") {
+        layer = "public";
+        flagExtract.cloudflare = true;
+      }
       if (layer !== "tailnet" && layer !== "public") {
         console.error(`parachute expose: unknown layer "${layer ?? ""}"`);
         console.error("usage: parachute expose tailnet [off]");
@@ -627,14 +711,17 @@ async function main(argv: string[]): Promise<number> {
         return 0;
       }
       const dryRun = rest.includes("--dry-run");
+      const list = rest.includes("--list");
       const yes = rest.includes("--yes") || rest.includes("-y");
-      const unknown = rest.find((a) => a !== "--dry-run" && a !== "--yes" && a !== "-y");
+      const unknown = rest.find(
+        (a) => a !== "--dry-run" && a !== "--list" && a !== "--yes" && a !== "-y",
+      );
       if (unknown !== undefined) {
         console.error(`parachute migrate: unknown argument "${unknown}"`);
-        console.error("usage: parachute migrate [--dry-run] [--yes]");
+        console.error("usage: parachute migrate [--list] [--dry-run] [--yes]");
         return 1;
       }
-      return await migrate({ dryRun, yes });
+      return await migrate({ dryRun, list, yes });
     }
 
     case "serve": {
@@ -672,32 +759,24 @@ async function main(argv: string[]): Promise<number> {
       // after `vault` (including --help) is passed through verbatim.
       if (rest.length === 0) return await dispatchVault(["--help"]);
 
-      // `parachute vault tokens create` in a TTY with no scope-narrowing flag
-      // → guided flow. Any of --scope / --read / --permission means the user
-      // has already decided, so we stay out of the way. Non-TTY always
-      // bypasses (no way to answer a prompt). Label is orthogonal — the
-      // guided flow prompts for it only if --label wasn't supplied.
-      const wantsGuidedTokenCreate =
-        rest[0] === "tokens" &&
-        rest[1] === "create" &&
-        isTtyInteractive() &&
-        !rest.includes("--scope") &&
-        !rest.includes("--read") &&
-        !rest.includes("--permission") &&
-        !isHelpFlag(rest[2]);
-      if (wantsGuidedTokenCreate) {
-        const { runVaultTokensCreateInteractive } = await import(
-          "./commands/vault-tokens-create-interactive.ts"
-        );
-        return await runVaultTokensCreateInteractive({ args: rest.slice(2) });
-      }
-
+      // Everything under `vault` forwards transparently to `parachute-vault`.
+      // `vault tokens create` used to route through a guided interactive
+      // wrapper, but the pvt_* DROP (vault#412 / hub#466) removed that vault
+      // subcommand — it now exits 1 with migration guidance. Access tokens are
+      // hub-issued JWTs; mint them with `parachute auth mint-token` or the
+      // admin SPA Connect card. We forward verbatim so the operator sees
+      // vault's own migration error rather than a hub-side stub.
       return await dispatchVault(rest);
     }
 
     default:
       console.error(`parachute: unknown command "${command}"`);
-      console.error("run `parachute --help` for usage");
+      console.error("");
+      console.error("If this is a fresh install, start here:");
+      console.error("  parachute init        # get the admin wizard going");
+      console.error("");
+      console.error("Or see all commands:");
+      console.error("  parachute --help");
       return 1;
   }
 }
@@ -706,6 +785,14 @@ async function run(argv: string[]): Promise<number> {
   try {
     return await main(argv);
   } catch (err) {
+    if (err instanceof MissingDependencyError) {
+      // A required external binary wasn't on PATH (git / tailscale / tail /
+      // …). Print the friendly install block to stderr. interactive:true so
+      // the operator at a terminal sees the "ask your sysadmin" trailer; the
+      // message was already formatted at construction, so we just emit it.
+      console.error(err.message);
+      return 1;
+    }
     if (err instanceof ServicesManifestError) {
       console.error(`services.json is malformed: ${err.message}`);
       console.error("Fix or remove the file, then re-run.");

package/src/clients.ts

@@ -12,12 +12,24 @@
  *     plaintext exactly once. The token endpoint enforces client_secret per
  *     RFC 6749 §3.2.1 (closes #72).
  *
- * Approval gate (closes #74): every row carries a `status` of `pending` or
- * `approved`. New self-registrations default to `pending`; only registrations
- * that authenticate with an operator token bearing `hub:admin` (the install-
- * time path for first-party modules) land as `approved`. The OAuth flow
- * rejects `pending` clients at `/oauth/authorize` and `/oauth/token`. An
- * operator promotes a pending client via `parachute auth approve-client`.
+ * Status column (`pending` | `approved`): every row carries one. New
+ * self-registrations default to `pending`; registrations that authenticate
+ * with an operator token bearing `hub:admin` (the install-time path for
+ * first-party modules) land as `approved`.
+ *
+ * Single-consent change (2026-05-29): the separate operator "approve this
+ * client" gate was retired. The user's OAuth consent IS the authorization —
+ * `handleAuthorizeGet` now session-gates a `pending` client: a request
+ * carrying a valid session auto-approves the client (status → `approved`,
+ * audit-logged) and FALLS THROUGH to the normal consent screen; a session-
+ * less request still renders the unauth "App not yet approved" page whose
+ * sign-in CTA round-trips back to authorize (after login the user re-enters
+ * with a session → auto-approve → consent). The `status` column, the DCR
+ * `pending` default, the `/oauth/token` pending rejection, and the
+ * `parachute auth approve-client` / SPA approve surfaces all persist but are
+ * near-vestigial — kept for defense-in-depth and back-compat. Motivation:
+ * Notes/Claude DCR a fresh `client_id` per instance, so a per-client_id
+ * approval gate re-prompted the operator constantly.
  */
 import type { Database } from "bun:sqlite";
 import { createHash, randomBytes, randomUUID } from "node:crypto";

package/src/cloudflare/config.ts

@@ -2,8 +2,6 @@ import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { CONFIG_DIR } from "../config.ts";
 
-export const CLOUDFLARED_DIR = join(CONFIG_DIR, "cloudflared");
-
 export const DEFAULT_TUNNEL_NAME = "parachute";
 
 /**
@@ -16,12 +14,20 @@ export const DEFAULT_TUNNEL_NAME = "parachute";
  * location change from pre-#32 (`~/.parachute/cloudflared/config.yml`).
  * Re-running `parachute expose public --cloudflare` regenerates the file
  * at the new path; the legacy file is left in place but unused.
+ *
+ * `configDir` overrides the base (`~/.parachute` by default). Tests pass a
+ * tmp dir so per-tunnel-derived paths never resolve against the operator's
+ * real `CONFIG_DIR` — otherwise running the suite scribbles fixture
+ * config.yml + log files into `~/.parachute/cloudflared/<name>/`.
  */
-export function cloudflaredPathsFor(tunnelName: string): {
+export function cloudflaredPathsFor(
+  tunnelName: string,
+  configDir: string = CONFIG_DIR,
+): {
   configPath: string;
   logPath: string;
 } {
-  const dir = join(CLOUDFLARED_DIR, tunnelName);
+  const dir = join(configDir, "cloudflared", tunnelName);
   return {
     configPath: join(dir, "config.yml"),
     logPath: join(dir, "cloudflared.log"),

package/src/cloudflare/detect.ts

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { isBinaryNotFoundError, lookupDep } from "@openparachute/depcheck";
 import type { Runner } from "../tailscale/run.ts";
 
 export const DEFAULT_CLOUDFLARED_HOME = join(homedir(), ".cloudflared");
@@ -10,30 +11,22 @@ export const DEFAULT_CLOUDFLARED_HOME = join(homedir(), ".cloudflared");
  * "binary not on PATH" errors — anything else (EACCES from a non-executable
  * file, corrupted binary, etc.) propagates so we don't silently report
  * "not installed" when something more specific is wrong.
+ *
+ * The not-found matcher is `@openparachute/depcheck`'s `isBinaryNotFoundError`
+ * — the single source of truth across the ecosystem (this used to be a local
+ * copy that drifted from vault's `git-preflight.ts`). Pass the binary name so
+ * a not-found message about an unrelated file isn't mis-attributed.
  */
 export async function isCloudflaredInstalled(runner: Runner): Promise<boolean> {
   try {
     const { code } = await runner(["cloudflared", "--version"]);
     return code === 0;
   } catch (err) {
-    if (isBinaryNotFoundError(err)) return false;
+    if (isBinaryNotFoundError(err, "cloudflared")) return false;
     throw err;
   }
 }
 
-function isBinaryNotFoundError(err: unknown): boolean {
-  if (!err || typeof err !== "object") return false;
-  const e = err as { code?: unknown; message?: unknown };
-  if (e.code === "ENOENT") return true;
-  // Bun.spawn's error shape varies across versions; fall back to message
-  // string matching so we catch "Executable not found in $PATH" and
-  // "ENOENT" variants without pinning to one runtime detail.
-  if (typeof e.message === "string") {
-    return /ENOENT|not found|No such file/i.test(e.message);
-  }
-  return false;
-}
-
 /**
  * `cloudflared tunnel login` drops a cert at `~/.cloudflared/cert.pem` — its
  * presence is cloudflared's own login marker. Every `cloudflared tunnel
@@ -45,14 +38,83 @@ export function isCloudflaredLoggedIn(cloudflaredHome: string = DEFAULT_CLOUDFLA
   return existsSync(join(cloudflaredHome, "cert.pem"));
 }
 
-export function cloudflaredInstallHint(platform: NodeJS.Platform = process.platform): string {
-  const url =
-    "https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/";
+/**
+ * Cloudflare's "Downloads" page (developers.cloudflare.com/cloudflare-one/
+ * connections/connect-networks/downloads/) churns markdown anchors; pkg.cloudflare.com
+ * paths the older instructions referenced now serve HTML / 404. Aaron hit
+ * the failure mode on a fresh Amazon Linux 2023 EC2 install (2026-05-27):
+ * `sudo dnf install cloudflared` returned 'No match for argument:
+ * cloudflared'. The reliable cross-distro path is grabbing the static
+ * binary from Cloudflare's GitHub releases.
+ *
+ * Canonical install paths:
+ *
+ *   macOS  → `brew install cloudflared` (homebrew is the documented path)
+ *   Linux  → architecture-specific binary from GitHub releases
+ *   other  → the binary-download path is still the best generic answer
+ *
+ * The `arch` parameter is the architecture string in `process.arch`
+ * shape (`x64`, `arm64`, `arm`). The static-binary curl recipe + the arch
+ * mapping now live in `@openparachute/depcheck`'s `cloudflared` registry
+ * entry (`install.linuxBinaryUrl`) — the single source of truth shared with
+ * the structured `MissingDependencyError` UX. This function keeps its own
+ * prose (the surrounding "works across distros" framing the expose flow
+ * prints) but derives the URL + arch support from the registry so the two
+ * can't drift. A `undefined` recipe (arch with no published artifact) is the
+ * signal to fall through to the generic releases pointer rather than
+ * fabricating a 404-bound URL.
+ */
+export function cloudflaredInstallHint(
+  platform: NodeJS.Platform = process.platform,
+  arch: NodeJS.Architecture = process.arch,
+): string {
+  const releasesUrl = "https://github.com/cloudflare/cloudflared/releases/latest";
   if (platform === "darwin") {
-    return `Install cloudflared:\n  brew install cloudflared\n(or see ${url})`;
+    return [
+      "Install cloudflared:",
+      "  brew install cloudflared",
+      "",
+      "(or download a static binary from",
+      `  ${releasesUrl})`,
+    ].join("\n");
   }
   if (platform === "linux") {
-    return `Install cloudflared: ${url}`;
+    const downloadUrl = cloudflaredLinuxDownloadUrl(arch);
+    if (downloadUrl) {
+      return [
+        "Install cloudflared (static binary — works across distros):",
+        "  curl -L -o /usr/local/bin/cloudflared \\",
+        `    ${downloadUrl}`,
+        "  sudo chmod +x /usr/local/bin/cloudflared",
+        "  cloudflared --version",
+        "",
+        "(distro packages are unreliable across versions; the GitHub release is the canonical path.)",
+      ].join("\n");
+    }
+    return [
+      "Install cloudflared from the official binary release:",
+      `  ${releasesUrl}`,
+      `(pick the linux-* artifact matching your architecture; your arch is "${arch}")`,
+    ].join("\n");
   }
-  return `Install cloudflared: ${url}`;
+  return ["Install cloudflared from the official binary release:", `  ${releasesUrl}`].join("\n");
+}
+
+/**
+ * Pull the cloudflared-linux-<suffix> download URL for an arch out of the
+ * depcheck registry's static-binary recipe. The registry recipe is a
+ * multi-line `curl … / chmod … / version` block; we extract the single
+ * `https://…/cloudflared-linux-<suffix>` line so this function's own prose
+ * wraps the canonical URL. Returns undefined when the arch has no published
+ * artifact (registry recipe is undefined) — the caller then uses the generic
+ * pointer. Keeps the arch→suffix mapping in exactly one place (the registry).
+ */
+function cloudflaredLinuxDownloadUrl(arch: NodeJS.Architecture): string | undefined {
+  const recipe = lookupDep("cloudflared")?.install.linuxBinaryUrl?.(arch);
+  if (!recipe) return undefined;
+  const urlLine = recipe
+    .split("\n")
+    .map((l) => l.trim())
+    .find((l) => l.startsWith("https://"));
+  return urlLine;
 }