@openparachute/hub 0.3.0-rc.1

package/src/cloudflare/tunnel.ts

@@ -0,0 +1,135 @@
+import { join } from "node:path";
+import type { CommandResult, Runner } from "../tailscale/run.ts";
+
+export class CloudflaredError extends Error {
+  override name = "CloudflaredError";
+  constructor(
+    message: string,
+    public readonly cmd: readonly string[],
+    public readonly result: CommandResult,
+  ) {
+    super(message);
+  }
+}
+
+export interface Tunnel {
+  id: string;
+  name: string;
+  createdAt?: string;
+}
+
+function combineErrStreams(result: CommandResult): string {
+  const e = result.stderr.trim();
+  if (e.length > 0) return e;
+  return result.stdout.trim();
+}
+
+/**
+ * Parse `cloudflared tunnel list --output json`. The schema is stable: an
+ * array of objects each with `id` (UUID) and `name`. We ignore extra fields.
+ * Entries missing either id or name are skipped rather than thrown — keeps
+ * us forward-compatible with cloudflared adding new tunnel shapes.
+ */
+export async function listTunnels(runner: Runner): Promise<Tunnel[]> {
+  const cmd = ["cloudflared", "tunnel", "list", "--output", "json"];
+  const result = await runner(cmd);
+  if (result.code !== 0) {
+    throw new CloudflaredError(
+      `cloudflared tunnel list failed: ${combineErrStreams(result)}`,
+      cmd,
+      result,
+    );
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(result.stdout);
+  } catch (err) {
+    throw new CloudflaredError(
+      `failed to parse cloudflared tunnel list JSON: ${err instanceof Error ? err.message : String(err)}`,
+      cmd,
+      result,
+    );
+  }
+  if (!Array.isArray(parsed)) {
+    throw new CloudflaredError("cloudflared tunnel list did not return a JSON array", cmd, result);
+  }
+  const tunnels: Tunnel[] = [];
+  for (const raw of parsed) {
+    if (!raw || typeof raw !== "object") continue;
+    const r = raw as Record<string, unknown>;
+    const id = typeof r.id === "string" ? r.id : undefined;
+    const name = typeof r.name === "string" ? r.name : undefined;
+    if (!id || !name) continue;
+    const t: Tunnel = { id, name };
+    if (typeof r.created_at === "string") t.createdAt = r.created_at;
+    tunnels.push(t);
+  }
+  return tunnels;
+}
+
+export async function findTunnelByName(runner: Runner, name: string): Promise<Tunnel | undefined> {
+  const tunnels = await listTunnels(runner);
+  return tunnels.find((t) => t.name === name);
+}
+
+/**
+ * `cloudflared tunnel create <name>` writes credentials to
+ * `~/.cloudflared/<UUID>.json` and prints a line like
+ *
+ *   Created tunnel parachute with id 2c1a7c7e-…-b3ef7c1d9a2a
+ *
+ * We parse the UUID from stdout rather than requiring callers to walk the
+ * credentials dir afterward — less filesystem coupling, and the UUID format
+ * is stable (RFC 4122 lowercase hex).
+ */
+export async function createTunnel(runner: Runner, name: string): Promise<Tunnel> {
+  const cmd = ["cloudflared", "tunnel", "create", name];
+  const result = await runner(cmd);
+  if (result.code !== 0) {
+    throw new CloudflaredError(
+      `cloudflared tunnel create failed: ${combineErrStreams(result)}`,
+      cmd,
+      result,
+    );
+  }
+  const match = result.stdout.match(
+    /([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})/i,
+  );
+  if (!match) {
+    throw new CloudflaredError(
+      `could not parse tunnel UUID from cloudflared output: ${result.stdout.trim()}`,
+      cmd,
+      result,
+    );
+  }
+  return { id: match[1]!, name };
+}
+
+/**
+ * `--overwrite-dns` turns the route command into an idempotent UPSERT: without
+ * it, cloudflared exits non-zero when the CNAME already exists, which breaks
+ * every rerun on the same hostname (and the error surface — "add the domain to
+ * Cloudflare" — is actively wrong in that case). The destination is always the
+ * caller's tunnel, so overwriting a pre-existing CNAME that points somewhere
+ * else is the right move; the user explicitly asked for this hostname to
+ * reach this tunnel.
+ */
+export async function routeDns(
+  runner: Runner,
+  tunnelName: string,
+  hostname: string,
+): Promise<void> {
+  const cmd = ["cloudflared", "tunnel", "route", "dns", "--overwrite-dns", tunnelName, hostname];
+  const result = await runner(cmd);
+  if (result.code !== 0) {
+    throw new CloudflaredError(
+      `cloudflared tunnel route dns failed: ${combineErrStreams(result)}`,
+      cmd,
+      result,
+    );
+  }
+}
+
+export function credentialsPath(uuid: string, cloudflaredHome: string): string {
+  return join(cloudflaredHome, `${uuid}.json`);
+}

package/src/commands/auth.ts

@@ -0,0 +1,69 @@
+/**
+ * `parachute auth` — ecosystem-level identity commands.
+ *
+ * Identity (password + 2FA) is an ecosystem concern now that the hub owns
+ * OAuth issuance (Phase 0). The *implementation* still lives in
+ * parachute-vault — these commands are thin shell-forwards to the vault
+ * binary so beta users learn the blessed namespace from day one.
+ *
+ * Vault keeps its own `set-password` / `2fa` commands for back-compat.
+ */
+
+export interface Runner {
+  run(cmd: readonly string[]): Promise<number>;
+}
+
+export const defaultRunner: Runner = {
+  async run(cmd) {
+    const proc = Bun.spawn([...cmd], { stdio: ["inherit", "inherit", "inherit"] });
+    return await proc.exited;
+  },
+};
+
+const AUTH_SUBCOMMANDS = new Set(["set-password", "2fa"]);
+
+export function authHelp(): string {
+  return `parachute auth — ecosystem identity commands (password + two-factor authentication)
+
+Usage:
+  parachute auth set-password         Set or change the owner password
+  parachute auth set-password --clear Remove the owner password
+  parachute auth 2fa status           Show 2FA state
+  parachute auth 2fa enroll           Enable TOTP 2FA (QR + backup codes)
+  parachute auth 2fa disable          Disable 2FA (requires password)
+  parachute auth 2fa backup-codes     Regenerate backup codes
+
+All subcommands forward to \`parachute-vault\` which implements the storage
+and crypto. If you see "not found on PATH", install vault first:
+
+  parachute install vault
+`;
+}
+
+export async function auth(
+  args: readonly string[],
+  runner: Runner = defaultRunner,
+): Promise<number> {
+  const sub = args[0];
+  if (sub === undefined || sub === "--help" || sub === "-h" || sub === "help") {
+    console.log(authHelp());
+    return 0;
+  }
+  if (!AUTH_SUBCOMMANDS.has(sub)) {
+    console.error(`parachute auth: unknown subcommand "${sub}"`);
+    console.error("run `parachute auth --help` for usage");
+    return 1;
+  }
+  try {
+    return await runner.run(["parachute-vault", ...args]);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.toLowerCase().includes("enoent") || msg.toLowerCase().includes("not found")) {
+      console.error("parachute-vault not found on PATH.");
+      console.error("Install it with: parachute install vault");
+      return 127;
+    }
+    console.error(`failed to run parachute-vault: ${msg}`);
+    return 1;
+  }
+}

package/src/commands/expose-auth-preflight.ts

@@ -0,0 +1,217 @@
+/**
+ * Post-exposure auth nudge. Runs after `parachute expose public` successfully
+ * brings a tunnel up (TTY only). The tunnel is already live; this is purely
+ * advisory — we never error the exposure flow regardless of what the user
+ * chooses. The goal is to catch the "fresh vault, just went public, no
+ * password or tokens set" trap before someone else finds it first.
+ *
+ * Four states we branch on, based on {@link VaultAuthStatus}:
+ *
+ *   - neither password nor tokens: loud warning + offer to set up each.
+ *   - password, no 2FA: shorter "recommend 2FA" nudge.
+ *   - tokens but no password: OAuth isn't set up; offer to add a password.
+ *   - `tokenCount === null`: couldn't read the DB; advisory only, no prompts
+ *     that depend on token state.
+ *   - all set: one-line "looks good" (the quiet path).
+ *
+ * Defaults are always "skip" — Enter declines every prompt. User can always
+ * run `parachute auth …` or `parachute vault tokens create` later.
+ */
+
+import { createInterface } from "node:readline/promises";
+import { type VaultAuthStatus, readVaultAuthStatus } from "../vault/auth-status.ts";
+
+/** `Bun.spawn(..., { stdio: "inherit" })` wrapper. Factored out so tests can
+ *  assert which commands got invoked without running them. */
+export type InteractiveRunner = (cmd: readonly string[]) => Promise<number>;
+
+const defaultInteractiveRunner: InteractiveRunner = async (cmd) => {
+  const proc = Bun.spawn([...cmd], { stdio: ["inherit", "inherit", "inherit"] });
+  return await proc.exited;
+};
+
+async function defaultPrompt(question: string): Promise<string> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return await rl.question(question);
+  } finally {
+    rl.close();
+  }
+}
+
+export interface AuthPreflightOpts {
+  /** Supply a pre-computed status to skip the on-disk read (tests). In
+   *  production, leave unset and we'll call {@link readVaultAuthStatus}. */
+  status?: VaultAuthStatus;
+  prompt?: (question: string) => Promise<string>;
+  interactiveRunner?: InteractiveRunner;
+  log?: (line: string) => void;
+  /** Forwarded to {@link readVaultAuthStatus} when `status` is not supplied. */
+  vaultHome?: string;
+}
+
+interface Resolved {
+  status: VaultAuthStatus;
+  prompt: (question: string) => Promise<string>;
+  interactiveRunner: InteractiveRunner;
+  log: (line: string) => void;
+}
+
+function resolve(opts: AuthPreflightOpts): Resolved {
+  return {
+    status: opts.status ?? readVaultAuthStatus({ vaultHome: opts.vaultHome }),
+    prompt: opts.prompt ?? defaultPrompt,
+    interactiveRunner: opts.interactiveRunner ?? defaultInteractiveRunner,
+    log: opts.log ?? ((line) => console.log(line)),
+  };
+}
+
+/**
+ * Prompt the user yes/no with Enter defaulting to "no" (skip). Returns true
+ * only on an affirmative answer. Anything else — blank, "n", garbage — is a
+ * decline; we don't reprompt, because the preflight is explicitly optional
+ * and the user has already done the hard part.
+ */
+async function yesNo(r: Resolved, question: string): Promise<boolean> {
+  const raw = (await r.prompt(`${question} [y/N] `)).trim().toLowerCase();
+  return raw === "y" || raw === "yes";
+}
+
+async function runCmd(r: Resolved, cmd: readonly string[], friendly: string): Promise<void> {
+  r.log("");
+  const code = await r.interactiveRunner(cmd);
+  if (code !== 0) {
+    // Don't blow up the preflight on a sub-command failure — the user can
+    // see the error, and the tunnel is still up. Just log a hint and move on.
+    r.log(
+      `(${friendly} exited ${code} — you can re-run \`${cmd.join(" ")}\` anytime. Continuing.)`,
+    );
+  }
+}
+
+async function offerOwnerPassword(r: Resolved): Promise<void> {
+  if (await yesNo(r, "Set the owner password now?")) {
+    await runCmd(r, ["parachute", "auth", "set-password"], "parachute auth set-password");
+  }
+}
+
+async function offerTotp(r: Resolved): Promise<void> {
+  if (await yesNo(r, "Enable TOTP 2FA now?")) {
+    await runCmd(r, ["parachute", "auth", "2fa", "enroll"], "parachute auth 2fa enroll");
+  }
+}
+
+async function offerTokenCreate(r: Resolved): Promise<void> {
+  if (await yesNo(r, "Create an API token now?")) {
+    await runCmd(r, ["parachute", "vault", "tokens", "create"], "parachute vault tokens create");
+  }
+}
+
+function printDivider(r: Resolved): void {
+  r.log("");
+  r.log("──────────────────────────────────────────────────────────────");
+}
+
+/**
+ * `neither password nor tokens`: the exposure is wide open — anyone who
+ * finds the URL can talk to the vault. The loudest warning we draw.
+ */
+async function handleWideOpen(r: Resolved): Promise<void> {
+  printDivider(r);
+  r.log("⚠  No owner password and no API tokens are configured.");
+  r.log("   The tunnel is reachable from the public internet RIGHT NOW.");
+  r.log("   Anyone with the URL can make requests until you set auth up.");
+  r.log("");
+  r.log("Recommended: set an owner password (enables the browser sign-in flow)");
+  r.log("and/or create an API token (for programmatic clients).");
+  r.log("");
+  await offerOwnerPassword(r);
+  // Offer 2FA regardless of the password step outcome: we can't observe it
+  // from outside the subprocess, and vault itself will reject a 2fa enroll
+  // if there's no password yet, surfacing the real error to the user.
+  await offerTotp(r);
+  await offerTokenCreate(r);
+  printDivider(r);
+}
+
+/**
+ * `password set, no 2FA`: the common case where the user did the obvious
+ * thing but hasn't opted into the stronger factor yet. Short nudge.
+ */
+async function handlePasswordNoTotp(r: Resolved): Promise<void> {
+  r.log("");
+  r.log("✓  Owner password is set.");
+  r.log("   Consider also enabling 2FA for defense-in-depth.");
+  await offerTotp(r);
+}
+
+/**
+ * `tokens exist, no password`: vault is authenticated for API clients but
+ * nobody can sign in through a browser — the hub's OAuth flow is dead in
+ * the water. Offer to fix.
+ */
+async function handleTokensNoPassword(r: Resolved): Promise<void> {
+  r.log("");
+  r.log("ℹ  API tokens exist, but no owner password is set.");
+  r.log("   Browser sign-in (OAuth) won't work until you add one.");
+  await offerOwnerPassword(r);
+}
+
+/**
+ * `tokenCount === null`: SQLite probe failed (DB missing, locked, schema
+ * drift, whatever). Don't guess; don't prompt on token state. Nudge 2FA
+ * if we know the password is set, otherwise stay quiet.
+ */
+async function handleUnknownTokens(r: Resolved): Promise<void> {
+  r.log("");
+  r.log("ℹ  Couldn't read vault token state (vault may be locked or offline).");
+  r.log("   Run `parachute vault tokens list` to check token config yourself.");
+  if (r.status.hasOwnerPassword && !r.status.hasTotp) {
+    r.log("");
+    r.log("   (While you're here: owner password is set, 2FA is not.)");
+    await offerTotp(r);
+  }
+}
+
+/**
+ * `all set`: password + 2FA + at least one token. Keep it tight.
+ */
+function handleAllGood(r: Resolved): void {
+  r.log("");
+  r.log("✓  Auth config looks good (password + 2FA + API tokens).");
+}
+
+/**
+ * Pick the branch. Pure function of the status — keeps test coverage trivial.
+ */
+function classify(
+  s: VaultAuthStatus,
+): "wide-open" | "password-no-totp" | "tokens-no-password" | "unknown-tokens" | "all-good" {
+  if (s.tokenCount === null) return "unknown-tokens";
+  const hasTokens = s.tokenCount > 0;
+  if (!s.hasOwnerPassword && !hasTokens) return "wide-open";
+  if (!s.hasOwnerPassword && hasTokens) return "tokens-no-password";
+  if (s.hasOwnerPassword && !s.hasTotp) return "password-no-totp";
+  return "all-good";
+}
+
+export async function runAuthPreflight(opts: AuthPreflightOpts = {}): Promise<void> {
+  const r = resolve(opts);
+  switch (classify(r.status)) {
+    case "wide-open":
+      await handleWideOpen(r);
+      return;
+    case "password-no-totp":
+      await handlePasswordNoTotp(r);
+      return;
+    case "tokens-no-password":
+      await handleTokensNoPassword(r);
+      return;
+    case "unknown-tokens":
+      await handleUnknownTokens(r);
+      return;
+    case "all-good":
+      handleAllGood(r);
+      return;
+  }
+}