@openparachute/hub 0.5.2 → 0.5.7

package/src/__tests__/setup.test.ts

@@ -115,18 +115,21 @@ describe("setup", () => {
     const h = makeHarness();
     try {
       // Pre-seed every first-party shortname so survey returns all-installed.
-      for (const m of [
-        "parachute-vault",
-        "parachute-notes",
-        "parachute-scribe",
-        "parachute-channel",
-      ]) {
+      // Distinct canonical ports per service — services-manifest.ts now
+      // rejects duplicate ports between distinct services (hub#195).
+      const seeds: Array<{ name: string; port: number }> = [
+        { name: "parachute-vault", port: 1940 },
+        { name: "parachute-notes", port: 1942 },
+        { name: "parachute-scribe", port: 1943 },
+        { name: "parachute-channel", port: 1941 },
+      ];
+      for (const s of seeds) {
         upsertService(
           {
-            name: m,
+            name: s.name,
             version: "0.0.0",
-            port: 1940,
-            paths: [`/${m.replace(/^parachute-/, "")}`],
+            port: s.port,
+            paths: [`/${s.name.replace(/^parachute-/, "")}`],
             health: "/health",
           },
           h.manifestPath,

package/src/__tests__/status.test.ts

@@ -317,6 +317,179 @@ describe("status", () => {
     }
   });
 
+  // Canonical-port drift warning (hub#195). When a known service ends up at
+  // a non-canonical port (because of an upgrade rewrite, a port-walk fallback,
+  // or an operator edit), surface it in `parachute status` so a silent miswire
+  // is operator-visible. Warning, not error — operators may have moved the
+  // service deliberately to dodge a third-party clash.
+  describe("canonical-port drift warning", () => {
+    test("warns when scribe is at non-canonical port (1944 instead of 1943)", async () => {
+      const { path, cleanup } = makeTempPath();
+      try {
+        upsertService(
+          {
+            name: "parachute-scribe",
+            port: 1944,
+            paths: ["/scribe"],
+            health: "/scribe/health",
+            version: "0.4.0",
+          },
+          path,
+        );
+        const lines: string[] = [];
+        await status({
+          manifestPath: path,
+          fetchImpl: async () => new Response(null, { status: 200 }),
+          print: (l) => lines.push(l),
+        });
+        expect(lines.some((l) => l.includes("canonical port is 1943"))).toBe(true);
+      } finally {
+        cleanup();
+      }
+    });
+
+    test("does not warn when service is on its canonical port", async () => {
+      const { path, cleanup } = makeTempPath();
+      try {
+        upsertService(
+          {
+            name: "parachute-scribe",
+            port: 1943,
+            paths: ["/scribe"],
+            health: "/scribe/health",
+            version: "0.4.0",
+          },
+          path,
+        );
+        const lines: string[] = [];
+        await status({
+          manifestPath: path,
+          fetchImpl: async () => new Response(null, { status: 200 }),
+          print: (l) => lines.push(l),
+        });
+        expect(lines.some((l) => l.includes("canonical port"))).toBe(false);
+      } finally {
+        cleanup();
+      }
+    });
+
+    test("does not warn for third-party services with no canonical port", async () => {
+      const { path, cleanup } = makeTempPath();
+      try {
+        upsertService(
+          {
+            name: "third-party-thing",
+            port: 9000,
+            paths: ["/widget"],
+            health: "/health",
+            version: "1.0.0",
+          },
+          path,
+        );
+        const lines: string[] = [];
+        await status({
+          manifestPath: path,
+          fetchImpl: async () => new Response(null, { status: 200 }),
+          print: (l) => lines.push(l),
+        });
+        expect(lines.some((l) => l.includes("canonical port"))).toBe(false);
+      } finally {
+        cleanup();
+      }
+    });
+
+    test("warning does not affect exit code (status stays 0 when healthy)", async () => {
+      const { path, cleanup } = makeTempPath();
+      try {
+        upsertService(
+          {
+            name: "parachute-scribe",
+            port: 1944,
+            paths: ["/scribe"],
+            health: "/scribe/health",
+            version: "0.4.0",
+          },
+          path,
+        );
+        const code = await status({
+          manifestPath: path,
+          fetchImpl: async () => new Response(null, { status: 200 }),
+          print: () => {},
+        });
+        // Drift is informational. A healthy probed service still returns 0
+        // even when the port has drifted off canonical.
+        expect(code).toBe(0);
+      } finally {
+        cleanup();
+      }
+    });
+
+    test("warning still fires when service is stopped (probe skipped)", async () => {
+      const { path, configDir, cleanup } = makeTempPath();
+      try {
+        upsertService(
+          {
+            name: "parachute-scribe",
+            port: 1944,
+            paths: ["/scribe"],
+            health: "/scribe/health",
+            version: "0.4.0",
+          },
+          path,
+        );
+        writePid("scribe", 4242, configDir);
+        const lines: string[] = [];
+        await status({
+          manifestPath: path,
+          configDir,
+          alive: () => false,
+          fetchImpl: async () => new Response(null, { status: 200 }),
+          print: (l) => lines.push(l),
+        });
+        // Drift is computed from services.json, not from the probe — a
+        // stopped service with a drifted port should still surface the
+        // warning so operators see the miswire even before they start it.
+        expect(lines.some((l) => l.includes("canonical port is 1943"))).toBe(true);
+      } finally {
+        cleanup();
+      }
+    });
+
+    test("multi-vault instance rows do not surface a drift warning (intentional gap)", async () => {
+      // Pinning the documented gap: `parachute-vault-default` is not
+      // a canonical manifest name in FIRST_PARTY_FALLBACKS, so
+      // `canonicalPortForManifest` returns undefined and no drift
+      // warning fires — even when the row's port differs from the
+      // canonical `parachute-vault` port (1940). Rationale lives on
+      // `canonicalPortForManifest` in service-spec.ts; this test pins
+      // the behavior so a future change to the lookup shape doesn't
+      // accidentally start emitting drift on every multi-vault row
+      // without an explicit decision.
+      const { path, cleanup } = makeTempPath();
+      try {
+        upsertService(
+          {
+            name: "parachute-vault-default",
+            port: 1944,
+            paths: ["/vault/default"],
+            health: "/vault/default/health",
+            version: "0.2.4",
+          },
+          path,
+        );
+        const lines: string[] = [];
+        await status({
+          manifestPath: path,
+          fetchImpl: async () => new Response(null, { status: 200 }),
+          print: (l) => lines.push(l),
+        });
+        expect(lines.some((l) => l.includes("canonical port"))).toBe(false);
+      } finally {
+        cleanup();
+      }
+    });
+  });
+
   test("stopped services still render a URL line so the user knows where to point clients post-start", async () => {
     const { path, configDir, cleanup } = makeTempPath();
     try {

package/src/admin-handlers.ts

@@ -31,6 +31,7 @@ import { restart as lifecycleRestart } from "./commands/lifecycle.ts";
 import { CONFIG_DIR } from "./config.ts";
 import { CSRF_FIELD_NAME, ensureCsrfToken, verifyCsrfToken } from "./csrf.ts";
 import type { ModuleManifest } from "./module-manifest.ts";
+import { checkAndRecord, clientIpFromRequest } from "./rate-limit.ts";
 import {
   type ServicesManifest,
   readManifest as readServicesManifest,
@@ -41,7 +42,7 @@ import {
   buildSessionCookie,
   createSession,
   deleteSession,
-  findSession,
+  findActiveSession,
   parseSessionCookie,
 } from "./sessions.ts";
 import { getUserByUsername, verifyPassword } from "./users.ts";
@@ -74,15 +75,6 @@ function redirect(location: string, extra: Record<string, string> = {}): Respons
 
 // --- session gate ----------------------------------------------------------
 
-/**
- * Return the active session for this request, or null. Caller decides what
- * to do on null — most paths should redirect to `/admin/login?next=<path>`.
- */
-function activeSession(db: Database, req: Request) {
-  const sid = parseSessionCookie(req.headers.get("cookie"));
-  return sid ? findSession(db, sid) : null;
-}
-
 function loginRedirect(req: Request, extra: Record<string, string> = {}): Response {
   const url = new URL(req.url);
   const next = `${url.pathname}${url.search}`;
@@ -106,7 +98,11 @@ export function handleAdminLoginGet(_db: Database, req: Request): Response {
   return htmlResponse(renderAdminLogin({ next, csrfToken: csrf.token }), 200, extra);
 }
 
-export async function handleAdminLoginPost(db: Database, req: Request): Promise<Response> {
+export async function handleAdminLoginPost(
+  db: Database,
+  req: Request,
+  deps: AdminLoginDeps = {},
+): Promise<Response> {
   const form = await req.formData();
   const formCsrf = form.get(CSRF_FIELD_NAME);
   if (!verifyCsrfToken(req, typeof formCsrf === "string" ? formCsrf : null)) {
@@ -118,6 +114,24 @@ export async function handleAdminLoginPost(db: Database, req: Request): Promise<
       400,
     );
   }
+  // Rate-limit gate fires *after* CSRF (so a junk cross-site POST doesn't
+  // burn a bucket slot for the victim's IP) but *before* credential check.
+  // Every legitimate login attempt — wrong password, missing user, eventually
+  // failed-2FA (#186) — counts toward the same bucket so an attacker can't
+  // partition the cooldown across stages.
+  const clientIp = clientIpFromRequest(req);
+  const now = deps.now ? deps.now() : new Date();
+  const gate = checkAndRecord(clientIp, now);
+  if (!gate.allowed) {
+    return htmlResponse(
+      renderAdminError({
+        title: "Too many login attempts",
+        message: `Too many login attempts from this IP. Try again in ${gate.retryAfterSeconds ?? 1} seconds.`,
+      }),
+      429,
+      { "retry-after": String(gate.retryAfterSeconds ?? 1) },
+    );
+  }
   const username = String(form.get("username") ?? "");
   const password = String(form.get("password") ?? "");
   const next = safeNext(String(form.get("next") ?? ""));
@@ -147,6 +161,17 @@ export async function handleAdminLoginPost(db: Database, req: Request): Promise<
   return redirect(next, { "set-cookie": cookie });
 }
 
+/**
+ * Test-injection seam for `handleAdminLoginPost`. Production callers omit
+ * `deps`; tests pass a deterministic clock so the rate-limit assertions
+ * don't race wall-clock time. Kept narrow — login doesn't share the wider
+ * `AdminDeps` because it doesn't load services / module manifests.
+ */
+export interface AdminLoginDeps {
+  /** Test seam — defaults to real clock. */
+  now?: () => Date;
+}
+
 // --- /admin/logout ---------------------------------------------------------
 
 /**
@@ -183,7 +208,7 @@ export async function handleAdminConfigGet(
   req: Request,
   deps: AdminDeps = {},
 ): Promise<Response> {
-  const session = activeSession(db, req);
+  const session = findActiveSession(db, req);
   if (!session) return loginRedirect(req);
 
   const csrf = ensureCsrfToken(req);
@@ -207,7 +232,7 @@ export async function handleAdminConfigPost(
   moduleName: string,
   deps: AdminDeps = {},
 ): Promise<Response> {
-  const session = activeSession(db, req);
+  const session = findActiveSession(db, req);
   if (!session) return loginRedirect(req);
 
   const form = await req.formData();

package/src/commands/expose-2fa-warning.ts

@@ -0,0 +1,82 @@
+/**
+ * Public-exposure 2FA-enrollment warning (#186). Lands as the next layer of
+ * defense after #188's `/admin/login` rate-limit floor: once the operator
+ * brings up cloudflare or Tailscale Funnel, `/admin/login` is reachable from
+ * the public internet on every layer admitting traffic. 2FA is the difference
+ * between "password is the only wall" and "password + something-you-have."
+ *
+ * Why this is a warning, not a hard gate: hard-gating would surprise operators
+ * mid-flow — they ran `parachute expose public` to expose, not to be told
+ * "set up 2FA first." A loud, contextual warning + a clear one-line
+ * remediation is the right shape; the operator decides whether to act now or
+ * later. The tunnel is up regardless.
+ *
+ * Why the source-of-truth is vault's `config.yaml`: 2FA enrollment lives in
+ * `parachute-vault` (the hub forwards `parachute auth 2fa enroll` to vault —
+ * see `commands/auth.ts` `VAULT_FORWARDED_SUBCOMMANDS`). The hub's `users`
+ * table has no TOTP column today; it will gain one when hub-admin login
+ * verifies TOTP against vault. Until then, "is 2FA enrolled?" maps cleanly
+ * to "does vault's config.yaml carry a non-empty `totp_secret`?", which is
+ * exactly what `readVaultAuthStatus().hasTotp` returns.
+ *
+ * If vault isn't installed at all (rare for the cloudflare path — it requires
+ * a vault entry — but possible on the tailnet/funnel path): `hasTotp` comes
+ * back `false` and the warning still fires. The remediation
+ * `parachute auth 2fa enroll` then surfaces vault's "install vault first"
+ * error, which is the right next step regardless.
+ */
+
+import { type VaultAuthStatus, readVaultAuthStatus } from "../vault/auth-status.ts";
+
+export interface Public2FAWarningOpts {
+  /** Pre-computed status to skip on-disk probe (tests). Production omits. */
+  status?: VaultAuthStatus;
+  /** Forwarded to {@link readVaultAuthStatus} when `status` is not supplied. */
+  vaultHome?: string;
+  /** Sink for the warning lines. Defaults to console.log. */
+  log?: (line: string) => void;
+  /** Public URL the operator just brought up — embedded in the warning. */
+  publicUrl: string;
+}
+
+/**
+ * `true` when `totp_secret` is present and non-empty in vault's config.yaml,
+ * `false` otherwise (missing vault, missing config.yaml, empty value).
+ *
+ * Source-of-truth note: TOTP storage is the vault's, not the hub's. See the
+ * module-level doc comment.
+ */
+export function is2FAEnrolled(
+  opts: { vaultHome?: string; status?: VaultAuthStatus } = {},
+): boolean {
+  const status =
+    opts.status ?? readVaultAuthStatus(opts.vaultHome ? { vaultHome: opts.vaultHome } : {});
+  return status.hasTotp;
+}
+
+/**
+ * Print a 2FA-enrollment warning to `log` when not enrolled. No-op when
+ * enrolled. Returns `true` if the warning fired, `false` if suppressed —
+ * primarily to make integration tests assert the branch without scraping log
+ * text.
+ */
+export function printPublic2FAWarning(opts: Public2FAWarningOpts): boolean {
+  const log = opts.log ?? ((line: string) => console.log(line));
+  if (
+    is2FAEnrolled({
+      ...(opts.vaultHome ? { vaultHome: opts.vaultHome } : {}),
+      ...(opts.status ? { status: opts.status } : {}),
+    })
+  ) {
+    return false;
+  }
+  log("");
+  log("⚠ 2FA is not enrolled. /admin is now reachable on the public internet");
+  log(`  (${opts.publicUrl}/admin/login). Anyone who guesses your password`);
+  log("  is in. Strongly recommended:");
+  log("");
+  log("    parachute auth 2fa enroll");
+  log("");
+  log("  Adds TOTP + backup codes. Takes 30 seconds.");
+  return true;
+}

package/src/commands/expose-cloudflare.ts

@@ -30,6 +30,8 @@ import { SERVICES_MANIFEST_PATH } from "../config.ts";
 import { type AliveFn, defaultAlive } from "../process-state.ts";
 import { readManifest } from "../services-manifest.ts";
 import { type Runner, defaultRunner } from "../tailscale/run.ts";
+import type { VaultAuthStatus } from "../vault/auth-status.ts";
+import { printPublic2FAWarning } from "./expose-2fa-warning.ts";
 
 const AUTH_DOC_URL =
   "https://github.com/ParachuteComputer/parachute-vault/blob/main/docs/auth-model.md";
@@ -106,6 +108,18 @@ export interface ExposeCloudflareOpts {
   /** Override `~/.cloudflared` for tests and `$HOME`-free environments. */
   cloudflaredHome?: string;
   now?: () => Date;
+  /**
+   * Override `~/.parachute/vault` for the 2FA-enrollment probe. Tests
+   * point at a tmp dir; production omits and the probe defaults to the
+   * resolved vault home. (#186)
+   */
+  vaultHome?: string;
+  /**
+   * Pre-computed vault auth status, primarily for tests. When set,
+   * `printPublic2FAWarning` consults this instead of reading
+   * `<vaultHome>/config.yaml` from disk. (#186)
+   */
+  vaultAuthStatus?: VaultAuthStatus;
 }
 
 interface Resolved {
@@ -121,6 +135,8 @@ interface Resolved {
   logPath: string;
   cloudflaredHome: string;
   now: () => Date;
+  vaultHome: string | undefined;
+  vaultAuthStatus: VaultAuthStatus | undefined;
 }
 
 function resolve(opts: ExposeCloudflareOpts): Resolved {
@@ -139,6 +155,8 @@ function resolve(opts: ExposeCloudflareOpts): Resolved {
     logPath: opts.logPath ?? paths.logPath,
     cloudflaredHome: opts.cloudflaredHome ?? DEFAULT_CLOUDFLARED_HOME,
     now: opts.now ?? (() => new Date()),
+    vaultHome: opts.vaultHome,
+    vaultAuthStatus: opts.vaultAuthStatus,
   };
 }
 
@@ -313,6 +331,15 @@ export async function exposeCloudflareUp(
   r.log("Point a claude.ai / ChatGPT connector at:");
   r.log(`  ${vaultUrl}`);
   printAuthGuidance(r.log, vaultUrl);
+  // 2FA-enrollment warning when /admin/login is now reachable on the public
+  // internet but the operator hasn't enrolled TOTP. Cloudflare exposure is
+  // always public; tailnet/funnel mirrors this in `expose.ts`. See #186.
+  printPublic2FAWarning({
+    log: r.log,
+    publicUrl: baseUrl,
+    ...(r.vaultHome !== undefined ? { vaultHome: r.vaultHome } : {}),
+    ...(r.vaultAuthStatus !== undefined ? { status: r.vaultAuthStatus } : {}),
+  });
   return 0;
 }
 

package/src/commands/expose-public-auto.ts

@@ -30,8 +30,8 @@
 
 import { DEFAULT_CLOUDFLARED_HOME } from "../cloudflare/detect.ts";
 import {
-  type ProviderAvailability,
   type DetectProvidersOpts,
+  type ProviderAvailability,
   detectProviders,
   isCloudflareReady,
   isTailnetReady,
@@ -143,9 +143,7 @@ function reportCloudflareNeedsDomain(r: Resolved): number {
   r.log("Re-run with the hostname:");
   r.log("  parachute expose public --cloudflare --domain vault.example.com");
   r.log("");
-  r.log(
-    "The hostname's apex domain must already be a zone on your Cloudflare account.",
-  );
+  r.log("The hostname's apex domain must already be a zone on your Cloudflare account.");
   return 1;
 }
 
@@ -154,9 +152,7 @@ function reportCloudflareNeedsDomain(r: Resolved): number {
  * (`--tailnet` / `--cloudflare`) was supplied AND we're not in a TTY (the TTY
  * path runs `expose-interactive.ts` instead).
  */
-export async function exposePublicAutoPick(
-  opts: ExposePublicAutoOpts = {},
-): Promise<number> {
+export async function exposePublicAutoPick(opts: ExposePublicAutoOpts = {}): Promise<number> {
   const r = resolve(opts);
   const availability = await r.detectProvidersImpl({ cloudflaredHome: r.cloudflaredHome });
   const tsReady = isTailnetReady(availability);