@openparachute/hub 0.5.10-rc.6 → 0.5.10

package/src/supervisor.ts

@@ -80,6 +80,17 @@ export interface SupervisorOpts {
    * Default 500 — gives sockets time to release on EADDRINUSE.
    */
   readonly restartDelayMs?: number;
+  /**
+   * Max time to wait for a child to exit after SIGTERM before
+   * escalating to SIGKILL, in ms. Default 5000 — long enough for a
+   * well-behaved module to flush its log buffer + drop its listeners,
+   * short enough that a wedged child doesn't keep `stop()` (and the
+   * container shutdown path that calls it) hanging indefinitely.
+   *
+   * Tests pass a short timeout (1–10ms) to exercise the SIGKILL
+   * escalation path without real waiting.
+   */
+  readonly killTimeoutMs?: number;
   /**
    * Where prefixed child output goes. Default `process.stdout.write`.
    * Tests inject a collector so they can assert on the multiplexed
@@ -123,6 +134,7 @@ export interface SupervisedProc {
 const DEFAULT_MAX_RESTARTS = 3;
 const DEFAULT_RESTART_WINDOW_MS = 60_000;
 const DEFAULT_RESTART_DELAY_MS = 500;
+const DEFAULT_KILL_TIMEOUT_MS = 5_000;
 
 /**
  * Per-module supervisor. Owns the spawn → watch → restart loop.
@@ -143,6 +155,7 @@ export class Supervisor {
       maxRestarts: opts.maxRestarts ?? DEFAULT_MAX_RESTARTS,
       restartWindowMs: opts.restartWindowMs ?? DEFAULT_RESTART_WINDOW_MS,
       restartDelayMs: opts.restartDelayMs ?? DEFAULT_RESTART_DELAY_MS,
+      killTimeoutMs: opts.killTimeoutMs ?? DEFAULT_KILL_TIMEOUT_MS,
       output: opts.output ?? ((line) => process.stdout.write(line)),
       spawnFn: opts.spawnFn ?? defaultSpawnFn,
       now: opts.now ?? Date.now,
@@ -177,20 +190,65 @@ export class Supervisor {
   }
 
   /**
-   * Stop a supervised module. Sends SIGTERM, marks the state
-   * `stopped`, and detaches the exit watcher so a normal termination
-   * isn't seen as a crash. Idempotent on already-stopped modules.
+   * Stop a supervised module. Sends SIGTERM, awaits the child's exit
+   * (so the log-pump drains the final flush before our stdout closes),
+   * and escalates to SIGKILL if the child doesn't exit within
+   * `killTimeoutMs`. Marks the state `stopped` and detaches the exit
+   * watcher so a normal termination isn't seen as a crash. Idempotent
+   * on already-stopped modules.
+   *
+   * The await matters in two places:
+   *   - Container shutdown (hub PID 1 receiving SIGTERM from Render):
+   *     without it, children's final log lines never make it through
+   *     hub's stdout pipe before the platform reaps the pod.
+   *   - `restart()`: a fresh spawn that races a still-listening prior
+   *     PID will fail with EADDRINUSE.
+   *
+   * The SIGKILL escalation handles a wedged module (e.g. a broken
+   * native binding ignoring SIGTERM). Without it, `stop()` would hang
+   * forever and a re-deploy would leak the orphaned child until the
+   * container itself was recycled.
    */
   async stop(short: string): Promise<ModuleState | undefined> {
     const entry = this.modules.get(short);
     if (!entry) return undefined;
     entry.stopRequested = true;
-    if (entry.proc) {
+    const proc = entry.proc;
+    if (proc) {
       try {
-        entry.proc.kill("SIGTERM");
+        proc.kill("SIGTERM");
       } catch {
         // Process may already be dead — fall through.
       }
+      // Race the child's exit against the kill timeout. If the timer
+      // wins, escalate to SIGKILL. Either way we end up awaiting the
+      // exit promise so the log pump drains.
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const timeout = new Promise<"timeout">((resolve) => {
+        timer = setTimeout(() => resolve("timeout"), this.opts.killTimeoutMs);
+      });
+      try {
+        const winner = await Promise.race([proc.exited.then(() => "exited" as const), timeout]);
+        if (winner === "timeout") {
+          this.opts.output(
+            `[supervisor] ${entry.req.short} did not exit ${this.opts.killTimeoutMs}ms after SIGTERM — escalating to SIGKILL.\n`,
+          );
+          try {
+            proc.kill("SIGKILL");
+          } catch {
+            // Process may already be dead between the timeout firing
+            // and us reaching kill() — fall through to the await.
+          }
+          try {
+            await proc.exited;
+            // SIGKILL cannot be caught; OS reaps the child promptly.
+          } catch {
+            // exited rejection is non-fatal — we're stopping anyway.
+          }
+        }
+      } finally {
+        clearTimeout(timer!);
+      }
     }
     entry.state = { ...entry.state, status: "stopped" };
     return entry.state;
@@ -217,16 +275,10 @@ export class Supervisor {
     if (!entry) return undefined;
     const req = entry.req;
     entry.state = { ...entry.state, status: "restarting" };
+    // stop() now awaits the prior process's exit (with SIGKILL
+    // escalation) before returning, so the fresh spawn below doesn't
+    // race on EADDRINUSE — no separate await needed here.
     await this.stop(short);
-    // Wait for the prior process to actually exit so the new spawn
-    // doesn't race on EADDRINUSE.
-    if (entry.proc) {
-      try {
-        await entry.proc.exited;
-      } catch {
-        // exited promise rejection is non-fatal — we're stopping anyway.
-      }
-    }
     // Drop the entry so `start` treats this as a clean spawn.
     this.modules.delete(short);
     return this.start(req);

package/src/users.ts

@@ -25,6 +25,25 @@ export interface User {
   passwordHash: string;
   createdAt: string;
   updatedAt: string;
+  /**
+   * Whether the user has changed their password since account creation.
+   * `false` means the user signed up with an admin-typed default password
+   * and the force-change-password flow at sign-in time should redirect
+   * them to `/account/change-password`. The wizard's first admin and env-
+   * seeded admins land as `true` (they chose their own password). Stored
+   * as `users.password_changed INTEGER 0|1` (added in migration v8).
+   */
+  passwordChanged: boolean;
+  /**
+   * The vault instance name this user is pinned to (Phase 1 multi-user is
+   * single-vault-per-user). `null` means "no per-vault restriction" — the
+   * default for admin accounts, where the OAuth issuer mints tokens for
+   * any requested vault. Non-null pins the issuer to narrow scopes to
+   * `vault:<assigned_vault>:<verb>`. No FK; vault names resolve through
+   * `services.json` at mint time. Stored as `users.assigned_vault TEXT`
+   * (added in migration v8).
+   */
+  assignedVault: string | null;
 }
 
 export class SingleUserModeError extends Error {
@@ -56,6 +75,8 @@ interface Row {
   password_hash: string;
   created_at: string;
   updated_at: string;
+  password_changed: number;
+  assigned_vault: string | null;
 }
 
 function rowToUser(r: Row): User {
@@ -65,6 +86,8 @@ function rowToUser(r: Row): User {
     passwordHash: r.password_hash,
     createdAt: r.created_at,
     updatedAt: r.updated_at,
+    passwordChanged: r.password_changed === 1,
+    assignedVault: r.assigned_vault,
   };
 }
 
@@ -72,6 +95,23 @@ export interface CreateUserOpts {
   /** Allow creating an additional user when one already exists. Off by default. */
   allowMulti?: boolean;
   now?: () => Date;
+  /**
+   * Whether the new user has already chosen their password. Default `false`
+   * — the admin-creates-user path (PR 2) lands new accounts with the bit
+   * unset so the user is force-redirected to change it on first sign-in
+   * (PR 3). The wizard's first-admin path and env-seeded admin path pass
+   * `true` (they chose their own password through the wizard form / env
+   * vars; no force-change needed).
+   */
+  passwordChanged?: boolean;
+  /**
+   * Vault instance name to pin the user to (Phase 1 single-vault). `null`
+   * (default) means "no restriction" — admin posture. The OAuth issuer
+   * (PR 4) reads this at mint time to narrow scopes. No validation here:
+   * the API endpoint (PR 2) is responsible for checking against
+   * `services.json` before passing through.
+   */
+  assignedVault?: string | null;
 }
 
 export async function createUser(
@@ -87,10 +127,14 @@ export async function createUser(
   const id = randomUUID();
   const passwordHash = await argonHash(password);
   const stamp = (opts.now?.() ?? new Date()).toISOString();
+  const passwordChanged = opts.passwordChanged === true ? 1 : 0;
+  const assignedVault = opts.assignedVault ?? null;
   try {
     db.prepare(
-      "INSERT INTO users (id, username, password_hash, created_at, updated_at) VALUES (?, ?, ?, ?, ?)",
-    ).run(id, username, passwordHash, stamp, stamp);
+      `INSERT INTO users
+         (id, username, password_hash, created_at, updated_at, password_changed, assigned_vault)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`,
+    ).run(id, username, passwordHash, stamp, stamp, passwordChanged, assignedVault);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     if (msg.includes("UNIQUE") && msg.includes("users.username")) {
@@ -98,7 +142,15 @@ export async function createUser(
     }
     throw err;
   }
-  return { id, username, passwordHash, createdAt: stamp, updatedAt: stamp };
+  return {
+    id,
+    username,
+    passwordHash,
+    createdAt: stamp,
+    updatedAt: stamp,
+    passwordChanged: passwordChanged === 1,
+    assignedVault,
+  };
 }
 
 export function getUserByUsername(db: Database, username: string): User | null {
@@ -106,6 +158,22 @@ export function getUserByUsername(db: Database, username: string): User | null {
   return row ? rowToUser(row) : null;
 }
 
+/**
+ * Case-insensitive username lookup. Username validation already pins
+ * the canonical form to lowercase (`[a-z0-9_-]`), so the only way a
+ * mixed-case lookup ever fires is a defense-in-depth check at the
+ * admin-create-user boundary — a future loosening of the validator
+ * (or a hand-edited row) wouldn't accidentally allow `Bob` to land
+ * alongside an existing `bob`. SQLite's `COLLATE NOCASE` does the work
+ * with no schema change.
+ */
+export function getUserByUsernameCI(db: Database, username: string): User | null {
+  const row = db
+    .query<Row, [string]>("SELECT * FROM users WHERE username = ? COLLATE NOCASE")
+    .get(username);
+  return row ? rowToUser(row) : null;
+}
+
 export function getUserById(db: Database, id: string): User | null {
   const row = db.query<Row, [string]>("SELECT * FROM users WHERE id = ?").get(id);
   return row ? rowToUser(row) : null;
@@ -142,3 +210,142 @@ export async function setPassword(
     .run(passwordHash, stamp, userId);
   if (result.changes === 0) throw new UserNotFoundError(userId);
 }
+
+/**
+ * Hard-delete a user row and clean up FK-dependent rows.
+ *
+ * Schema reality at v8:
+ *   - `tokens.user_id` is nullable (made nullable in migration v6). The
+ *     plan from the design doc is "tokens stay with `revoked_at` set so
+ *     the audit trail of 'this user existed and held these tokens'
+ *     survives." But the FK is RESTRICT-on-delete, so we need to null
+ *     out `tokens.user_id` after revoking to actually delete the
+ *     parent users row. The audit trail survives via the `subject`
+ *     column we backfill from the username plus the existing
+ *     `created_at`, `scopes`, `client_id`, `revoked_at` fields.
+ *   - `sessions.user_id` and `grants.user_id` are NOT NULL with a
+ *     non-cascading FK. Both are deleted before the users row drops.
+ *
+ * Returns false when no user matches the id (idempotent — the API
+ * layer translates that to 404). Returns true on a successful delete.
+ *
+ * Caller is responsible for the first-admin-undeletable check; this
+ * helper enforces no policy beyond the schema hygiene.
+ */
+export function deleteUser(db: Database, userId: string): boolean {
+  const row = db.query<Row, [string]>("SELECT * FROM users WHERE id = ?").get(userId);
+  if (!row) return false;
+  const now = new Date().toISOString();
+  db.transaction(() => {
+    // 1. Revoke + retain tokens for audit. Mark every un-revoked token
+    //    revoked, then null out user_id on every token (revoked or
+    //    not) so the FK doesn't block the users delete. Backfill
+    //    `subject` with the username so the audit trail isn't anchored
+    //    to a primary key that just vanished.
+    db.prepare("UPDATE tokens SET revoked_at = ? WHERE user_id = ? AND revoked_at IS NULL").run(
+      now,
+      userId,
+    );
+    db.prepare(
+      "UPDATE tokens SET subject = COALESCE(subject, ?), user_id = NULL WHERE user_id = ?",
+    ).run(row.username, userId);
+    // 2. Drop sessions + grants. Both have non-cascading FKs on user_id;
+    //    leaving rows behind would RESTRICT the users delete below.
+    db.prepare("DELETE FROM sessions WHERE user_id = ?").run(userId);
+    db.prepare("DELETE FROM grants WHERE user_id = ?").run(userId);
+    // 3. Drop the user row itself.
+    db.prepare("DELETE FROM users WHERE id = ?").run(userId);
+  })();
+  return true;
+}
+
+/**
+ * Username validation (multi-user Phase 1, design 2026-05-20-multi-user-phase-1.md §4).
+ *
+ * Rules — settled with Aaron pre-PR-1:
+ *   * Charset: `[a-z0-9_-]` (lowercase letters, digits, underscore, hyphen).
+ *     Lowercase-only sidesteps "Bob vs bob" case-folding bugs across every
+ *     downstream surface (URLs, log lines, the admin SPA's row keys).
+ *   * Length: 2-32 chars inclusive. Hard floor on 1-char names (no `a`,
+ *     `b`, …) because those are too easy to typo into someone else's
+ *     account; hard ceiling on 32 because URL paths and log lines stay
+ *     scannable. (Same shape vault-side scope verbs use.)
+ *   * Reserved list (case-insensitive): admin, root, system, setup,
+ *     parachute, hub. Keeps URL-shaped surfaces safe (Phase 2 may add
+ *     `/users/<username>` paths; reserving the namespace now is cheap).
+ *     Regex already pins lowercase, but the case-folded check is defense
+ *     in depth: if a future loosening lets capitals through, the reserved
+ *     check still triggers on `Admin`, `ROOT`, etc.
+ *
+ * Discriminated-union return: callers branch on `valid` rather than
+ * throwing. PR 2's `POST /api/users` returns a 400 with the `reason`
+ * surfaced in the response body.
+ */
+export const USERNAME_RESERVED = ["admin", "root", "system", "setup", "parachute", "hub"] as const;
+
+const USERNAME_REGEX = /^[a-z0-9_-]+$/;
+const USERNAME_MIN_LEN = 2;
+const USERNAME_MAX_LEN = 32;
+
+export type ValidateUsernameResult =
+  | { valid: true; name: string }
+  | { valid: false; reason: "format" | "length" | "reserved" };
+
+export function validateUsername(name: string): ValidateUsernameResult {
+  // Length check first — a 0-char string fails the regex on emptiness but
+  // "length" is the more honest diagnostic.
+  if (name.length < USERNAME_MIN_LEN || name.length > USERNAME_MAX_LEN) {
+    return { valid: false, reason: "length" };
+  }
+  // The regex deliberately allows leading/trailing `_` and `-` (so
+  // `_-_`, `--alice`, `-foo`, `bar_` all pass the format gate). Stricter
+  // rules can land later if real-world users hit confusion. Vault's
+  // parallel username validator has the same shape — cross-repo parity
+  // matters more than aesthetic edge-case rejection here.
+  if (!USERNAME_REGEX.test(name)) {
+    return { valid: false, reason: "format" };
+  }
+  // Reserved-words check is case-insensitive even though the regex already
+  // pins lowercase — see comment above.
+  const lower = name.toLowerCase();
+  if (USERNAME_RESERVED.some((r) => r === lower)) {
+    return { valid: false, reason: "reserved" };
+  }
+  return { valid: true, name };
+}
+
+/**
+ * Password validation (multi-user Phase 1, design §5).
+ *
+ * Single rule: minimum 12 characters. No complexity classes — modern
+ * guidance (NIST 800-63B) prefers passphrase length over forced-symbol
+ * mixes, and Aaron settled on 12 as the floor pre-PR-1. No max length
+ * (argon2id absorbs whatever the user submits).
+ *
+ * Same discriminated-union shape as `validateUsername` — PR 2's create-
+ * user / reset-password endpoints (and PR 3's `/account/change-password`
+ * form) wire the `reason` into the response.
+ */
+export const PASSWORD_MIN_LEN = 12;
+
+/**
+ * Upper bound for incoming password bodies. Not enforced inside
+ * `validatePassword` itself — the validator's contract is "length floor,
+ * no complexity rules" and adding a ceiling would muddy it. Exposed as
+ * a constant so PR 2's `POST /api/users` (and PR 3's change-password
+ * form) can cap incoming bodies before argon2id touches them. Defense
+ * against a CPU-DoS shape where an unauthenticated POST submits a
+ * megabyte password and forces a long argon2id hash. 256 chars is
+ * comfortably above any human-chosen passphrase (Diceware 8-word
+ * passphrases run ~55 chars).
+ */
+export const PASSWORD_MAX_LEN = 256;
+
+export type ValidatePasswordResult = { valid: true } | { valid: false; reason: "too_short" };
+
+export function validatePassword(password: string): ValidatePasswordResult {
+  if (password.length < PASSWORD_MIN_LEN) {
+    return { valid: false, reason: "too_short" };
+  }
+  return { valid: true };
+}

package/src/vault-name.ts

@@ -0,0 +1,71 @@
+/**
+ * Vault-name validation, mirrored from `@openparachute/vault`'s
+ * `src/vault-name.ts`.
+ *
+ * The vault package owns the canonical validator (used by `init`, the
+ * `--vault-name` flag, and the `PARACHUTE_VAULT_NAME` env var on
+ * first-boot). Hub doesn't depend on vault at runtime, so we keep a
+ * byte-identical contract here and pin parity with a test that exercises
+ * the same rule set:
+ *
+ *   * lowercase alphanumeric + hyphens or underscores
+ *   * 2–32 chars
+ *   * `list` is reserved
+ *
+ * If vault's validator changes (e.g. additional reserved name, length
+ * relaxation), the two must move in lockstep — hub passing the typed
+ * name through `PARACHUTE_VAULT_NAME` only works as long as vault accepts
+ * what hub validates. Cross-repo drift here would silently fall back to
+ * `default` at vault first-boot (vault's `resolveFirstBootVaultName`
+ * downgrades env-invalid values).
+ *
+ * Out of scope: collision against existing vaults on the same hub — the
+ * wizard only ever creates the first vault, so name reuse can't happen.
+ * Subsequent vaults go through the admin SPA, which talks to vault's own
+ * `/vault/list` endpoint.
+ */
+
+const VAULT_NAME_RE = /^[a-z0-9_-]+$/;
+const VAULT_NAME_MIN_LEN = 2;
+const VAULT_NAME_MAX_LEN = 32;
+
+const RESERVED_NAMES = new Set([
+  // Mirrors vault's reservation. Collides with the legacy `/vaults/list`
+  // discovery endpoint; the routes have moved under `/vault/<name>/` but
+  // vault's `cmdCreate` still rejects "list" and cross-repo consistency
+  // is cheap.
+  "list",
+]);
+
+export type VaultNameValidation = { ok: true; name: string } | { ok: false; error: string };
+
+/**
+ * Validate a vault name against vault's strict contract. Trims
+ * surrounding whitespace before checking. Returns the trimmed name on
+ * success so callers don't double-trim.
+ */
+export function validateVaultName(raw: string): VaultNameValidation {
+  const name = raw.trim();
+  if (!name) {
+    return { ok: false, error: "vault name cannot be empty." };
+  }
+  if (name.length < VAULT_NAME_MIN_LEN || name.length > VAULT_NAME_MAX_LEN) {
+    return {
+      ok: false,
+      error: `vault names must be ${VAULT_NAME_MIN_LEN}–${VAULT_NAME_MAX_LEN} characters long.`,
+    };
+  }
+  if (!VAULT_NAME_RE.test(name)) {
+    return {
+      ok: false,
+      error: "vault names must be lowercase alphanumeric with hyphens or underscores.",
+    };
+  }
+  if (RESERVED_NAMES.has(name)) {
+    return { ok: false, error: `"${name}" is a reserved vault name.` };
+  }
+  return { ok: true, name };
+}
+
+/** The default vault name when the operator leaves the field blank. */
+export const DEFAULT_VAULT_NAME = "default";

package/src/vault-names.ts

@@ -0,0 +1,57 @@
+/**
+ * Vault-name list — the single source of truth for "which vault instances are
+ * registered on this hub right now."
+ *
+ * Multi-user Phase 1, PR 4 of 5 (design
+ * [`parachute.computer/design/2026-05-20-multi-user-phase-1.md`](https://parachute.computer/design/2026-05-20-multi-user-phase-1/)).
+ * Consolidates the two pre-PR-4 copies that read services.json and emitted
+ * vault names — one was private inside `oauth-handlers.ts` (used by the
+ * consent vault picker + post-consent narrowing), the other was private
+ * inside `api-users.ts` (used by `GET /api/users/vaults` for the admin SPA's
+ * assigned-vault dropdown + `POST /api/users` validation). PR 4 wires a third
+ * caller — server-side defense in `handleConsentSubmit` refusing mints
+ * whose picked vault disagrees with the user's `assigned_vault` — so the
+ * two private copies became three, and a duplicated read-and-derive helper
+ * for "what vaults exist" is exactly the shape that needs a single owner.
+ *
+ * Lives next to `well-known.ts` (which already owns `isVaultEntry` +
+ * `vaultInstanceNameFor`) rather than inside it: well-known's role is the
+ * `/.well-known/parachute.json` document shape, and a free-floating list
+ * helper would muddy that file's surface. Standalone module keeps the
+ * focused-purpose contract.
+ *
+ * Walks both manifest shapes: single-entry-multi-path (`parachute-vault`
+ * with `paths: ["/vault/work", "/vault/personal"]`) and per-vault entries
+ * (`parachute-vault-work`) by delegating each (name, path) pair to
+ * `vaultInstanceNameFor`. Entries with no paths still resolve to a name via
+ * the helper's manifest-suffix fallback (hub#143).
+ */
+import { type ServicesManifest, readManifest } from "./services-manifest.ts";
+import { isVaultEntry, vaultInstanceNameFor } from "./well-known.ts";
+
+/**
+ * Emit each vault instance's name from an in-memory manifest. Sorted output
+ * keeps callers (consent picker dropdown, admin SPA dropdown, server-side
+ * defense lookup) deterministic without each having to wrap in their own
+ * `.sort()`.
+ */
+export function listVaultNames(manifest: ServicesManifest): string[] {
+  const names = new Set<string>();
+  for (const svc of manifest.services) {
+    if (!isVaultEntry(svc)) continue;
+    const paths = svc.paths.length > 0 ? svc.paths : [undefined];
+    for (const path of paths) {
+      names.add(vaultInstanceNameFor(svc.name, path));
+    }
+  }
+  return Array.from(names).sort();
+}
+
+/**
+ * Read-from-disk convenience for callers that already have a manifest path
+ * (e.g. `/api/users/vaults` reading the live `services.json`). Equivalent to
+ * `listVaultNames(readManifest(manifestPath))`.
+ */
+export function listVaultNamesFromPath(manifestPath: string): string[] {
+  return listVaultNames(readManifest(manifestPath));
+}