@openparachute/hub 0.3.0-rc.1 → 0.5.1

package/src/cli.ts

@@ -13,7 +13,9 @@ import { exposePublic, exposeTailnet } from "./commands/expose.ts";
 import { install } from "./commands/install.ts";
 import { logs, restart, start, stop } from "./commands/lifecycle.ts";
 import { migrate } from "./commands/migrate.ts";
+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 { ExposeStateError } from "./expose-state.ts";
 import {
@@ -22,11 +24,14 @@ import {
   logsHelp,
   migrateHelp,
   restartHelp,
+  setupHelp,
   startHelp,
   statusHelp,
   stopHelp,
   topLevelHelp,
+  upgradeHelp,
 } from "./help.ts";
+import { HUB_SVC } from "./hub-control.ts";
 import { knownServices } from "./service-spec.ts";
 import { ServicesManifestError } from "./services-manifest.ts";
 import { TailscaleError } from "./tailscale/run.ts";
@@ -139,41 +144,124 @@ function extractNamedFlag(
 }
 
 /**
- * Extract the Cloudflare-mode flags from `parachute expose public …`:
- * `--cloudflare` (boolean) + `--domain=<host>` / `--domain <host>`. Returns
- * the stripped argv so the layer/action parser sees `[layer, action?]`
- * regardless of flag placement.
+ * Extract every `parachute expose …` provider flag in one pass:
+ *
+ *   --cloudflare              boolean — pin to Cloudflare Tunnel
+ *   --tailnet                 boolean — pin to Tailscale Funnel (#29)
+ *   --skip-provider-check     boolean — bypass auto-detection in non-TTY,
+ *                                       fall through to today's Tailscale
+ *                                       default (CI escape hatch, #29)
+ *   --domain=<host>           hostname for the Cloudflare path
+ *   --tunnel-name=<name>      named tunnel override (#32)
+ *
+ * Returns the stripped argv so the layer/action parser sees `[layer, action?]`
+ * regardless of flag placement. `--tailnet` + `--cloudflare` together is
+ * caller-rejected; this extractor doesn't enforce mutual exclusion so help-
+ * driven error messages can stay close to the dispatch site.
  */
-function extractCloudflareFlags(args: string[]): {
+function extractExposeProviderFlags(args: string[]): {
   cloudflare: boolean;
+  tailnet: boolean;
+  skipProviderCheck: boolean;
   domain?: string;
+  tunnelName?: string;
   rest: string[];
   error?: string;
 } {
   const rest: string[] = [];
   let cloudflare = false;
+  let tailnet = false;
+  let skipProviderCheck = false;
   let domain: string | undefined;
+  let tunnelName: string | undefined;
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
     if (a === "--cloudflare") {
       cloudflare = true;
       continue;
     }
+    if (a === "--tailnet" || a === "--tailscale") {
+      tailnet = true;
+      continue;
+    }
+    if (a === "--skip-provider-check") {
+      skipProviderCheck = true;
+      continue;
+    }
     if (a === "--domain") {
       const v = args[i + 1];
-      if (!v) return { cloudflare, rest, error: "--domain requires a hostname argument" };
+      if (!v) {
+        return {
+          cloudflare,
+          tailnet,
+          skipProviderCheck,
+          rest,
+          error: "--domain requires a hostname argument",
+        };
+      }
       domain = v;
       i++;
       continue;
     }
     if (a?.startsWith("--domain=")) {
       domain = a.slice("--domain=".length);
-      if (!domain) return { cloudflare, rest, error: "--domain requires a hostname argument" };
+      if (!domain) {
+        return {
+          cloudflare,
+          tailnet,
+          skipProviderCheck,
+          rest,
+          error: "--domain requires a hostname argument",
+        };
+      }
+      continue;
+    }
+    if (a === "--tunnel-name") {
+      const v = args[i + 1];
+      if (!v) {
+        return {
+          cloudflare,
+          tailnet,
+          skipProviderCheck,
+          rest,
+          error: "--tunnel-name requires a name argument",
+        };
+      }
+      tunnelName = v;
+      i++;
+      continue;
+    }
+    if (a?.startsWith("--tunnel-name=")) {
+      tunnelName = a.slice("--tunnel-name=".length);
+      if (!tunnelName) {
+        return {
+          cloudflare,
+          tailnet,
+          skipProviderCheck,
+          rest,
+          error: "--tunnel-name requires a name argument",
+        };
+      }
       continue;
     }
     if (a !== undefined) rest.push(a);
   }
-  return { cloudflare, domain, rest };
+  const out: {
+    cloudflare: boolean;
+    tailnet: boolean;
+    skipProviderCheck: boolean;
+    domain?: string;
+    tunnelName?: string;
+    rest: string[];
+  } = {
+    cloudflare,
+    tailnet,
+    skipProviderCheck,
+    rest,
+  };
+  if (domain !== undefined) out.domain = domain;
+  if (tunnelName !== undefined) out.tunnelName = tunnelName;
+  return out;
 }
 
 async function main(argv: string[]): Promise<number> {
@@ -192,6 +280,29 @@ async function main(argv: string[]): Promise<number> {
       console.log(pkg.version);
       return 0;
 
+    case "setup": {
+      if (isHelpFlag(rest[0])) {
+        console.log(setupHelp());
+        return 0;
+      }
+      const tagExtract = extractTag(rest);
+      if (tagExtract.error) {
+        console.error(`parachute setup: ${tagExtract.error}`);
+        return 1;
+      }
+      const noStart = tagExtract.rest.includes("--no-start");
+      const remaining = tagExtract.rest.filter((a) => a !== "--no-start");
+      if (remaining.length > 0) {
+        console.error(`parachute setup: unknown argument "${remaining[0]}"`);
+        console.error("usage: parachute setup [--tag <name>] [--no-start]");
+        return 1;
+      }
+      const setupOpts: Parameters<typeof setup>[0] = {};
+      if (tagExtract.tag) setupOpts.tag = tagExtract.tag;
+      if (noStart) setupOpts.noStart = true;
+      return await setup(setupOpts);
+    }
+
     case "install": {
       if (isHelpFlag(rest[0])) {
         console.log(installHelp());
@@ -253,12 +364,18 @@ async function main(argv: string[]): Promise<number> {
         console.error(`parachute expose: ${hubExtract.error}`);
         return 1;
       }
-      const cfExtract = extractCloudflareFlags(hubExtract.rest);
-      if (cfExtract.error) {
-        console.error(`parachute expose: ${cfExtract.error}`);
+      const flagExtract = extractExposeProviderFlags(hubExtract.rest);
+      if (flagExtract.error) {
+        console.error(`parachute expose: ${flagExtract.error}`);
         return 1;
       }
-      const exposeArgs = cfExtract.rest;
+      if (flagExtract.cloudflare && flagExtract.tailnet) {
+        console.error(
+          "parachute expose: --tailnet and --cloudflare are mutually exclusive. Pick one.",
+        );
+        return 1;
+      }
+      const exposeArgs = flagExtract.rest;
       const layer = exposeArgs[0];
       const mode = exposeArgs[1];
       if (isHelpFlag(layer)) {
@@ -284,10 +401,17 @@ async function main(argv: string[]): Promise<number> {
       }
       const action = mode === "off" ? "off" : "up";
 
+      if (flagExtract.tailnet && layer !== "public") {
+        console.error(
+          "parachute expose: --tailnet pins the public layer to Tailscale Funnel; it doesn't apply to `expose tailnet`.",
+        );
+        return 1;
+      }
+
       // Cloudflare mode is a separate execution path — different detector,
       // different state file, different process model (it spawns cloudflared
       // rather than driving tailscale serve/funnel). Route to it early.
-      if (cfExtract.cloudflare) {
+      if (flagExtract.cloudflare) {
         if (layer !== "public") {
           console.error(
             "parachute expose: --cloudflare only applies to `public` (it's a public-internet path).",
@@ -297,10 +421,11 @@ async function main(argv: string[]): Promise<number> {
         const { exposeCloudflareUp, exposeCloudflareOff } = await import(
           "./commands/expose-cloudflare.ts"
         );
+        const cfOpts = flagExtract.tunnelName ? { tunnelName: flagExtract.tunnelName } : {};
         if (action === "off") {
-          return await exposeCloudflareOff();
+          return await exposeCloudflareOff(cfOpts);
         }
-        if (!cfExtract.domain) {
+        if (!flagExtract.domain) {
           // Partial flag promotion: the user told us they want Cloudflare but
           // didn't supply a hostname. In a TTY, prompt only for what's
           // missing instead of forcing them to retype the whole command. In a
@@ -322,21 +447,46 @@ async function main(argv: string[]): Promise<number> {
           console.error("  parachute expose public");
           return 1;
         }
-        return await exposeCloudflareUp(cfExtract.domain);
+        return await exposeCloudflareUp(flagExtract.domain, cfOpts);
       }
 
       const exposeOpts = hubExtract.hubOrigin ? { hubOrigin: hubExtract.hubOrigin } : {};
 
-      // Interactive picker: `parachute expose public` with no provider/domain
-      // flags, running under a TTY on both stdin and stdout, routes through a
-      // guided flow that offers Tailscale vs. Cloudflare, walks provider
-      // setup, and hands back to the flag-driven entry points. Non-TTY or any
-      // scripted use (flags present) keeps today's behavior exactly.
+      // `--tailnet` is the explicit Tailscale Funnel pin — bypass both the
+      // interactive picker and the non-TTY auto-pick. Goes straight to
+      // exposePublic so today's Funnel flow keeps working unchanged.
+      if (layer === "public" && action === "up" && flagExtract.tailnet) {
+        return await exposePublic("up", exposeOpts);
+      }
+
+      // Interactive picker: `parachute expose public` with no provider flags,
+      // running under a TTY on both stdin and stdout, routes through a guided
+      // flow that offers Tailscale vs. Cloudflare, walks provider setup, and
+      // hands back to the flag-driven entry points.
       if (layer === "public" && action === "up" && isTtyInteractive()) {
         const { exposePublicInteractive } = await import("./commands/expose-interactive.ts");
         return await exposePublicInteractive({ exposeOpts });
       }
 
+      // Non-TTY auto-pick: detect which provider is configured and run it.
+      // `--skip-provider-check` (CI escape hatch) skips detection and falls
+      // through to today's Tailscale-Funnel default — useful when the
+      // environment is already pre-flighted and the auto-pick would just
+      // print noise. Both paths run only on `expose public up`; tailnet
+      // exposure has only one provider so nothing to pick.
+      //
+      // `domain` and `tunnelName` are deliberately *not* threaded into
+      // auto-pick. Both are Cloudflare-only flags; if a user passes them
+      // without `--cloudflare`, threading would silently route them to
+      // Cloudflare. Better to drop the flags here and let auto-pick decide
+      // purely from what's installed — if it lands on cloudflare-only-ready,
+      // it prints the explicit `--cloudflare --domain` hint instead of
+      // guessing intent.
+      if (layer === "public" && action === "up" && !flagExtract.skipProviderCheck) {
+        const { exposePublicAutoPick } = await import("./commands/expose-public-auto.ts");
+        return await exposePublicAutoPick({ tailscaleOpts: exposeOpts });
+      }
+
       // `expose public off` (no `--cloudflare`) auto-detects which provider is
       // live. The explicit `--cloudflare` off branch above still wins — this
       // path is only for users who typed plain `off` and don't want to
@@ -346,9 +496,15 @@ async function main(argv: string[]): Promise<number> {
         return await runExposePublicOffAutoDetect({ tailscaleOffOpts: exposeOpts });
       }
 
-      return layer === "public"
-        ? await exposePublic(action, exposeOpts)
-        : await exposeTailnet(action, exposeOpts);
+      // `--skip-provider-check` fallthrough: pin to today's Tailscale-Funnel
+      // default for `expose public up`. Made explicit (rather than letting
+      // it tumble through the layer ternary) so the escape-hatch branch is
+      // visible at a glance.
+      if (layer === "public" && action === "up" && flagExtract.skipProviderCheck) {
+        return await exposePublic("up", exposeOpts);
+      }
+
+      return await exposeTailnet(action, exposeOpts);
     }
 
     case "start": {
@@ -381,6 +537,27 @@ async function main(argv: string[]): Promise<number> {
       return await restart(rest[0]);
     }
 
+    case "upgrade": {
+      if (isHelpFlag(rest[0])) {
+        console.log(upgradeHelp());
+        return 0;
+      }
+      const tagExtract = extractTag(rest);
+      if (tagExtract.error) {
+        console.error(`parachute upgrade: ${tagExtract.error}`);
+        return 1;
+      }
+      const remaining = tagExtract.rest;
+      if (remaining.length > 1) {
+        console.error(`parachute upgrade: unexpected argument "${remaining[1]}"`);
+        console.error("usage: parachute upgrade [<service>] [--tag <name>]");
+        return 1;
+      }
+      const upgradeOpts: Parameters<typeof upgrade>[1] = {};
+      if (tagExtract.tag) upgradeOpts.tag = tagExtract.tag;
+      return await upgrade(remaining[0], upgradeOpts);
+    }
+
     case "logs": {
       if (isHelpFlag(rest[0])) {
         console.log(logsHelp());
@@ -389,7 +566,7 @@ async function main(argv: string[]): Promise<number> {
       const svc = rest[0];
       if (!svc) {
         console.error("usage: parachute logs <service> [-f]");
-        console.error(`services: ${knownServices().join(", ")}`);
+        console.error(`services: ${[HUB_SVC, ...knownServices()].join(", ")}`);
         return 1;
       }
       const follow = rest.includes("-f") || rest.includes("--follow");

package/src/clients.ts

@@ -0,0 +1,210 @@
+/**
+ * OAuth client registry. Backs the `/oauth/register` endpoint (RFC 7591
+ * Dynamic Client Registration) and the client-lookup side of
+ * `/oauth/authorize` and `/oauth/token`.
+ *
+ * Two flavors:
+ *   - **Public clients** (PKCE-only): no `client_secret`. Browser-side apps
+ *     register themselves with one or more `redirect_uris` and rely on PKCE
+ *     for the auth-code exchange. `client_secret_hash` is NULL for these.
+ *   - **Confidential clients**: server-side apps. We mint a random
+ *     `client_secret` on registration, store its sha256 hash, return the
+ *     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`.
+ */
+import type { Database } from "bun:sqlite";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+
+export type ClientStatus = "pending" | "approved";
+
+export interface OAuthClient {
+  clientId: string;
+  /** SHA-256 hex digest of the client secret. Null for public clients. */
+  clientSecretHash: string | null;
+  redirectUris: string[];
+  scopes: string[];
+  clientName: string | null;
+  registeredAt: string;
+  /** Whether the client may participate in OAuth flows. See file header. */
+  status: ClientStatus;
+}
+
+export class ClientNotFoundError extends Error {
+  constructor(clientId: string) {
+    super(`oauth client "${clientId}" is not registered`);
+    this.name = "ClientNotFoundError";
+  }
+}
+
+export class InvalidRedirectUriError extends Error {
+  constructor(uri: string) {
+    super(`redirect_uri "${uri}" is not registered for this client`);
+    this.name = "InvalidRedirectUriError";
+  }
+}
+
+interface Row {
+  client_id: string;
+  client_secret_hash: string | null;
+  redirect_uris: string;
+  scopes: string;
+  client_name: string | null;
+  registered_at: string;
+  status: string;
+}
+
+function rowToClient(r: Row): OAuthClient {
+  return {
+    clientId: r.client_id,
+    clientSecretHash: r.client_secret_hash,
+    redirectUris: JSON.parse(r.redirect_uris) as string[],
+    scopes: r.scopes.split(" ").filter((s) => s.length > 0),
+    clientName: r.client_name,
+    registeredAt: r.registered_at,
+    status: r.status === "approved" ? "approved" : "pending",
+  };
+}
+
+export interface RegisterClientOpts {
+  redirectUris: string[];
+  scopes?: string[];
+  clientName?: string;
+  /** Defaults to public (PKCE-only). Set to true for a server-side client. */
+  confidential?: boolean;
+  /** Override the generated client_id. Mostly for tests + first-party seeds. */
+  clientId?: string;
+  /**
+   * Approval status to write. Defaults to `approved` — direct callers
+   * (tests, install-time first-party seeds) want a row that can OAuth.
+   * The public DCR endpoint (`POST /oauth/register`) passes `pending`
+   * explicitly so self-served registrations require operator approval
+   * before they can run an OAuth flow (closes #74).
+   */
+  status?: ClientStatus;
+  now?: () => Date;
+}
+
+export interface RegisteredClient {
+  client: OAuthClient;
+  /** Plaintext secret for confidential clients. NOT recoverable from the DB. */
+  clientSecret: string | null;
+}
+
+export function registerClient(db: Database, opts: RegisterClientOpts): RegisteredClient {
+  if (opts.redirectUris.length === 0) {
+    throw new Error("registerClient: at least one redirect_uri is required");
+  }
+  for (const uri of opts.redirectUris) {
+    if (!isValidRedirectUri(uri)) {
+      throw new Error(`registerClient: invalid redirect_uri "${uri}"`);
+    }
+  }
+  const clientId = opts.clientId ?? randomUUID();
+  const clientSecret = opts.confidential ? randomBytes(32).toString("base64url") : null;
+  const clientSecretHash = clientSecret
+    ? createHash("sha256").update(clientSecret).digest("hex")
+    : null;
+  const registeredAt = (opts.now?.() ?? new Date()).toISOString();
+  const scopes = (opts.scopes ?? []).join(" ");
+  const status: ClientStatus = opts.status ?? "approved";
+  db.prepare(
+    `INSERT INTO clients
+     (client_id, client_secret_hash, redirect_uris, scopes, client_name, registered_at, status)
+     VALUES (?, ?, ?, ?, ?, ?, ?)`,
+  ).run(
+    clientId,
+    clientSecretHash,
+    JSON.stringify(opts.redirectUris),
+    scopes,
+    opts.clientName ?? null,
+    registeredAt,
+    status,
+  );
+  return {
+    client: {
+      clientId,
+      clientSecretHash,
+      redirectUris: opts.redirectUris,
+      scopes: opts.scopes ?? [],
+      clientName: opts.clientName ?? null,
+      registeredAt,
+      status,
+    },
+    clientSecret,
+  };
+}
+
+/**
+ * Promote a `pending` client to `approved`. Idempotent — calling on an
+ * already-approved row is a no-op. Returns true when the row was found and
+ * is now approved (whether by this call or already), false when no such
+ * client exists. Used by `parachute auth approve-client`.
+ */
+export function approveClient(db: Database, clientId: string): boolean {
+  const existing = getClient(db, clientId);
+  if (!existing) return false;
+  if (existing.status === "approved") return true;
+  db.prepare("UPDATE clients SET status = 'approved' WHERE client_id = ?").run(clientId);
+  return true;
+}
+
+/** List clients filtered by status. Used by `parachute auth pending-clients`. */
+export function listClientsByStatus(db: Database, status: ClientStatus): OAuthClient[] {
+  const rows = db
+    .query<Row, [string]>("SELECT * FROM clients WHERE status = ? ORDER BY registered_at")
+    .all(status);
+  return rows.map(rowToClient);
+}
+
+export function getClient(db: Database, clientId: string): OAuthClient | null {
+  const row = db.query<Row, [string]>("SELECT * FROM clients WHERE client_id = ?").get(clientId);
+  return row ? rowToClient(row) : null;
+}
+
+/**
+ * Returns the registered redirect URI matching `candidate` exactly, or throws.
+ * RFC 8252 + 6749 require exact-match for redirect URIs (no wildcards, no
+ * loose comparison) — anything looser is an open-redirect waiting to happen.
+ */
+export function requireRegisteredRedirectUri(client: OAuthClient, candidate: string): string {
+  if (!client.redirectUris.includes(candidate)) {
+    throw new InvalidRedirectUriError(candidate);
+  }
+  return candidate;
+}
+
+export function verifyClientSecret(client: OAuthClient, presented: string): boolean {
+  if (!client.clientSecretHash) return false;
+  const presentedHash = createHash("sha256").update(presented).digest("hex");
+  return timingSafeEqualHex(client.clientSecretHash, presentedHash);
+}
+
+function timingSafeEqualHex(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return diff === 0;
+}
+
+/**
+ * Light validation — refuses obviously-wrong shapes (relative paths, javascript:
+ * URIs). Doesn't try to match a registered URI; that's `requireRegisteredRedirectUri`.
+ */
+export function isValidRedirectUri(uri: string): boolean {
+  try {
+    const u = new URL(uri);
+    if (u.protocol === "javascript:" || u.protocol === "data:") return false;
+    return u.protocol === "http:" || u.protocol === "https:";
+  } catch {
+    return false;
+  }
+}

package/src/cloudflare/config.ts

@@ -3,8 +3,30 @@ import { dirname, join } from "node:path";
 import { CONFIG_DIR } from "../config.ts";
 
 export const CLOUDFLARED_DIR = join(CONFIG_DIR, "cloudflared");
-export const CLOUDFLARED_CONFIG_PATH = join(CLOUDFLARED_DIR, "config.yml");
-export const CLOUDFLARED_LOG_PATH = join(CLOUDFLARED_DIR, "cloudflared.log");
+
+export const DEFAULT_TUNNEL_NAME = "parachute";
+
+/**
+ * Per-tunnel config + log file paths. Each tunnel gets its own subdirectory
+ * under `~/.parachute/cloudflared/<tunnelName>/` so multiple tunnels on one
+ * box don't trample each other's config.yml or interleave log lines.
+ *
+ * The default tunnel ("parachute") lives at
+ * `~/.parachute/cloudflared/parachute/{config.yml,cloudflared.log}` — a
+ * 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.
+ */
+export function cloudflaredPathsFor(tunnelName: string): {
+  configPath: string;
+  logPath: string;
+} {
+  const dir = join(CLOUDFLARED_DIR, tunnelName);
+  return {
+    configPath: join(dir, "config.yml"),
+    logPath: join(dir, "cloudflared.log"),
+  };
+}
 
 export interface TunnelConfigOpts {
   tunnelUuid: string;
@@ -48,10 +70,7 @@ ingress:
 `;
 }
 
-export function writeConfig(
-  opts: TunnelConfigOpts,
-  configPath: string = CLOUDFLARED_CONFIG_PATH,
-): string {
+export function writeConfig(opts: TunnelConfigOpts, configPath: string): string {
   mkdirSync(dirname(configPath), { recursive: true });
   writeFileSync(configPath, renderConfig(opts));
   return configPath;