@openparachute/hub 0.5.7 → 0.5.10-rc.10

package/src/csrf.ts

@@ -19,15 +19,28 @@
  * pre-login and post-login forms, and it works no matter how many tabs the
  * operator has open.
  *
- * The cookie is HttpOnly (the form doesn't need JS to read it; the server
- * embeds the value at render time), SameSite=Lax (matches the session
- * cookie), Secure, and Path=/ (covers every admin form, OAuth or otherwise).
+ * The cookie is HttpOnly: consumers receive the token value via either the
+ * server-rendered HTML form (cookie + embedded value, classic double-submit)
+ * or via the JSON body of `/api/me` (cookie alongside body — same pattern,
+ * just JSON instead of HTML). Neither path needs JS to read the cookie
+ * directly. SameSite=Lax (matches the session cookie), Secure conditional
+ * on the request protocol (see below), and Path=/ (covers every admin
+ * form, OAuth flow, and `/api/me` consumer).
+ *
+ * `Secure` is set when the request arrived over HTTPS (direct or behind a
+ * reverse proxy that set `X-Forwarded-Proto: https`) — `isHttpsRequest` in
+ * `request-protocol.ts` is the single source of truth. On
+ * `http://localhost:1939` the attribute is omitted so the browser actually
+ * keeps the cookie; setting `Secure` unconditionally silently drops it on
+ * HTTP and breaks the double-submit handshake on the very next POST
+ * ("Invalid form submission" page on the wizard, etc.).
  *
  * Token entropy: 32 random bytes, base64url-encoded — same shape as session
  * IDs. No HMAC needed: the value is opaque to the client and only ever
  * compared to itself across the cookie/form boundary.
  */
 import { randomBytes, timingSafeEqual } from "node:crypto";
+import { isHttpsRequest } from "./request-protocol.ts";
 
 export const CSRF_COOKIE_NAME = "parachute_hub_csrf";
 export const CSRF_FIELD_NAME = "__csrf";
@@ -39,15 +52,18 @@ export function generateCsrfToken(): string {
   return randomBytes(32).toString("base64url");
 }
 
-export function buildCsrfCookie(token: string): string {
-  return [
-    `${CSRF_COOKIE_NAME}=${token}`,
-    "HttpOnly",
-    "Secure",
-    "SameSite=Lax",
-    "Path=/",
-    `Max-Age=${CSRF_TTL_SECONDS}`,
-  ].join("; ");
+/**
+ * Build a Set-Cookie header value for a CSRF token. `secure` defaults to
+ * true (the production posture behind a TLS terminator); callers that
+ * mint the cookie for a known-HTTP request — `ensureCsrfToken` does
+ * this via `isHttpsRequest` — pass `secure: false` to omit the
+ * attribute so the browser keeps the cookie on plain HTTP.
+ */
+export function buildCsrfCookie(token: string, opts: { secure?: boolean } = {}): string {
+  const parts = [`${CSRF_COOKIE_NAME}=${token}`, "HttpOnly"];
+  if (opts.secure !== false) parts.push("Secure");
+  parts.push("SameSite=Lax", "Path=/", `Max-Age=${CSRF_TTL_SECONDS}`);
+  return parts.join("; ");
 }
 
 export function parseCsrfCookie(cookieHeader: string | null): string | null {
@@ -69,12 +85,17 @@ export interface EnsuredCsrf {
  * Ensure the request carries a CSRF token cookie; mint and return one if not.
  * Callers embed `result.token` in the rendered form and attach
  * `result.setCookie` (if defined) to the response.
+ *
+ * Protocol-aware: when the request is plain HTTP (`http://localhost:1939`
+ * during local dev / on-box CLI), the minted cookie omits the `Secure`
+ * attribute so the browser keeps it. When the request is HTTPS (or
+ * forwarded via `X-Forwarded-Proto: https`), `Secure` is set.
  */
 export function ensureCsrfToken(req: Request): EnsuredCsrf {
   const existing = parseCsrfCookie(req.headers.get("cookie"));
   if (existing && existing.length > 0) return { token: existing };
   const token = generateCsrfToken();
-  return { token, setCookie: buildCsrfCookie(token) };
+  return { token, setCookie: buildCsrfCookie(token, { secure: isHttpsRequest(req) }) };
 }
 
 /**

package/src/help.ts

@@ -17,6 +17,7 @@ Usage:
   parachute logs <service> [-f]     print service logs; -f to tail
   parachute expose tailnet [off]    HTTPS across your tailnet (supported)
   parachute expose public  [off]    HTTPS on the public internet (exploratory)
+  parachute serve                   run hub HTTP server foregrounded (for containers)
   parachute migrate [--dry-run]     archive legacy files at ecosystem root
   parachute auth <cmd>              identity (set password, manage 2FA)
   parachute vault <args...>         vault-specific ops (tokens, 2fa, config, init,
@@ -124,7 +125,7 @@ Examples:
 }
 
 export function statusHelp(): string {
-  return `parachute status — show installed services, process state, and health
+  return `parachute status — show installed services, process state, health, install source
 
 Usage:
   parachute status
@@ -133,22 +134,28 @@ What it does:
   Reads ~/.parachute/services.json. For each registered service:
     - checks PID file at ~/.parachute/<svc>/run/<svc>.pid → running/stopped
     - probes http://localhost:<port><health> (skipped for known-stopped processes)
+    - classifies the install source as bun-linked (local checkout) or npm
 
   Stopped services show "-" for health and don't count toward the exit
   code — they're an expected state after fresh install before \`parachute
   start\`. Running or externally-managed services that fail health checks
   do exit 1.
 
+  A "STALE: services.json cached … live package.json …" continuation line
+  appears under a row when a bun-linked service has been rebuilt but the
+  manifest's cached version hasn't caught up — re-install (\`parachute
+  install <pkg>\`) refreshes the row.
+
 Exit codes:
   0   all probed services healthy (or none running)
   1   one or more probed services unhealthy
 
 Example:
   $ parachute status
-  SERVICE          PORT  VERSION  PROCESS  PID    UPTIME  HEALTH  LATENCY
-  parachute-vault  1940  0.2.4    running  12345  2h 13m  ok      2ms
+  SERVICE          PORT  VERSION  PROCESS  PID    UPTIME  HEALTH  LATENCY  SOURCE
+  parachute-vault  1940  0.2.4    running  12345  2h 13m  ok      2ms      bun-linked → parachute-vault @ 8aa167b
     → http://127.0.0.1:1940/vault/default/mcp
-  parachute-notes  1942  0.0.1    stopped  -      -       -       -
+  parachute-notes  1942  0.0.1    stopped  -      -       -       -        npm (0.3.15-rc.1)
     → http://127.0.0.1:1942/notes
 `;
 }
@@ -342,8 +349,9 @@ What it does:
   Re-running on an up-to-date install is a fast no-op.
 
 Examples:
-  parachute upgrade                 sweep every installed service
+  parachute upgrade                 sweep hub + every installed service
   parachute upgrade vault           just vault
+  parachute upgrade hub             upgrade the dispatcher itself (closes #251)
   parachute upgrade vault --tag rc  pin the rc dist-tag (npm path only)
 `;
 }
@@ -363,6 +371,48 @@ If no log file exists yet, prints a hint to \`parachute start <service>\`.
 `;
 }
 
+export function serveHelp(): string {
+  return `parachute serve — run the hub HTTP server foregrounded
+
+Usage:
+  parachute serve
+
+The container shape. The on-box CLI flow (\`parachute expose\`) spawns the
+hub-server detached and tracks it via pidfile; \`parachute serve\` is the
+inverse — the hub IS the foreground process, lives as long as its
+supervisor wants it to, and exits on signal. Built for Docker / Render /
+systemd, but works fine for a foregrounded local debug too.
+
+Environment:
+  PORT                              bind port (default 1939). Render injects
+                                    this; honor it so the platform's HTTP
+                                    forwarder lands on the right socket.
+  PARACHUTE_HOME                    config root (default ~/.parachute).
+                                    Point at a persistent disk in containers.
+  PARACHUTE_HUB_ORIGIN              canonical https://… origin baked into
+                                    OAuth issuer + token aud claims. Set to
+                                    the public hostname Render / Cloudflare
+                                    serves.
+  PARACHUTE_INITIAL_ADMIN_USERNAME  on first boot when no admin row exists,
+  PARACHUTE_INITIAL_ADMIN_PASSWORD  seed an admin from these. Boot-time
+                                    idempotent — ignored once an admin
+                                    exists, so leaving them set across
+                                    restarts is safe.
+
+If no admin exists and the seed env vars aren't set, the hub still comes
+up — visit \`/admin/setup\` to bootstrap via the first-boot web wizard
+(admin account + first vault, all from the browser).
+
+Examples:
+  parachute serve                          # foreground, defaults
+  PORT=8080 PARACHUTE_HOME=/parachute parachute serve
+  docker run -e PARACHUTE_INITIAL_ADMIN_USERNAME=ops \\
+             -e PARACHUTE_INITIAL_ADMIN_PASSWORD=… \\
+             -v parachute-data:/parachute \\
+             parachute-hub:0.5.10 serve
+`;
+}
+
 export function migrateHelp(): string {
   return `parachute migrate — archive legacy files at the ecosystem root
 

package/src/hub-control.ts

@@ -27,6 +27,7 @@ import { WELL_KNOWN_DIR } from "./well-known.ts";
  */
 
 export const HUB_SVC = "hub";
+export const HUB_PACKAGE = "@openparachute/hub";
 export const HUB_DEFAULT_PORT = 1939;
 /**
  * Default fallback range is 1 — the hub binds 1939 or fails. Walking up would

package/src/hub-db.ts

@@ -130,6 +130,93 @@ const MIGRATIONS: readonly Migration[] = [
       CREATE INDEX tokens_family ON tokens (family_id) WHERE family_id IS NOT NULL;
     `,
   },
+  {
+    version: 6,
+    sql: `
+      -- Token registry generalization (closes hub#212 Phase 1). Until v6 the
+      -- tokens table only held OAuth refresh tokens; v6 generalizes it to a
+      -- single registry across every issued JWT class (refresh, access,
+      -- operator, mint-token). Three structural changes:
+      --
+      --   1. user_id becomes NULLABLE. OAuth-issued rows still set it to the
+      --      caller's user (canonical identity field). CLI-minted /
+      --      operator-minted rows leave user_id NULL and put the operator/
+      --      service name in the new \`subject\` column.
+      --   2. Three new columns: \`permissions\` (JSON, custom claim per
+      --      auth-architecture-shape.md §11.3), \`created_via\` (provenance
+      --      tag: oauth_refresh / cli_mint / operator_mint), \`subject\`
+      --      (non-user identity for service / operator mints).
+      --   3. Existing rows backfill \`created_via='oauth_refresh'\` because
+      --      the table was OAuth-refresh-only before v6.
+      --
+      -- SQLite has no ALTER COLUMN to drop NOT NULL, so we use the
+      -- recreate-and-rename pattern. Inside the migration transaction the
+      -- whole swap is atomic; concurrent reads (there are none — hub is
+      -- single-writer) wouldn't see a half-state. FKs from tokens → users
+      -- stay enforced for non-NULL user_id values; nothing references
+      -- tokens, so the drop is safe.
+      CREATE TABLE tokens_new (
+        jti TEXT PRIMARY KEY,
+        user_id TEXT REFERENCES users(id),
+        client_id TEXT NOT NULL,
+        scopes TEXT NOT NULL,
+        refresh_token_hash TEXT,
+        family_id TEXT,
+        expires_at TEXT NOT NULL,
+        revoked_at TEXT,
+        created_at TEXT NOT NULL,
+        permissions TEXT,
+        created_via TEXT NOT NULL DEFAULT 'oauth_refresh',
+        subject TEXT
+      );
+      INSERT INTO tokens_new (
+        jti, user_id, client_id, scopes, refresh_token_hash, family_id,
+        expires_at, revoked_at, created_at,
+        permissions, created_via, subject
+      )
+      SELECT
+        jti, user_id, client_id, scopes, refresh_token_hash, family_id,
+        expires_at, revoked_at, created_at,
+        NULL, 'oauth_refresh', NULL
+      FROM tokens;
+      DROP TABLE tokens;
+      ALTER TABLE tokens_new RENAME TO tokens;
+      -- Recreate indexes (DROP TABLE took them with it).
+      CREATE INDEX tokens_user ON tokens (user_id) WHERE user_id IS NOT NULL;
+      CREATE INDEX tokens_active_refresh ON tokens (refresh_token_hash)
+        WHERE refresh_token_hash IS NOT NULL AND revoked_at IS NULL;
+      CREATE INDEX tokens_family ON tokens (family_id) WHERE family_id IS NOT NULL;
+      -- New: revocation list endpoint queries on (revoked_at, expires_at).
+      CREATE INDEX tokens_revoked ON tokens (revoked_at)
+        WHERE revoked_at IS NOT NULL;
+      -- Subject lookup for non-user mints (operator name, service name).
+      CREATE INDEX tokens_subject ON tokens (subject) WHERE subject IS NOT NULL;
+    `,
+  },
+  {
+    version: 7,
+    sql: `
+      -- Hub-level key/value settings (hub#268). Used by:
+      --   * setup_expose_mode — operator's "how will this hub be reached?"
+      --     choice from the first-boot wizard expose step. Values:
+      --     'localhost' | 'tailnet' | 'public'.
+      --   * pending_first_client_auto_approve_until — ISO-8601 timestamp
+      --     set when the wizard finishes; first OAuth client registration
+      --     within the window is auto-approved + the row cleared (single
+      --     use). Absent / past-due means the standard pending-approval
+      --     flow applies.
+      --
+      -- Single-row-per-key schema. updated_at lets us age out stale
+      -- entries if a future pattern needs it; nothing currently relies on
+      -- it. Bare KV — no audit log, no history — these are hub-local
+      -- operator preferences, not user-facing data.
+      CREATE TABLE hub_settings (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      );
+    `,
+  },
 ];
 
 export function openHubDb(path: string = hubDbPath()): Database {