@openparachute/hub 0.7.4-rc.14 → 0.7.4-rc.16

package/src/help.ts

@@ -17,6 +17,7 @@ Usage:
   parachute install <service>       install and register a service
                                     services: ${services}
   parachute status                  show installed services, run state, health
+  parachute doctor                  run health checks + tell you the one thing to fix
   parachute start   [service]       start a module via the supervisor (or ensure the hub is up)
   parachute stop    [service]       stop a module via the supervisor (or stop the hub unit)
   parachute restart [service]       restart a module via the supervisor (or restart the hub unit)
@@ -367,6 +368,43 @@ Example:
 `;
 }
 
+export function doctorHelp(): string {
+  return `parachute doctor — health / diagnostics for your Parachute install
+
+Usage:
+  parachute doctor [--json]
+
+What it does:
+  Runs a set of independent health checks and prints a grouped report
+  (✓ pass / ⚠ warn / ✗ fail), each with a one-line detail and — where there
+  is one — a copy-pasteable fix-it command. The single command that answers
+  "is my Parachute healthy, and if not, what's the one thing to fix?"
+
+  Checks (each PASSES on a fresh / fully-current install — doctor positively
+  detects a known-bad condition and never treats "not configured" as broken):
+    - Hub supervisor reachable on :1939 (/health).
+    - Each CONFIGURED module alive via its loopback /health (2xx or 401 = live).
+    - services.json parses + required fields valid (a missing file is the
+      fresh pre-install state, not a failure).
+    - operator.token exists, parses, and its issuer matches the hub (the
+      recurring "not signed in to the hub" / issuer-mismatch class).
+    - Each first-party module bin is executable (catches the lost-+x-bit
+      start-failure class).
+    - Migration: legacy detached install? known cruft at the ecosystem root?
+      (allowlist detectors only — a fresh root flags nothing).
+    - Exposure: if exposed, is the public origin reachable? If not exposed,
+      "loopback only" is reported as benign info, never a warning.
+    - Version freshness (cosmetic) — drift is WARN at most, never a failure.
+
+Flags:
+  --json     emit a single JSON object instead of the human report
+
+Exit codes:
+  0   no failures (warnings are advisory and still exit 0)
+  1   one or more checks failed
+`;
+}
+
 export function exposeHelp(): string {
   return `parachute expose — route your services behind HTTPS on a network layer
 

package/src/rate-limit.ts

@@ -87,6 +87,21 @@ export const CHANGE_PASSWORD_WINDOW_MS = 5 * 60 * 1000;
  * cookie attacker shouldn't get a 5-shot grind window.
  */
 export const CHANGE_PASSWORD_MAX_ATTEMPTS = 3;
+/**
+ * `/api/account/2fa/confirm` (TOTP enrollment seal) window: 15 minutes. This is
+ * the SELF-only, already-session-authenticated enrollment step — the operator is
+ * typing the first live code off their own authenticator while it drifts into
+ * sync, so legitimate mistypes are common and must not be punished. The threat
+ * is only a hijacked session grinding the (client-held, not-yet-persisted)
+ * in-flight secret, which the 10^6 code space + replay cache already make
+ * effectively non-exploitable — so this is defense-in-depth, deliberately MORE
+ * generous than the 3/5-min change-password bucket. NOT the `/login/2fa` bucket:
+ * that one is the strict, pre-auth brute-force door (5/15-min); enrollment is a
+ * different, lower-risk surface and gets its own lenient bucket.
+ */
+export const TOTP_ENROLL_CONFIRM_WINDOW_MS = 15 * 60 * 1000;
+/** `/api/account/2fa/confirm` attempts allowed per window. 11th is denied. */
+export const TOTP_ENROLL_CONFIRM_MAX_ATTEMPTS = 10;
 /**
  * `/login/2fa` window length: 15 minutes — same as `/login`. The second-
  * factor step (hub#473) sits behind a verified password + a short-lived
@@ -289,6 +304,18 @@ export const changePasswordRateLimiter = new RateLimiter(
  */
 export const totpRateLimiter = new RateLimiter(TOTP_MAX_ATTEMPTS, TOTP_WINDOW_MS);
 
+/**
+ * `/api/account/2fa/confirm` enrollment-seal bucket. Lenient (10 / 15 min),
+ * keyed by `user.id` (the session already establishes identity). Separate from
+ * `totpRateLimiter` so an enrollment mistype and a `/login/2fa` failure never
+ * share a window — different surfaces, different threat models (see the const
+ * docs above).
+ */
+export const totpEnrollConfirmRateLimiter = new RateLimiter(
+  TOTP_ENROLL_CONFIRM_MAX_ATTEMPTS,
+  TOTP_ENROLL_CONFIRM_WINDOW_MS,
+);
+
 /**
  * Coarse per-IP CEILING rate limiter — 60 attempts / 15 min, keyed by client
  * IP ONLY. Shared by all interactive auth doors (`/login`, the
@@ -342,6 +369,7 @@ export function __resetForTests(): void {
   loginRateLimiter.reset();
   changePasswordRateLimiter.reset();
   totpRateLimiter.reset();
+  totpEnrollConfirmRateLimiter.reset();
   vaultTokenMintRateLimiter.reset();
   signupRateLimiter.reset();
   authIpCeilingRateLimiter.reset();