@openparachute/hub 0.5.14-rc.9 → 0.6.0

package/src/pending-login.ts

@@ -0,0 +1,116 @@
+/**
+ * Pending-login state for the two-step TOTP login (hub#473).
+ *
+ * When a user with 2FA enrolled posts a correct username+password to `/login`,
+ * we do NOT mint a session yet — the user still has to prove the second
+ * factor. We stash the half-authenticated state under an opaque token and hand
+ * the browser a short-lived `parachute_hub_pending_login` cookie. The user
+ * then posts their TOTP / backup code to `/login/2fa`, which looks up the
+ * pending state, verifies the factor, and only then mints the real session.
+ *
+ * Storage: a process-local Map with per-entry expiry — same posture as the
+ * rate-limiter (`rate-limit.ts`). Persistence isn't worth a DB write: the
+ * window is 5 minutes, and a process restart simply forces the user to
+ * re-enter their password (the password POST is cheap to repeat, and losing
+ * an in-flight half-login on restart is fine — no security regression). This
+ * also avoids a second schema migration for a 5-minute-lived ephemeral row.
+ *
+ * The token is a 32-byte base64url random (same shape as a session id), so it
+ * is unguessable and opaque to the client. It carries no claims — everything
+ * is server-side in the Map.
+ */
+import { randomBytes } from "node:crypto";
+import { isHttpsRequest } from "./request-protocol.ts";
+
+export const PENDING_LOGIN_COOKIE_NAME = "parachute_hub_pending_login";
+/** Pending logins are valid for 5 minutes — long enough to open an
+ *  authenticator app, short enough to bound a half-authenticated window. */
+export const PENDING_LOGIN_TTL_MS = 5 * 60 * 1000;
+
+interface PendingLogin {
+  userId: string;
+  /** The post-2FA redirect target resolved at password-verify time. */
+  next: string;
+  /** Absolute expiry (ms epoch). */
+  expiresAtMs: number;
+}
+
+const pending = new Map<string, PendingLogin>();
+
+function gc(nowMs: number): void {
+  for (const [token, p] of pending) {
+    if (p.expiresAtMs <= nowMs) pending.delete(token);
+  }
+}
+
+/**
+ * Create a pending-login entry and return its opaque token. The caller sets
+ * the token as a cookie on the "enter your code" response.
+ */
+export function createPendingLogin(
+  userId: string,
+  next: string,
+  now: () => Date = () => new Date(),
+): string {
+  const nowMs = now().getTime();
+  gc(nowMs);
+  const token = randomBytes(32).toString("base64url");
+  pending.set(token, { userId, next, expiresAtMs: nowMs + PENDING_LOGIN_TTL_MS });
+  return token;
+}
+
+/**
+ * Resolve a pending-login token to its state, or null if absent/expired.
+ * Does NOT consume — the caller consumes only after the second factor
+ * verifies (so a failed 2FA attempt can retry against the same pending login
+ * without re-entering the password).
+ */
+export function getPendingLogin(
+  token: string | null,
+  now: () => Date = () => new Date(),
+): { userId: string; next: string } | null {
+  if (!token) return null;
+  const nowMs = now().getTime();
+  gc(nowMs);
+  const p = pending.get(token);
+  if (!p) return null;
+  if (p.expiresAtMs <= nowMs) {
+    pending.delete(token);
+    return null;
+  }
+  return { userId: p.userId, next: p.next };
+}
+
+/** Delete a pending-login entry (after successful 2FA, or on cancel). Idempotent. */
+export function consumePendingLogin(token: string | null): void {
+  if (token) pending.delete(token);
+}
+
+/** Test-only: clear all pending logins between cases. */
+export function _resetPendingLogins(): void {
+  pending.clear();
+}
+
+export function buildPendingLoginCookie(token: string, req: Request): string {
+  const parts = [`${PENDING_LOGIN_COOKIE_NAME}=${token}`, "HttpOnly"];
+  if (isHttpsRequest(req)) parts.push("Secure");
+  // Path=/login so the cookie only rides /login and /login/2fa requests.
+  parts.push("SameSite=Lax", "Path=/login", `Max-Age=${Math.floor(PENDING_LOGIN_TTL_MS / 1000)}`);
+  return parts.join("; ");
+}
+
+export function buildPendingLoginClearCookie(req: Request): string {
+  const parts = [`${PENDING_LOGIN_COOKIE_NAME}=`, "HttpOnly"];
+  if (isHttpsRequest(req)) parts.push("Secure");
+  parts.push("SameSite=Lax", "Path=/login", "Max-Age=0");
+  return parts.join("; ");
+}
+
+export function parsePendingLoginCookie(cookieHeader: string | null): string | null {
+  if (!cookieHeader) return null;
+  for (const part of cookieHeader.split(";")) {
+    const [name, ...rest] = part.trim().split("=");
+    if (name === PENDING_LOGIN_COOKIE_NAME) return rest.join("=");
+  }
+  return null;
+}

package/src/rate-limit.ts

@@ -81,6 +81,34 @@ 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;
+/**
+ * `/login/2fa` window length: 15 minutes — same as `/login`. The second-
+ * factor step (hub#473) sits behind a verified password + a short-lived
+ * pending-login token, so the threat model is "attacker who already has the
+ * password grinding 6-digit codes / backup codes." A 5-attempt / 15-min
+ * bucket per IP turns 10^6-space TOTP grinding into "rotate IPs," same floor
+ * as `/login`. Keyed by IP (the pending-login token is short-lived and an
+ * attacker could mint many, so IP is the stable actor key here).
+ */
+export const TOTP_WINDOW_MS = 15 * 60 * 1000;
+/** `/login/2fa` attempts allowed per window. 6th within the window is denied. */
+export const TOTP_MAX_ATTEMPTS = 5;
+/**
+ * `POST /account/vault-token/<name>` window length: 10 minutes. The endpoint
+ * is session-gated and assignment-capped (a friend can only mint
+ * `vault:<assigned>:read|write`), so this limiter isn't the primary defense —
+ * it's a floor that stops a compromised session (stolen cookie) from
+ * machine-gunning the registry with mint rows. Keyed by user-id (identity is
+ * established by the session before the limiter is reached), same posture as
+ * the change-password limiter.
+ */
+export const VAULT_TOKEN_MINT_WINDOW_MS = 10 * 60 * 1000;
+/**
+ * `POST /account/vault-token/<name>` attempts allowed per window. A friend
+ * minting a token for a script does it a handful of times at most; 10 per 10
+ * minutes is generous for a human and still chokes a stolen-cookie flood.
+ */
+export const VAULT_TOKEN_MINT_MAX_ATTEMPTS = 10;
 /** Sentinel for the IP-extraction priority chain when nothing parsed. */
 export const UNKNOWN_IP_SENTINEL = "unknown";
 
@@ -197,6 +225,27 @@ export const changePasswordRateLimiter = new RateLimiter(
   CHANGE_PASSWORD_WINDOW_MS,
 );
 
+/**
+ * `/login/2fa` rate limiter — per-IP, 5 attempts / 15 min (hub#473). Bounds
+ * second-factor grinding by an attacker who already has the password. Separate
+ * bucket from `/login` so a password failure and a TOTP failure don't share a
+ * window — but both are per-IP so rotating egress IPs is the only escape, same
+ * as the password floor.
+ */
+export const totpRateLimiter = new RateLimiter(TOTP_MAX_ATTEMPTS, TOTP_WINDOW_MS);
+
+/**
+ * `POST /account/vault-token/<name>` rate limiter — per-user, 10 attempts /
+ * 10 min (friend vault-token mint). Keyed by user-id (session-gated endpoint,
+ * identity established before this limiter is reached). Separate bucket from
+ * change-password so a token-mint flurry and a password-change flurry don't
+ * share a window.
+ */
+export const vaultTokenMintRateLimiter = new RateLimiter(
+  VAULT_TOKEN_MINT_MAX_ATTEMPTS,
+  VAULT_TOKEN_MINT_WINDOW_MS,
+);
+
 /**
  * Backwards-compat shim for hub#188's call sites: the original
  * top-level `checkAndRecord` was the login limiter. New code should
@@ -215,6 +264,8 @@ export function checkAndRecord(key: string, now: Date): RateLimitResult {
 export function __resetForTests(): void {
   loginRateLimiter.reset();
   changePasswordRateLimiter.reset();
+  totpRateLimiter.reset();
+  vaultTokenMintRateLimiter.reset();
 }
 
 /**

package/src/resource-binding.ts

@@ -0,0 +1,134 @@
+/**
+ * RFC 8707 (Resource Indicators for OAuth 2.0) resource-binding helpers.
+ *
+ * An MCP client connecting to a single vault (`<origin>/vault/<name>/mcp`)
+ * discovers the hub as its authorization server via the RFC 9728 challenge
+ * (`WWW-Authenticate: Bearer resource_metadata=…`) → per-vault Protected
+ * Resource Metadata. A spec-following client then sends the `resource`
+ * parameter on `/oauth/authorize` naming that exact MCP endpoint.
+ *
+ * Before this module the hub dropped `resource` on the floor: the consent
+ * screen advertised the ENTIRE scope catalog (every vault + hub:admin +
+ * scribe:admin …) and the minted token's audience was derived purely from
+ * the operator's manual vault-picker choice. Two failures fell out:
+ *
+ *   1. Scary consent — a friend connecting to ONE vault saw the whole hub's
+ *      scope surface.
+ *   2. Broad-scope rejection — an unnamed `vault:read` token (the shape a
+ *      client gets when it never picks a specific vault) is REJECTED by a
+ *      current-line vault (`findBroadVaultScopes`), because hub-issued tokens
+ *      must carry resource-narrowed `vault:<name>:<verb>` scopes + a matching
+ *      `aud=vault.<name>`.
+ *
+ * This module consumes `resource` end-to-end: when it resolves to a per-vault
+ * MCP resource we derive `<name>`, narrow the consent scope list to that
+ * vault's named scopes, lock the picker to `<name>`, and mint named scopes so
+ * `inferAudience` stamps `aud=vault.<name>`.
+ *
+ * Source of truth for scope shape: `parachute-patterns/patterns/oauth-scopes.md`.
+ */
+
+import { VAULT_VERBS } from "./jwt-audience.ts";
+
+/**
+ * Two recognised per-vault resource shapes, both rooted at the hub origin:
+ *
+ *   - the MCP endpoint:  `<origin>/vault/<name>/mcp`  (the canonical RFC 8707
+ *     resource indicator the PRM `resource` field advertises and a spec-
+ *     following client echoes back);
+ *   - the PRM document:  `<origin>/vault/<name>/.well-known/oauth-protected-resource`
+ *     (some clients send the metadata URL itself as the resource).
+ *
+ * A trailing slash and any query/fragment are tolerated. Capture group 1 is
+ * the vault instance name (same `[^/]+` shape `vaultInstanceNameFor` derives
+ * from a `/vault/<name>` path).
+ */
+const VAULT_MCP_PATH_RE = /^\/vault\/([^/]+)\/mcp\/?$/;
+const VAULT_PRM_PATH_RE = /^\/vault\/([^/]+)\/\.well-known\/oauth-protected-resource\/?$/;
+
+/**
+ * Resolve the RFC 8707 `resource` parameter to a vault instance name, or null
+ * when it isn't a per-vault MCP resource (absent, malformed, off-origin, or a
+ * non-vault path). Off-origin resources return null deliberately: we only
+ * narrow consent for resources the hub itself fronts, so a `resource` naming
+ * some third party's URL can't drive the vault-narrowing path.
+ *
+ * `boundOrigins` is the hub's own origin set (issuer + loopback + tailnet +
+ * funnel — same set the same-origin CSRF gate uses). A resource whose origin
+ * isn't in that set is treated as not-ours.
+ *
+ * The vault name is NOT validated against the live services.json here — that
+ * check stays where it already lives (the consent picker / submit defenses).
+ * This helper's only job is shape recognition + name extraction.
+ */
+export function resolveResourceVault(
+  resource: string | null | undefined,
+  boundOrigins: readonly string[],
+): string | null {
+  if (!resource) return null;
+  let parsed: URL;
+  try {
+    parsed = new URL(resource);
+  } catch {
+    return null;
+  }
+  if (!boundOrigins.includes(parsed.origin)) return null;
+  const mcp = VAULT_MCP_PATH_RE.exec(parsed.pathname);
+  if (mcp?.[1]) return decodeVaultName(mcp[1]);
+  const prm = VAULT_PRM_PATH_RE.exec(parsed.pathname);
+  if (prm?.[1]) return decodeVaultName(prm[1]);
+  return null;
+}
+
+/** Canonical vault-name shape — mirrors `VAULT_SCOPED_RE`'s name group. */
+const VAULT_NAME_RE = /^[a-zA-Z0-9_-]+$/;
+
+/**
+ * Decode a captured path segment into a vault name, returning null when it
+ * isn't a well-formed vault name. Two failure modes both fall through to the
+ * unbound flow (no narrowing, no junk mint):
+ *
+ *   - malformed percent-escape (`%GG`) → `decodeURIComponent` throws → null.
+ *     A bad `resource` must degrade gracefully, not 500 the authorize handler.
+ *   - decoded value isn't `[a-zA-Z0-9_-]+` → null. The `[^/]+` path capture
+ *     admits anything between slashes; a crafted `resource=…/vault/%2F..%2Fadmin/mcp`
+ *     decodes to `/../admin`, which would otherwise mint a token stamped
+ *     `aud=vault./../admin`. Harmless (the resource server rejects it) but it's
+ *     audit-log noise + a minting path for non-vault names. Anchoring the name
+ *     to the canonical shape closes it. Matches `VAULT_SCOPED_RE`'s name group
+ *     so what we accept here is exactly what a vault scope can name.
+ */
+function decodeVaultName(segment: string): string | null {
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(segment);
+  } catch {
+    return null;
+  }
+  return VAULT_NAME_RE.test(decoded) ? decoded : null;
+}
+
+/**
+ * Rewrite the requested scope list for a resource-bound vault flow.
+ *
+ *   - unnamed `vault:<verb>`        → `vault:<name>:<verb>` (the narrow,
+ *     audience-correct shape vault accepts);
+ *   - already-named `vault:<other>:<verb>` is LEFT UNTOUCHED — a client that
+ *     explicitly named a different vault is not silently re-pointed; the
+ *     downstream picker / assignment defenses decide whether that's allowed.
+ *   - non-vault scopes (`scribe:transcribe`, `hub:admin`, …) pass through
+ *     unchanged — resource-binding only narrows the vault verbs.
+ *
+ * Idempotent: a scope already shaped `vault:<name>:<verb>` for THIS name is
+ * returned as-is, so re-running over a narrowed list is a no-op.
+ */
+export function narrowResourceVaultScopes(scopes: readonly string[], vaultName: string): string[] {
+  return scopes.map((s) => {
+    const parts = s.split(":");
+    const verb = parts[1];
+    if (parts.length === 2 && parts[0] === "vault" && verb && VAULT_VERBS.has(verb)) {
+      return `vault:${vaultName}:${verb}`;
+    }
+    return s;
+  });
+}

package/src/scope-explanations.ts

@@ -138,23 +138,39 @@ export const NON_REQUESTABLE_SCOPES: ReadonlySet<string> = new Set([
 ]);
 
 /**
- * Per-vault `vault:<name>:admin` scopes are also non-requestable via the
- * public OAuth flow: they let the holder mint, revoke, and rotate tokens
- * for a specific vault instance, which is operator-only territory.
+ * Per-vault `vault:<name>:admin` scopes ARE requestable via the public OAuth
+ * flow (single-consent change, 2026-05-29). A user may grant a named vault's
+ * admin scope to an OAuth client — e.g. Claude MCP minting an admin token for
+ * a vault — but only within the one guardrail that survives the simplification:
+ * a user may only delegate authority they themselves hold. That guardrail is
+ * enforced at the shared mint choke-point (`capScopesToUserAuthority` applied
+ * inside `issueAuthCodeRedirect` in `oauth-handlers.ts`): an OAuth flow caps
+ * named vault verbs to those the consenting user actually holds on that vault.
+ * `vaultVerbsForRole` never returns `admin` for an assigned (read/write) user,
+ * so admin is dropped for everyone except the hub owner (isFirstAdmin) — who
+ * holds admin everywhere by construction. An admin-only request from a
+ * non-owner is refused outright (never minted as a zero-scope token).
  *
- * They are mintable by operator-proving local paths, all of which require
- * already-established authority (never third-party consent):
+ * `vault:<name>:admin` also remains mintable by operator-proving local paths,
+ * all of which require already-established authority:
  *   - the session-cookie-gated `/admin/vault-admin-token/:name` endpoint
  *     (the vault SPA's Manage link + setup wizard); and
  *   - `POST /api/auth/mint-token` under the capability-attenuation model —
- *     a `parachute:host:admin` bearer (box-wide → one-vault) or a
- *     `vault:<name>:admin` bearer (same-vault subset). The same model governs
- *     `POST /api/auth/revoke-token` (revoke what you could mint). See
- *     `canGrant` in `scope-attenuation.ts` and the guards in
- *     `api-mint-token.ts` / `api-revoke-token.ts`.
+ *     a `parachute:host:auth` bearer (any requestable scope, now incl.
+ *     `vault:<name>:admin` — an intentional de-escalation widening that
+ *     landed with the single-consent change), a `parachute:host:admin`
+ *     bearer (box-wide → one-vault), or a `vault:<name>:admin` bearer
+ *     (same-vault subset). The same model governs `POST /api/auth/revoke-token`
+ *     (revoke what you could mint). See `canGrant` in `scope-attenuation.ts`
+ *     and the guards in `api-mint-token.ts` / `api-revoke-token.ts`.
  *
- * Pattern-based because the set is open-ended — every vault instance the
- * operator creates implies a new scope, and we don't want to enumerate them.
+ * The matcher is pattern-based because the set is open-ended — every vault
+ * instance the operator creates implies a new scope, and we don't want to
+ * enumerate them. It is still used by `isVaultAdminScope` (the mint-token
+ * de-escalation recognizer) and `explainScope` / `VAULT_VERB_RE` (so the
+ * consent screen renders the admin badge and `scopeIsAdmin` recognizes the
+ * named admin form — load-bearing: the same-hub and trust-by-name auto-mint
+ * gates rely on `scopeIsAdmin` to keep admin consent-gated).
  */
 const VAULT_ADMIN_RE = /^vault:[a-zA-Z0-9_-]+:admin$/;
 
@@ -240,7 +256,12 @@ export function isWellFormedOrNonVaultScope(scope: string): boolean {
 
 /** True when the scope is non-requestable via the public OAuth flow. */
 export function isNonRequestableScope(scope: string): boolean {
-  return NON_REQUESTABLE_SCOPES.has(scope) || VAULT_ADMIN_RE.test(scope);
+  // Per-vault `vault:<name>:admin` is NO LONGER globally non-requestable
+  // (single-consent change, 2026-05-29). It flows through the public OAuth
+  // consent path and through `canGrant` rule 1, capped to the consenting
+  // user's held authority at the `issueAuthCodeRedirect` choke-point. Only
+  // the host-level operator scopes stay non-requestable here.
+  return NON_REQUESTABLE_SCOPES.has(scope);
 }
 
 /** True when the scope can appear in a public `/oauth/authorize` request. */
@@ -261,17 +282,24 @@ export function isRequestableScope(scope: string): boolean {
  * shape we use on the operator approval page where no per-user vault has
  * been selected yet (a specific vault is chosen during sign-in).
  *
- * Verb-only — admin verbs on a per-vault basis (`vault:<name>:admin`) are
- * `NON_REQUESTABLE_SCOPES` by policy and never reach the consent screen, so
- * we don't substitute for them here. Read / write get the matching label.
+ * Includes `admin` (single-consent change, 2026-05-29). `vault:<name>:admin`
+ * is now requestable via OAuth, so it reaches the consent screen and MUST get
+ * the `vault:admin` explanation (level `"admin"`) — both so the consent UI
+ * renders the admin badge and so `scopeIsAdmin("vault:<name>:admin")` returns
+ * true. That second effect is LOAD-BEARING: the same-hub auto-trust gate
+ * (`!hasAdminScope`) and the trust-by-client_name gate
+ * (`!requestedScopes.some(scopeIsAdmin)`) rely on `scopeIsAdmin` recognizing
+ * the named admin form to keep admin grants consent-gated (never silently
+ * auto-minted). If this regex dropped `admin`, those gates would treat a
+ * named admin scope as non-admin and auto-mint it.
  */
-const VAULT_VERB_RE = /^vault:[a-zA-Z0-9_*-]+:(read|write)$/;
+const VAULT_VERB_RE = /^vault:[a-zA-Z0-9_*-]+:(read|write|admin)$/;
 
 export function explainScope(scope: string): ScopeExplanation | null {
   const direct = SCOPE_EXPLANATIONS[scope];
   if (direct) return direct;
   if (VAULT_VERB_RE.test(scope)) {
-    const verb = scope.split(":")[2] as "read" | "write";
+    const verb = scope.split(":")[2] as "read" | "write" | "admin";
     return SCOPE_EXPLANATIONS[`vault:${verb}`] ?? null;
   }
   return null;

package/src/services-manifest.ts

@@ -185,6 +185,39 @@ export interface ServiceEntry {
    * with display metadata attached.
    */
   uis?: Record<string, UiSubUnit>;
+  /**
+   * Last `parachute start` failure that's still actionable, persisted so a
+   * *subsequent* `parachute status` (a separate invocation that only reads
+   * this manifest) + the admin SPA can surface it. Today the only writer is
+   * the lifecycle start preflight when a startCmd binary is missing from PATH
+   * (`@openparachute/depcheck` `MissingDependencyError.toWire()`): the row
+   * shows "failed to start — <binary> not installed" with the install info
+   * instead of a bare orphan-timeout. Cleared on the next successful start.
+   *
+   * Stored as the structured `missing_dependency` wire so the SPA can render
+   * the dedicated install card; `parachute status` reads `error_description`.
+   * Validated as a pass-through object (shape owned by depcheck) rather than
+   * re-typed field-by-field here.
+   */
+  lastStartError?: ServiceEntryStartError;
+}
+
+/**
+ * Persisted start-failure detail on a ServiceEntry. Mirrors depcheck's
+ * `MissingDependencyWire` for the missing-dependency case; `error_type` is
+ * left open so a future non-dependency start failure could reuse the field.
+ */
+export interface ServiceEntryStartError {
+  error_type: string;
+  error_description: string;
+  /** Present for `error_type: "missing_dependency"`. */
+  binary?: string;
+  why?: string | null;
+  docs_url?: string | null;
+  install?: { darwin?: string; linux?: string; generic?: string };
+  sysadmin_hint?: string;
+  /** ISO timestamp of when the failure was recorded. */
+  at?: string;
 }
 
 export interface ServicesManifest {
@@ -251,6 +284,7 @@ function validateEntry(raw: unknown, where: string): ServiceEntry {
   }
   const uis = e.uis;
   const validatedUis = validateUis(uis, where);
+  const validatedStartError = validateStartError(e.lastStartError, where);
   const entry: ServiceEntry = { name, port, paths: paths as string[], health, version };
   if (displayName !== undefined) entry.displayName = displayName;
   if (tagline !== undefined) entry.tagline = tagline;
@@ -258,9 +292,48 @@ function validateEntry(raw: unknown, where: string): ServiceEntry {
   if (installDir !== undefined) entry.installDir = installDir;
   if (stripPrefix !== undefined) entry.stripPrefix = stripPrefix;
   if (validatedUis !== undefined) entry.uis = validatedUis;
+  if (validatedStartError !== undefined) entry.lastStartError = validatedStartError;
   return entry;
 }
 
+/**
+ * Validate the optional `lastStartError` field. `undefined` round-trips
+ * unchanged. A present value must be an object carrying the two required
+ * string fields (`error_type`, `error_description`); the remaining fields
+ * (the missing-dependency detail) pass through with light type-narrowing so
+ * the SPA install card has them, but we never hard-fail an otherwise-valid
+ * row on a malformed start-error — it's diagnostic metadata, not a contract
+ * field. A malformed value is dropped rather than thrown.
+ */
+function validateStartError(raw: unknown, _where: string): ServiceEntryStartError | undefined {
+  if (raw === undefined || raw === null) return undefined;
+  if (typeof raw !== "object" || Array.isArray(raw)) return undefined;
+  const r = raw as Record<string, unknown>;
+  if (typeof r.error_type !== "string" || typeof r.error_description !== "string") {
+    return undefined;
+  }
+  const out: ServiceEntryStartError = {
+    error_type: r.error_type,
+    error_description: r.error_description,
+  };
+  if (typeof r.binary === "string") out.binary = r.binary;
+  if (typeof r.why === "string" || r.why === null) out.why = r.why as string | null;
+  if (typeof r.docs_url === "string" || r.docs_url === null) {
+    out.docs_url = r.docs_url as string | null;
+  }
+  if (r.install && typeof r.install === "object" && !Array.isArray(r.install)) {
+    const ins = r.install as Record<string, unknown>;
+    const install: { darwin?: string; linux?: string; generic?: string } = {};
+    if (typeof ins.darwin === "string") install.darwin = ins.darwin;
+    if (typeof ins.linux === "string") install.linux = ins.linux;
+    if (typeof ins.generic === "string") install.generic = ins.generic;
+    out.install = install;
+  }
+  if (typeof r.sysadmin_hint === "string") out.sysadmin_hint = r.sysadmin_hint;
+  if (typeof r.at === "string") out.at = r.at;
+  return out;
+}
+
 /**
  * Validate the optional `uis` map on a ServiceEntry. `undefined` round-trips
  * unchanged (the field is optional); a present map must be a plain object
@@ -763,3 +836,42 @@ export function findService(
   // missed.
   return readManifestLenient(path).services.find((s) => s.name === name);
 }
+
+/**
+ * Persist a `lastStartError` onto the named row so a later `parachute status`
+ * + the admin SPA surface it. No-op if the row isn't present (e.g. a service
+ * that failed to start before its first self-registration wrote a row — the
+ * inline `parachute start` message already told the operator). Lenient read
+ * so a malformed sibling row doesn't block recording an unrelated failure.
+ */
+export function recordStartError(
+  name: string,
+  err: ServiceEntryStartError,
+  path: string = SERVICES_MANIFEST_PATH,
+): void {
+  if (!existsSync(path)) return;
+  const current = readManifestLenient(path);
+  const idx = current.services.findIndex((s) => s.name === name);
+  if (idx < 0) return;
+  const row = current.services[idx];
+  if (!row) return;
+  current.services[idx] = {
+    ...row,
+    lastStartError: { ...err, at: err.at ?? new Date().toISOString() },
+  };
+  writeManifest(current, path);
+}
+
+/** Clear a row's persisted `lastStartError` (called on a successful start).
+ * No-op when the row is absent or already clean. */
+export function clearStartError(name: string, path: string = SERVICES_MANIFEST_PATH): void {
+  if (!existsSync(path)) return;
+  const current = readManifestLenient(path);
+  const idx = current.services.findIndex((s) => s.name === name);
+  if (idx < 0) return;
+  const row = current.services[idx];
+  if (!row || row.lastStartError === undefined) return;
+  const { lastStartError: _drop, ...rest } = row;
+  current.services[idx] = rest;
+  writeManifest(current, path);
+}