@openparachute/hub 0.5.13 → 0.5.14-rc.10

package/src/api-modules.ts

@@ -3,10 +3,12 @@
  *
  * Combines three sources into a single per-module row:
  *
- *   - **Curated availability** — vault, notes, scribe, runner (the v0.6
- *     release bar). The Phase-2 marketplace will broaden this; for now
- *     it's hardcoded so the admin UI has a stable "what can I install?"
- *     list even on a fresh container where services.json is empty.
+ *   - **Curated availability** — vault, scribe (the launch focus per
+ *     Aaron 2026-05-27). The list was previously broader; trimmed for
+ *     the launch arc. The Phase-2 marketplace will broaden this; for
+ *     now it's hardcoded so the admin UI has a stable "what can I
+ *     install?" list even on a fresh container where services.json is
+ *     empty.
  *   - **Installed state** — services.json reads (version, installDir).
  *   - **Supervisor state** — per-module run status (`running` / `stopped`
  *     / `crashed` / `starting` / `restarting`) + pid. Absent when the
@@ -80,15 +82,30 @@ function lookupModule(
 export const API_MODULES_REQUIRED_SCOPE = "parachute:host:auth";
 
 /**
- * Curated module short-names for v0.6 Render self-host. Marketplace is
- * Phase 2 — until then, the admin UI offers exactly these. Order is the
- * recommended install order (vault → app → notes → scribe → runner;
- * app auto-bootstraps notes-ui on first boot — `notes` here is the
- * notes-daemon back-compat install path retained for operators still on
- * the pre-app architecture; scribe + runner come last because they
- * depend on a working vault + app to be useful).
+ * Curated module short-names. The admin UI offers exactly these for install
+ * + management. Order is the recommended install order (vault first, scribe
+ * second).
+ *
+ * Trimmed 2026-05-27 (Aaron-directed launch focus) from the prior set of
+ * `["vault", "surface", "notes", "scribe", "runner"]`. The dropped modules
+ * are still published on npm and still work — they're just not the focus:
+ *
+ *   - `notes` (notes-daemon): retired. Notes-UI now lives at
+ *     `notes.parachute.computer` as a hosted SPA — operators don't install
+ *     a notes daemon anymore. The npm package `@openparachute/notes-ui`
+ *     is a library imported by `parachute-surface` and by custom-surface
+ *     builders.
+ *   - `surface` (host module): de-emphasized. `@openparachute/surface-client`
+ *     remains the canonical library for folks building their own UIs
+ *     against a Parachute hub; running the surface-host module on your
+ *     own box is no longer the headline path (use notes.parachute.computer
+ *     or build your own).
+ *   - `runner`: experimental, not in the focus set for launch.
+ *
+ * Re-adding any of these is one line — keep the list small until use
+ * cases demand otherwise.
  */
-export const CURATED_MODULES = ["vault", "app", "notes", "scribe", "runner"] as const;
+export const CURATED_MODULES = ["vault", "scribe"] as const;
 export type CuratedModuleShort = (typeof CURATED_MODULES)[number];
 
 export interface ApiModulesDeps {
@@ -385,8 +402,8 @@ export async function handleApiModules(req: Request, deps: ApiModulesDeps): Prom
         //     (e.g. `/vault/default` + `/admin/` → `/vault/default/admin/`).
         //   - Single-instance modules (app, scribe, runner) declare a
         //     full hub-origin path that ALREADY includes the mount
-        //     (e.g. `/app/admin/`, `/scribe/admin`); the mount must NOT
-        //     be prepended again or the result is `/app/app/admin/`
+        //     (e.g. `/surface/admin/`, `/scribe/admin`); the mount must NOT
+        //     be prepended again or the result is `/app/surface/admin/`
         //     (the audit bug caught 2026-05-25 on the SPA's Services
         //     dropdown).
         // Detect by checking if candidate is already mount-prefixed.

package/src/api-ready.ts

@@ -0,0 +1,102 @@
+/**
+ * `GET /api/ready` — hub-side boot-readiness probe (hub#443).
+ *
+ * Public (no bearer required) — used by:
+ *
+ *   1. The transient-state HTML page rendered by the upstream-error
+ *      flow (see `proxy-error-ui.ts`). Its inline poll script hits this
+ *      endpoint every 2s up to 5 times so a wizard mid-boot can refresh
+ *      itself without an HTML reload.
+ *   2. Any third-party tool (smoke test, dashboard) that wants to know
+ *      whether the hub's modules are all up.
+ *
+ * Shape:
+ *
+ *     {
+ *       "ready": boolean,
+ *       "ready_modules": string[],         // shorts that are up
+ *       "transient_modules": string[],     // shorts currently booting
+ *       "persistent_modules": string[]     // shorts crashed / stopped
+ *     }
+ *
+ * `ready: true` iff every supervised module is in the "running" state
+ * past its boot window AND no module is in transient/persistent
+ * failure. The hub itself is implicit — if you reached this endpoint,
+ * hub is up.
+ *
+ * Why public: the page that polls this is itself served pre-auth (a
+ * 503 from a proxied request before the operator has even reached
+ * /login). Bearer-gating would make the poll fail and the page sit
+ * forever on "still loading."
+ */
+
+import { DEFAULT_BOOT_WINDOW_MS } from "./proxy-state.ts";
+import type { Supervisor } from "./supervisor.ts";
+
+export interface ApiReadyDeps {
+  /** Container-mode supervisor handle. When absent the hub is in CLI
+   *  mode and we report ready=true (we have no visibility into other
+   *  processes' boot state). */
+  supervisor?: Supervisor;
+  /** Test seam over Date.now. */
+  now?: () => number;
+  /** Test seam over the boot window. */
+  bootWindowMs?: number;
+}
+
+export function handleApiReady(req: Request, deps: ApiReadyDeps = {}): Response {
+  if (req.method !== "GET" && req.method !== "HEAD") {
+    return new Response("method not allowed", { status: 405 });
+  }
+  const now = (deps.now ?? Date.now)();
+  const bootWindow = deps.bootWindowMs ?? DEFAULT_BOOT_WINDOW_MS;
+
+  const ready: string[] = [];
+  const transient: string[] = [];
+  const persistent: string[] = [];
+
+  if (deps.supervisor) {
+    for (const m of deps.supervisor.list()) {
+      switch (m.status) {
+        case "starting":
+        case "restarting":
+          transient.push(m.short);
+          break;
+        case "crashed":
+        case "stopped":
+          persistent.push(m.short);
+          break;
+        case "running": {
+          // Inside the boot window we report transient even though the
+          // process is "running" — the listener may not have bound yet.
+          // After the window we report ready (process is up + presumed
+          // listening; if it's not, the proxy classifier still catches
+          // it via the same window check and surfaces persistent state).
+          let startedMs = 0;
+          if (m.startedAt) {
+            const parsed = Date.parse(m.startedAt);
+            if (Number.isFinite(parsed)) startedMs = parsed;
+          }
+          if (startedMs > 0 && now - startedMs < bootWindow) {
+            transient.push(m.short);
+          } else {
+            ready.push(m.short);
+          }
+          break;
+        }
+      }
+    }
+  }
+
+  const isReady = transient.length === 0 && persistent.length === 0;
+  const body = JSON.stringify({
+    ready: isReady,
+    ready_modules: ready,
+    transient_modules: transient,
+    persistent_modules: persistent,
+  });
+  return new Response(body, {
+    status: 200,
+    headers: { "content-type": "application/json", "cache-control": "no-store" },
+  });
+}

package/src/api-revoke-token.ts

@@ -1,38 +1,73 @@
 /**
  * `POST /api/auth/revoke-token` — HTTP companion to `parachute auth
- * revoke-token <jti>` (hub#221) and the missing piece behind the future
- * admin UI's revoke action.
+ * revoke-token <jti>` (hub#221) and the backing endpoint for the admin
+ * UI's revoke action. Closes hub#220.
  *
- * Same auth shape as `POST /api/auth/mint-token`: bearer-gated on
- * `parachute:host:auth` (admin scope-set tokens carry it as a superset;
- * narrow `--scope-set auth` operator tokens carry it directly). Closes
- * hub#220.
+ * Auth — capability attenuation, SYMMETRIC to mint-token (hub#452): you may
+ * revoke exactly what you could have minted. After validating the bearer
+ * (signature / issuer / expiry — same as today):
+ *
+ *   1. If the bearer holds `parachute:host:auth` → it may revoke ANY jti
+ *      (the original, broadest behavior — preserved unchanged).
+ *   2. Otherwise the bearer must clear the entry gate — it must hold at least
+ *      one minting authority (`parachute:host:auth`, `parachute:host:admin`,
+ *      or some `vault:<*>:admin`, via `hasMintingAuthority`). A bearer with
+ *      none (e.g. a read-only token) gets 403 up front — it can revoke
+ *      nothing, just as it can mint nothing.
+ *   3. The per-jti authority check then governs what such a bearer may
+ *      actually revoke: the target jti is revocable iff EVERY one of its
+ *      recorded scopes satisfies `canGrant(bearerScopes, scope)` — i.e. the
+ *      bearer could have minted that exact token. A `vault:work:admin` bearer
+ *      can revoke a `vault:work:write` or `vault:work:admin` jti, but NOT a
+ *      `vault:other:*` jti and NOT a `parachute:host:*` jti — the same
+ *      cross-vault / host-escalation walls mint enforces.
+ *
+ * Idempotency / no-info-leak: an UNKNOWN jti (no `tokens` row — never minted
+ * or already purged) returns the SAME 404 `not_found` the endpoint has always
+ * returned, for every caller including host:auth. The per-jti authority check
+ * only runs when the row is FOUND. So an attenuated bearer probing a jti it
+ * doesn't own cannot distinguish "exists but not yours" from "doesn't exist"
+ * by the unknown-jti path — it gets the identical 404 a host:auth bearer
+ * would. A jti that EXISTS but is out of the bearer's authority returns 403
+ * (and is NOT revoked): the caller already knows the jti string, so "exists
+ * but not yours" leaks nothing beyond what it already holds — and returning
+ * idempotent-ok there would be a lie (it revoked nothing).
  *
  * Body: `{ jti: string }`.
  *
- * Responses (matching the OAuth 2.0 error-shape vocabulary used by
- * mint-token and the rest of the hub's bearer-protected admin API):
+ * Responses (OAuth 2.0 error-shape vocabulary, matching mint-token):
  *
  *   - 200 `{ jti, revoked_at }` — success. Idempotent: re-revoking an
- *     already-revoked jti returns the existing `revoked_at` and 200,
- *     same as the CLI's exit-0-with-existing-timestamp behavior.
+ *     already-revoked jti returns the existing `revoked_at` and 200.
  *   - 400 `invalid_request` — missing/malformed body, missing jti.
  *   - 401 `unauthenticated` — missing or invalid bearer.
- *   - 403 `insufficient_scope` — bearer lacks `parachute:host:auth`.
+ *   - 403 `insufficient_scope` — bearer holds no minting authority (entry
+ *     gate), or the target jti carries a scope the bearer couldn't have
+ *     minted (per-jti authority check).
  *   - 404 `not_found` — no `tokens` row matches the jti.
  *   - 405 `method_not_allowed` — non-POST.
  *
  * Identity field in audit-friendly success: not echoed in the response
  * body (the JSON shape is intentionally minimal — `jti` + `revoked_at`
  * is all a UI consumer needs); operator-side audit lives in hub logs.
- * Mirrors the CLI's design where `identity=` was added for stdout but
- * the wire response stays narrow.
  */
 import type { Database } from "bun:sqlite";
 import { findTokenRowByJti, revokeTokenByJti, validateAccessToken } from "./jwt-sign.ts";
+import { MINT_HOST_AUTH_SCOPE, canGrant, hasMintingAuthority } from "./scope-attenuation.ts";
 
-/** Scope required on the bearer token to call this endpoint. */
-export const API_REVOKE_TOKEN_REQUIRED_SCOPE = "parachute:host:auth";
+/**
+ * Scope that authorises revoking ANY jti unconditionally (rule 1). A bearer
+ * without it may still revoke via attenuation (rule 3) if it clears the
+ * `hasMintingAuthority` entry gate.
+ */
+export const API_REVOKE_TOKEN_REQUIRED_SCOPE = MINT_HOST_AUTH_SCOPE;
+
+/**
+ * Maximum accepted length of a caller-supplied `jti`. A real jti is a UUID or
+ * short opaque token; anything materially longer is malformed input. Capping
+ * it keeps the verbatim-echoed value out of structured logs from bloating.
+ */
+export const MAX_JTI_LENGTH = 256;
 
 export interface ApiRevokeTokenDeps {
   db: Database;
@@ -80,12 +115,19 @@ export async function handleApiRevokeToken(
     return jsonError(401, "unauthenticated", `bearer token invalid — ${msg}`);
   }
 
-  // 3. Scope gate.
-  if (!bearerScopes.includes(API_REVOKE_TOKEN_REQUIRED_SCOPE)) {
+  // 3. Entry gate. A `parachute:host:auth` bearer may revoke anything
+  //    (rule 1) and skips the per-jti authority check below. Any other
+  //    bearer must hold SOME minting authority (host:admin or a
+  //    `vault:<*>:admin`) to attempt a revoke at all — a bearer with none
+  //    can revoke nothing under attenuation, so we 403 it here rather than
+  //    looking up the jti. Whether such a bearer may revoke a SPECIFIC jti
+  //    is decided per-jti in step 5 via `canGrant`.
+  const bearerHasHostAuth = bearerScopes.includes(API_REVOKE_TOKEN_REQUIRED_SCOPE);
+  if (!bearerHasHostAuth && !hasMintingAuthority(bearerScopes)) {
     return jsonError(
       403,
       "insufficient_scope",
-      `bearer token lacks ${API_REVOKE_TOKEN_REQUIRED_SCOPE}`,
+      `bearer token holds no revoke authority (need ${API_REVOKE_TOKEN_REQUIRED_SCOPE}, parachute:host:admin, or vault:<name>:admin)`,
     );
   }
 
@@ -103,15 +145,59 @@ export async function handleApiRevokeToken(
   if (typeof body.jti !== "string" || body.jti.length === 0) {
     return jsonError(400, "invalid_request", "jti is required and must be a non-empty string");
   }
+  // Cap the jti length. It's echoed verbatim into `error_description` and
+  // structured log lines; a real jti is a UUID/short token (well under 256
+  // chars), so a longer value is malformed input — reject it before it can
+  // bloat log lines. JSON-encoded responses already neutralize injection;
+  // this is a size guard, not an escaping one.
+  if (body.jti.length > MAX_JTI_LENGTH) {
+    return jsonError(400, "invalid_request", `jti exceeds ${MAX_JTI_LENGTH}-character maximum`);
+  }
   const jti = body.jti;
 
-  // 5. Lookup + revoke. Order: row-existence first (404 if missing), then
-  // attempt revoke. Idempotent: if already revoked, surface the existing
-  // revoked_at — same CLI semantics from hub#221.
+  // 5. Lookup + per-jti authority + revoke. Order: row-existence first
+  // (404 if missing — same response for every caller, no leak), then the
+  // attenuation authority check (for non-host:auth bearers), then attempt
+  // revoke. Idempotent: if already revoked, surface the existing revoked_at
+  // — same CLI semantics from hub#221.
   const existing = findTokenRowByJti(deps.db, jti);
   if (!existing) {
     return jsonError(404, "not_found", `no token with jti ${jti} found in registry`);
   }
+
+  // Per-jti authority (rule 3 / symmetric to mint attenuation). A host:auth
+  // bearer skips this — it may revoke anything. Any other bearer may revoke
+  // this jti only if EVERY one of its recorded scopes is one the bearer could
+  // have minted (`canGrant`). One out-of-authority scope (cross-vault, a
+  // host:* scope, etc.) blocks the whole revoke with 403 — and the token is
+  // left intact. The caller already knows the jti, so "exists but not yours"
+  // leaks nothing beyond what it holds; idempotent-ok would falsely imply a
+  // revoke happened.
+  if (!bearerHasHostAuth) {
+    // A scopeless target (recorded `scopes: []`) would otherwise pass the
+    // `canGrant` filter vacuously — `[].filter(...)` is empty, so
+    // `ungrantable.length === 0`. That's silently permissive: any bearer
+    // clearing the entry gate could revoke a zero-scope token. Such tokens
+    // shouldn't exist (the CLI/SPA never mint them), but if one does, only a
+    // host:auth bearer may revoke it — a non-host:auth bearer has no
+    // attenuation authority that "covers" the empty scope set.
+    if (existing.scopes.length === 0) {
+      return jsonError(
+        403,
+        "insufficient_scope",
+        `bearer token cannot revoke jti ${jti}: target has no recorded scopes (only ${API_REVOKE_TOKEN_REQUIRED_SCOPE} may revoke a scopeless token)`,
+      );
+    }
+    const ungrantable = existing.scopes.filter((s) => !canGrant(bearerScopes, s));
+    if (ungrantable.length > 0) {
+      return jsonError(
+        403,
+        "insufficient_scope",
+        `bearer token cannot revoke jti ${jti}: its scope(s) ${ungrantable.join(", ")} are outside the bearer's authority`,
+      );
+    }
+  }
+
   if (existing.revokedAt) {
     return ok({ jti, revoked_at: existing.revokedAt });
   }