@openparachute/hub 0.7.1 → 0.7.2

package/src/admin-lock.ts

@@ -0,0 +1,281 @@
+/**
+ * Optional idle screen-lock for the hub ADMIN UI (phone-style lock).
+ *
+ * ## What this guards (and what it deliberately doesn't)
+ *
+ * The hub admin UI is reachable remotely once `parachute expose` is up
+ * (Tailscale / Cloudflare). A grabbed or left-logged-in admin browser session
+ * is a real risk: the password-login session cookie lasts 24h, so an
+ * unattended tab is a standing admin console. This adds an OPTIONAL operator
+ * PIN that LOCKS THE WHOLE ADMIN SURFACE — one lock over everything, not
+ * per-action gating (per-action would friction-up configuration, which is the
+ * dangerous stuff we most want behind the lock anyway). Unlock with the PIN →
+ * a frictionless working window; admin activity refreshes it; idle re-locks.
+ *
+ * THREAT MODEL: this is a WEB/UI-layer guard for the EXPOSED admin portal. It
+ * does NOT protect against someone with a SHELL on the box — they read
+ * `~/.parachute/operator.token` / the vault DB directly and bypass the hub
+ * entirely. That's an OS concern (disk encryption, a locked OS screen, SSH-key
+ * hygiene). The lock shuts the *portal* door — the one the internet can reach —
+ * which is the point.
+ *
+ * ## The single chokepoint
+ *
+ * The admin SPA + every module config UI get their working Bearer from one of
+ * the cookie-gated mint endpoints:
+ *   - `GET /admin/host-admin-token`        (the SPA's own Bearer)
+ *   - `GET /admin/agent-token`             (agent chat + config UIs)
+ *   - `GET /admin/vault-admin-token/<name>`(per-vault admin SPA)
+ *   - `GET /admin/module-token/<short>`    (generic module config UI Bearer)
+ *
+ * All four share the exact `parseSessionCookie → findSession → [isFirstAdmin]
+ * → signAccessToken` shape. Inserting {@link requireUnlocked} into each makes
+ * the lock cascade to EVERY admin surface with no per-module changes: when
+ * locked, the mint returns 423 and the relevant UI shows the lock screen / its
+ * admin calls fail closed (no Bearer). A surface OAuth'ing in via `/oauth/*`
+ * never touches these endpoints, so the OAuth issuer is untouched — see the
+ * design note (`design/2026-06-17-admin-ui-lock.md`).
+ *
+ * ## Unlock state — per-session, in-memory, "unlocked-until"
+ *
+ * Simplest workable model. A successful PIN unlock records `unlockedUntil` for
+ * the session id (the cookie value) in a process-local Map. The session is
+ * UNLOCKED iff a future `unlockedUntil` exists; genuine USER activity (the SPA's
+ * debounced `/heartbeat`, fired on pointer/key/scroll) slides it forward by the
+ * idle window. Token mints do NOT slide it — the SPA polls some endpoints in the
+ * background, and letting a poll's re-mint extend the window would keep an
+ * idle-but-open tab unlocked forever. LOCKED when:
+ *   - no PIN is set → feature OFF, never locked (today's behavior);
+ *   - PIN set + no unlock recorded (fresh load / first visit);
+ *   - PIN set + the recorded unlock is in the past (idle-expired);
+ *   - a hub restart wipes the Map → re-lock (a feature, not a bug).
+ *
+ * The unlock state is NEVER persisted and NEVER put in the cookie — a stolen
+ * cookie alone can't carry an unlocked window; the attacker still needs the
+ * PIN. (The cookie already authenticates the password session; the PIN is the
+ * second, idle-bounded gate on top.)
+ */
+import type { Database } from "bun:sqlite";
+import { hash as argonHash, verify as argonVerify } from "@node-rs/argon2";
+import { deleteSetting, getSetting, setSetting } from "./hub-settings.ts";
+import { RateLimiter } from "./rate-limit.ts";
+
+/** Default idle window before a session re-locks. Phone-lock territory. */
+export const DEFAULT_ADMIN_LOCK_IDLE_SECONDS = 15 * 60;
+
+/** Clamp on the operator-configurable idle window: 1 min … 24h. */
+export const MIN_ADMIN_LOCK_IDLE_SECONDS = 60;
+export const MAX_ADMIN_LOCK_IDLE_SECONDS = 24 * 60 * 60;
+
+/**
+ * PIN format: 4–12 digits. A numeric PIN is the phone-lock affordance the
+ * feature is named for; the real defense is the idle window + brute-force
+ * limiter, not PIN entropy (the session is already password-authenticated —
+ * this is a second, convenience-grade gate). Operators wanting a full secret
+ * use the OS lock / a strong account password; this is the "don't leave the
+ * console open on the train" guard.
+ */
+export const ADMIN_LOCK_PIN_RE = /^[0-9]{4,12}$/;
+
+export type ValidatePinResult = { valid: true } | { valid: false; reason: "format" };
+
+export function validatePin(pin: string): ValidatePinResult {
+  return ADMIN_LOCK_PIN_RE.test(pin) ? { valid: true } : { valid: false, reason: "format" };
+}
+
+// --- PIN storage (argon2id hash in hub_settings) ---------------------------
+
+/** True iff an admin-lock PIN is configured (feature is ON). */
+export function isLockConfigured(db: Database): boolean {
+  const h = getSetting(db, "admin_lock_pin_hash");
+  return typeof h === "string" && h.length > 0;
+}
+
+/**
+ * Store (or rotate) the PIN. Hashes with argon2id — the same family the hub
+ * already uses for passwords + TOTP backup codes (`@node-rs/argon2`). The
+ * caller MUST have validated the PIN format first; this trusts its input.
+ */
+export async function setPin(db: Database, pin: string): Promise<void> {
+  const h = await argonHash(pin);
+  setSetting(db, "admin_lock_pin_hash", h);
+}
+
+/** Remove the PIN (turn the feature OFF). Idempotent. Also clears idle config. */
+export function clearPin(db: Database): void {
+  deleteSetting(db, "admin_lock_pin_hash");
+  deleteSetting(db, "admin_lock_idle_seconds");
+}
+
+/**
+ * Verify a submitted PIN against the stored hash. Returns false when no PIN is
+ * configured (defensive — callers gate on {@link isLockConfigured} first) or
+ * the hash is malformed.
+ */
+export async function verifyPin(db: Database, pin: string): Promise<boolean> {
+  const h = getSetting(db, "admin_lock_pin_hash");
+  if (typeof h !== "string" || h.length === 0) return false;
+  try {
+    return await argonVerify(h, pin);
+  } catch {
+    // Corrupt/unparseable hash — fail closed.
+    return false;
+  }
+}
+
+// --- idle window config ----------------------------------------------------
+
+/** Read the configured idle window (clamped). Falls back to the default. */
+export function getIdleSeconds(db: Database): number {
+  const raw = getSetting(db, "admin_lock_idle_seconds");
+  if (typeof raw !== "string") return DEFAULT_ADMIN_LOCK_IDLE_SECONDS;
+  const n = Number.parseInt(raw, 10);
+  if (!Number.isFinite(n)) return DEFAULT_ADMIN_LOCK_IDLE_SECONDS;
+  return clampIdleSeconds(n);
+}
+
+export function clampIdleSeconds(n: number): number {
+  if (n < MIN_ADMIN_LOCK_IDLE_SECONDS) return MIN_ADMIN_LOCK_IDLE_SECONDS;
+  if (n > MAX_ADMIN_LOCK_IDLE_SECONDS) return MAX_ADMIN_LOCK_IDLE_SECONDS;
+  return Math.floor(n);
+}
+
+/** Persist the operator's idle-window choice (clamped). */
+export function setIdleSeconds(db: Database, seconds: number): void {
+  setSetting(db, "admin_lock_idle_seconds", String(clampIdleSeconds(seconds)));
+}
+
+// --- per-session unlock state (in-memory, never persisted) -----------------
+
+/**
+ * sessionId → unlockedUntil epoch ms. Process-local; a restart wipes it (which
+ * is the re-lock-on-fresh-process behavior we want). Bounded by an
+ * opportunistic prune of expired rows on every touch, so an attacker churning
+ * session ids can't grow it unboundedly.
+ */
+const unlockedUntil = new Map<string, number>();
+
+function pruneExpired(now: number): void {
+  for (const [sid, until] of unlockedUntil) {
+    if (until <= now) unlockedUntil.delete(sid);
+  }
+}
+
+/**
+ * Record a fresh unlock for `sessionId`, valid for `idleSeconds` from now.
+ * Called after a successful PIN verify.
+ */
+export function recordUnlock(
+  sessionId: string,
+  idleSeconds: number,
+  now: number = Date.now(),
+): void {
+  pruneExpired(now);
+  unlockedUntil.set(sessionId, now + idleSeconds * 1000);
+}
+
+/**
+ * Slide the unlock window forward by `idleSeconds` IF the session is currently
+ * unlocked. Called on admin activity (heartbeat + every successful mint) so an
+ * actively-used console doesn't lock mid-work. Does NOT create an unlock for a
+ * locked session — only an explicit PIN entry can do that.
+ */
+export function refreshActivity(
+  sessionId: string,
+  idleSeconds: number,
+  now: number = Date.now(),
+): void {
+  const until = unlockedUntil.get(sessionId);
+  if (until === undefined || until <= now) return; // locked — activity doesn't unlock
+  unlockedUntil.set(sessionId, now + idleSeconds * 1000);
+}
+
+/** Is this session currently within an unlock window? */
+export function isSessionUnlocked(sessionId: string, now: number = Date.now()): boolean {
+  const until = unlockedUntil.get(sessionId);
+  return until !== undefined && until > now;
+}
+
+/** Force-lock a session immediately ("Lock now"). Idempotent. */
+export function lockSession(sessionId: string): void {
+  unlockedUntil.delete(sessionId);
+}
+
+/** Remaining unlock seconds for a session (0 when locked). For status UI. */
+export function unlockSecondsRemaining(sessionId: string, now: number = Date.now()): number {
+  const until = unlockedUntil.get(sessionId);
+  if (until === undefined || until <= now) return 0;
+  return Math.ceil((until - now) / 1000);
+}
+
+/** Test seam: wipe all in-memory unlock state. */
+export function _resetUnlockStateForTest(): void {
+  unlockedUntil.clear();
+}
+
+// --- the gate the four token-mint chokepoints call -------------------------
+
+/**
+ * The single lock gate. Returns whether the mint may proceed.
+ *
+ *   - feature OFF (no PIN) → ALWAYS allow (today's behavior, byte-for-byte).
+ *   - feature ON + session unlocked → allow.
+ *   - feature ON + session locked → DENY (the caller returns 423 Locked).
+ *
+ * Deliberately a PURE CHECK — it does NOT slide the idle window. Sliding is
+ * driven exclusively by genuine USER activity (the SPA's debounced
+ * `/heartbeat`, fired on pointer/key/scroll), NOT by token mints. The SPA polls
+ * some endpoints in the background (e.g. the version badge every 30s), and each
+ * such poll re-mints a host-admin Bearer; if a mint extended the window, a
+ * left-open-but-idle tab would never lock — defeating the whole feature. The
+ * heartbeat is the one thing that means "a human is here."
+ *
+ * `now` is injectable for tests.
+ */
+export function requireUnlocked(
+  db: Database,
+  sessionId: string,
+  now: number = Date.now(),
+): { ok: true } | { ok: false; reason: "locked" } {
+  if (!isLockConfigured(db)) return { ok: true };
+  if (isSessionUnlocked(sessionId, now)) {
+    return { ok: true };
+  }
+  return { ok: false, reason: "locked" };
+}
+
+/** RFC-shaped 423 the mint chokepoints return when locked. */
+export function lockedResponse(): Response {
+  return new Response(
+    JSON.stringify({
+      error: "locked",
+      error_description:
+        "the admin UI is locked — enter your PIN to unlock (POST /api/admin-lock/unlock)",
+    }),
+    {
+      status: 423,
+      headers: {
+        "content-type": "application/json",
+        "cache-control": "no-store",
+      },
+    },
+  );
+}
+
+// --- unlock brute-force limiter --------------------------------------------
+
+/**
+ * Per-session unlock-attempt limiter. The unlock endpoint is session-gated, so
+ * the threat is a compromised session (stolen cookie) grinding argon2id PIN
+ * verifications without bound — keyed by session id, same posture as
+ * `/account/change-password` (keyed by user). 5 wrong PINs / 5 min is the
+ * floor; the idle window + the limiter together are the real defense (the PIN
+ * itself is convenience-grade — see the module header).
+ */
+export const ADMIN_LOCK_UNLOCK_MAX_ATTEMPTS = 5;
+export const ADMIN_LOCK_UNLOCK_WINDOW_MS = 5 * 60 * 1000;
+
+export const unlockLimiter = new RateLimiter(
+  ADMIN_LOCK_UNLOCK_MAX_ATTEMPTS,
+  ADMIN_LOCK_UNLOCK_WINDOW_MS,
+);

package/src/admin-module-token.ts

@@ -8,15 +8,15 @@
  * hub frames/links those surfaces consistently (the Modules page "Configure"
  * action). Each module-owned config UI, served behind the hub proxy to a
  * logged-in portal operator, needs an admin-scoped hub Bearer to call its own
- * `<short>:admin`-gated endpoints — the same shape the channel config UI gets
- * from `/admin/channel-token` and the vault admin SPA gets from
+ * `<short>:admin`-gated endpoints — the same shape the agent config UI gets
+ * from `/admin/agent-token` and the vault admin SPA gets from
  * `/admin/vault-admin-token/<name>`. This is the GENERIC mint that covers every
  * other self-registered single-audience module, so the hub doesn't grow a
  * bespoke per-module mint endpoint as each module ships a config UI.
  *
  * Scope + audience: `<short>:admin`, audience = `<short>` (the bare service
  * prefix). Modules validate the JWT's `aud` against their literal short name
- * (`scribe`, `runner`, `surface`, `channel`) — the same shape `inferAudience`
+ * (`scribe`, `runner`, `surface`, `agent`) — the same shape `inferAudience`
  * stamps for the public OAuth flow, so a hub-minted and an OAuth-minted admin
  * token are indistinguishable to the module. This mirrors the per-request
  * `<short>:admin` proxy token `api-modules-config.ts` used to mint; the
@@ -32,13 +32,14 @@
  *
  * Gate: the session must belong to the first admin (the single hub admin under
  * the Phase 1 multi-user model — `users.ts:isFirstAdmin`), exactly like
- * host-admin-token / vault-admin-token / channel-token. A friend account holds
+ * host-admin-token / vault-admin-token / agent-token. A friend account holds
  * a valid session but must not mint a module admin Bearer.
  *
  * Tokens are short-lived (10 min — matches the sibling admin-token mints); the
  * config UI re-fetches on near-expiry.
  */
 import type { Database } from "bun:sqlite";
+import { lockedResponse, requireUnlocked } from "./admin-lock.ts";
 import { signAccessToken } from "./jwt-sign.ts";
 import {
   type ModuleManifest,
@@ -49,7 +50,7 @@ import type { ServiceEntry } from "./services-manifest.ts";
 import { findSession, parseSessionCookie } from "./sessions.ts";
 import { isFirstAdmin } from "./users.ts";
 
-/** Short TTL — matches host/vault/channel admin-token. UI re-fetches on near-expiry. */
+/** Short TTL — matches host/vault/agent admin-token. UI re-fetches on near-expiry. */
 export const MODULE_TOKEN_TTL_SECONDS = 10 * 60;
 const MODULE_TOKEN_CLIENT_ID = "parachute-hub-spa";
 
@@ -143,10 +144,10 @@ export async function handleModuleToken(
   }
   const sid = parseSessionCookie(req.headers.get("cookie"));
   const session = sid ? findSession(deps.db, sid) : null;
-  if (!session) {
+  if (!session || !sid) {
     return jsonError(401, "unauthenticated", "no admin session — sign in at /login first");
   }
-  // First-admin gate (mirrors host/vault/channel-admin-token). A friend account
+  // First-admin gate (mirrors host/vault/agent-admin-token). A friend account
   // (non-first-admin user) holds a valid session but must not mint a module
   // admin Bearer.
   if (!isFirstAdmin(deps.db, session.userId)) {
@@ -156,6 +157,13 @@ export async function handleModuleToken(
       "module admin token mint is restricted to the hub admin — your account home is at /account/",
     );
   }
+  // Admin screen-lock gate (see admin-host-admin-token.ts). A locked admin
+  // session can't mint a module admin Bearer, so every module-owned config UI
+  // fails closed until the operator unlocks. This is what makes the lock
+  // cascade to ALL modules with zero per-module changes. Off by default.
+  if (!requireUnlocked(deps.db, sid).ok) {
+    return lockedResponse();
+  }
   const scope = `${short}:admin`;
   const minted = await signAccessToken(deps.db, {
     sub: session.userId,

package/src/admin-vault-admin-token.ts

@@ -25,6 +25,7 @@
  * for their assigned vault; they don't get vault admin via this endpoint.
  */
 import type { Database } from "bun:sqlite";
+import { lockedResponse, requireUnlocked } from "./admin-lock.ts";
 import { signAccessToken } from "./jwt-sign.ts";
 import { findSession, parseSessionCookie } from "./sessions.ts";
 import { isFirstAdmin } from "./users.ts";
@@ -66,7 +67,7 @@ export async function handleVaultAdminToken(
   }
   const sid = parseSessionCookie(req.headers.get("cookie"));
   const session = sid ? findSession(deps.db, sid) : null;
-  if (!session) {
+  if (!session || !sid) {
     return jsonError(401, "unauthenticated", "no admin session — sign in at /login first");
   }
   // Multi-user Phase 1 privesc gate (mirrors host-admin-token). vault:<name>:admin
@@ -80,6 +81,12 @@ export async function handleVaultAdminToken(
       "vault admin token mint is restricted to the hub admin — your account home is at /account/",
     );
   }
+  // Admin screen-lock gate (see admin-host-admin-token.ts). A locked admin
+  // session can't mint a vault admin Bearer, so the vault admin SPA fails
+  // closed until the operator unlocks. Off by default.
+  if (!requireUnlocked(deps.db, sid).ok) {
+    return lockedResponse();
+  }
   const scope = `vault:${vaultName}:admin`;
   // Per-vault audience: vault validates the JWT's `aud` claim against
   // `vault.<name>` derived from its own URL-bound config (vault src/auth.ts

package/src/admin-vaults.ts

@@ -537,8 +537,8 @@ export interface DeleteVaultDeps {
   manifestPath?: string;
   /** Absolute path to `connections.json` in the hub state dir. */
   connectionsStorePath: string;
-  /** Loopback origin for the channel daemon, or `null` when not installed. */
-  channelOrigin: string | null;
+  /** Loopback origin for the agent daemon, or `null` when not installed. */
+  agentOrigin: string | null;
   /** Resolve a vault's loopback origin from services.json (trigger teardown). */
   resolveVaultOrigin: (vaultName: string) => string | null;
   /**
@@ -651,7 +651,7 @@ function listVaultInstanceNames(manifestPath: string): Set<string> {
  *      the name);
  *   5. connections whose source/provisioned vault is the deleted vault
  *      (via `teardownConnection`, which post-B0 also revokes the registered
- *      long-lived mints) + a report-only scan of channel's `/api/channels`
+ *      long-lived mints) + a report-only scan of the agent's `/api/channels`
  *      for legacy vault-backed entries (`orphaned_channels`);
  *   6. mechanics: shell to `parachute-vault remove <name> --yes` (the module
  *      CLI stays the single source of truth for vault destruction,
@@ -764,7 +764,7 @@ export async function handleDeleteVault(
     ...(deps.resolveModuleOrigin !== undefined
       ? { resolveModuleOrigin: deps.resolveModuleOrigin }
       : {}),
-    channelOrigin: deps.channelOrigin,
+    agentOrigin: deps.agentOrigin,
     storePath: deps.connectionsStorePath,
     ...(deps.fetchImpl !== undefined ? { fetchImpl: deps.fetchImpl } : {}),
     ...(deps.now !== undefined ? { now: deps.now } : {}),
@@ -797,9 +797,9 @@ export async function handleDeleteVault(
 
   // Legacy channel scan — vault-backed channel entries still referencing the
   // vault after connection teardown (pre-Connections wiring). REPORT ONLY:
-  // channel's config is the channel module's domain; the operator removes
-  // them from channel's own UI.
-  if (deps.channelOrigin !== null) {
+  // the channel config is the agent module's domain; the operator removes
+  // them from the agent's own UI.
+  if (deps.agentOrigin !== null) {
     try {
       const fetchImpl = deps.fetchImpl ?? fetch;
       // Short-lived (60s) — stays below the registered-mint threshold by
@@ -808,8 +808,8 @@ export async function handleDeleteVault(
       const scanToken = (
         await signAccessToken(deps.db, {
           sub: adminSub,
-          scopes: ["channel:admin"],
-          audience: "channel",
+          scopes: ["agent:admin"],
+          audience: "agent",
           clientId: DELETE_VAULT_CLIENT_ID,
           issuer: deps.issuer,
           ttlSeconds: DELETE_VAULT_PROVISION_TTL_SECONDS,
@@ -817,7 +817,7 @@ export async function handleDeleteVault(
           ...(deps.now !== undefined ? { now: deps.now } : {}),
         })
       ).token;
-      const res = await fetchImpl(`${deps.channelOrigin}/api/channels`, {
+      const res = await fetchImpl(`${deps.agentOrigin}/api/channels`, {
         headers: { authorization: `Bearer ${scanToken}`, accept: "application/json" },
       });
       if (res.ok) {
@@ -830,11 +830,11 @@ export async function handleDeleteVault(
           }
         }
       } else {
-        warnings.push({ step: "channel_scan", detail: `channel list returned ${res.status}` });
+        warnings.push({ step: "agent_scan", detail: `agent channel list returned ${res.status}` });
       }
     } catch (err) {
       warnings.push({
-        step: "channel_scan",
+        step: "agent_scan",
         detail: err instanceof Error ? err.message : String(err),
       });
     }