@openparachute/hub 0.5.14-rc.2 → 0.5.14-rc.21

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-attenuation.ts

@@ -0,0 +1,85 @@
+/**
+ * Capability attenuation — the shared authority model behind both the
+ * mint side (`/api/auth/mint-token`, hub#452) and the revoke side
+ * (`/api/auth/revoke-token`). The two endpoints are symmetric: you may
+ * revoke exactly what you could have minted.
+ *
+ * `canGrant(bearerScopes, scope)` answers: could a bearer holding
+ * `bearerScopes` mint a token carrying `scope`? It is the single source of
+ * truth for "is `scope` within this bearer's authority" — mint uses it to
+ * gate what a request may issue; revoke uses it to gate what a request may
+ * tear down (every recorded scope on the target jti must be `canGrant`-able).
+ *
+ * `hasMintingAuthority(bearerScopes)` is the cheap entry gate: does the
+ * bearer hold ANY authority at all (host:auth, host:admin, or some
+ * `vault:<*>:admin`)? A bearer with none can neither mint nor revoke via
+ * attenuation, so both endpoints 403 it before any per-scope work.
+ *
+ * Pure functions — no DB, no I/O — so they're trivially testable and both
+ * handlers stay thin.
+ */
+import { isNonRequestableScope, isVaultAdminScope, vaultScopeName } from "./scope-explanations.ts";
+
+/**
+ * Bearer scope that authorises minting any *requestable* scope (rule 1 of the
+ * attenuation model). The operator's admin scope-set carries this; a narrow
+ * `--scope-set=auth` operator token carries it too.
+ */
+export const MINT_HOST_AUTH_SCOPE = "parachute:host:auth";
+/**
+ * Bearer scope that authorises minting `vault:<name>:admin` (rule 2).
+ * `parachute:host:admin` already implies box-wide administration of every
+ * vault on the hub, so minting a vault-pinned admin from it is a privilege
+ * *reduction* (de-escalation), not an escalation — see the design doc
+ * `2026-05-28-operator-mintable-vault-admin.md`.
+ */
+export const MINT_HOST_ADMIN_SCOPE = "parachute:host:admin";
+
+/**
+ * Capability attenuation: can a bearer holding `bearerScopes` mint a token
+ * carrying `requestedScope`? True iff the requested scope is a subset of the
+ * bearer's own authority under one of three rules:
+ *
+ *   1. requestable + bearer has `parachute:host:auth`;
+ *   2. `vault:<N>:admin` + bearer has `parachute:host:admin`;
+ *   3. `vault:<N>:<verb>` + bearer has `vault:<N>:admin` (same `<N>`).
+ *
+ * Pure function — no DB, no I/O — so it's trivially testable and the guard in
+ * each handler is a single `scopes.filter((s) => !canGrant(bearerScopes, s))`.
+ *
+ * On the revoke side this is the symmetric rule: a target jti is revocable by
+ * a non-host:auth bearer iff EVERY one of its recorded scopes is `canGrant`-able
+ * — i.e. the bearer could have minted that token, so it may also tear it down.
+ * Cross-vault and host-authority targets are never `canGrant`-able by a mere
+ * `vault:<N>:admin` bearer, so it can neither mint nor revoke them.
+ */
+export function canGrant(bearerScopes: string[], requestedScope: string): boolean {
+  // Rule 1 — host:auth mints any requestable scope.
+  if (!isNonRequestableScope(requestedScope) && bearerScopes.includes(MINT_HOST_AUTH_SCOPE)) {
+    return true;
+  }
+  // Rule 2 — host:admin attenuates to a named vault's admin.
+  if (isVaultAdminScope(requestedScope) && bearerScopes.includes(MINT_HOST_ADMIN_SCOPE)) {
+    return true;
+  }
+  // Rule 3 — vault:<N>:admin attenuates to any same-vault subset (incl. admin).
+  const requestedVault = vaultScopeName(requestedScope);
+  if (requestedVault !== null && bearerScopes.includes(`vault:${requestedVault}:admin`)) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Does the bearer hold ANY minting authority? Entry gate before per-scope
+ * checks — a bearer with none (e.g. a read-only token) can mint (or revoke
+ * via attenuation) nothing, so both endpoints 403 it early rather than
+ * walking every scope to the same end.
+ */
+export function hasMintingAuthority(bearerScopes: string[]): boolean {
+  return (
+    bearerScopes.includes(MINT_HOST_AUTH_SCOPE) ||
+    bearerScopes.includes(MINT_HOST_ADMIN_SCOPE) ||
+    bearerScopes.some((s) => isVaultAdminScope(s))
+  );
+}

package/src/scope-explanations.ts

@@ -138,20 +138,130 @@ export const NON_REQUESTABLE_SCOPES: ReadonlySet<string> = new Set([
 ]);
 
 /**
- * Per-vault `vault:<name>:admin` scopes are also non-requestable: they let
- * the holder mint, revoke, and rotate tokens for a specific vault instance,
- * which is operator-only territory. Like `parachute:host:admin`, these are
- * minted by a session-cookie-gated hub endpoint (`/admin/vault-admin-token/:name`),
- * never by the public OAuth flow.
- *
- * 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.
+ * 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).
+ *
+ * `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: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`.
+ *
+ * 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$/;
 
+/**
+ * Any per-vault scope: `vault:<name>:<verb>` for verb ∈ {read, write, admin}.
+ * Captures the name in group 1 and the verb in group 2. Used by the
+ * mint-token capability-attenuation model to recognise the scopes a
+ * `vault:<name>:admin` bearer may attenuate to (same-vault subsets).
+ */
+const VAULT_SCOPED_RE = /^vault:([a-zA-Z0-9_-]+):(read|write|admin)$/;
+
+/**
+ * True when `scope` is a per-vault admin scope (`vault:<name>:admin`).
+ * Exported so the mint-token path can recognise the one non-requestable
+ * scope it conditionally admits for `parachute:host:admin` bearers.
+ */
+export function isVaultAdminScope(scope: string): boolean {
+  return VAULT_ADMIN_RE.test(scope);
+}
+
+/**
+ * Extract the vault name from ANY per-vault scope (`vault:<name>:<verb>` for
+ * verb ∈ {read, write, admin}), or null if the scope isn't per-vault-scoped.
+ * Used by the mint-token attenuation model to (a) match a `vault:<name>:admin`
+ * bearer against same-vault requested scopes, and (b) derive the `vault_scope`
+ * pin for every vault-scoped mint regardless of verb.
+ */
+export function vaultScopeName(scope: string): string | null {
+  const m = VAULT_SCOPED_RE.exec(scope);
+  return m ? (m[1] ?? null) : null;
+}
+
+/**
+ * Mint-time shape guard: reject scopes that LOOK like a *named* per-vault scope
+ * (`vault:<name>:<verb>`, three+ colon-segments, first segment `vault`
+ * case-insensitively to catch `VAULT:…`) but are malformed — i.e. they don't
+ * match the strict `vault:<name>:<read|write|admin>` shape (`VAULT_SCOPED_RE`).
+ *
+ * Returns true for (i.e. ADMITS):
+ *   - well-formed named scopes `vault:<name>:<read|write|admin>`;
+ *   - the canonical *unnamed* two-segment scopes `vault:read|write|admin`
+ *     (legitimate OAuth/consent forms — keys in `SCOPE_EXPLANATIONS`, narrowed
+ *     to a named vault at consent time) and any other non-three-segment
+ *     `vault`-prefixed string — those aren't attempting the named shape, so
+ *     they're out of this guard's remit and keep their existing behaviour;
+ *   - every non-vault scope (`scribe:transcribe`, `parachute:host:*`, …).
+ *
+ * Returns false for (i.e. REJECTS) only a `vault`-prefixed string with three
+ * or more colon-segments that fails `VAULT_SCOPED_RE`:
+ *   `vault:work:ADMIN` (uppercase verb), `vault::admin` (empty name),
+ *   `vault:work:read:admin` (extra segment), `VAULT:work:admin` (uppercase
+ *   resource).
+ *
+ * Why this exists (defensive hygiene — adversarial audit, 2026-05-28): a
+ * `parachute:host:auth` bearer can today mint those four malformed strings.
+ * `isNonRequestableScope`'s strict regexes don't match them, so `canGrant`
+ * rule 1 admits them as "requestable" — the mint succeeds (200) carrying the
+ * literal junk string and writes a registry row. They grant ZERO access today
+ * (the vault consumer's `decomposeVaultScope` is case-sensitive + anchored and
+ * rejects all four), so this is NOT exploitable now. The value is (a) registry
+ * hygiene (no junk rows) and (b) a backstop against a FUTURE consumer-
+ * normalization regression — if vault ever started case-folding scope verbs,
+ * those junk tokens could silently become live admin. A strict mint-time shape
+ * check closes that door now.
+ *
+ * Orthogonal to authority: this is an input-shape check applied to ALL mint
+ * callers (host:auth, host:admin, vault:<name>:admin) before any `canGrant`
+ * attenuation. It does not affect non-vault scopes or the unnamed `vault:<verb>`
+ * forms.
+ */
+export function isWellFormedOrNonVaultScope(scope: string): boolean {
+  const segments = scope.split(":");
+  // Only constrain the *named* per-vault shape: first segment names the vault
+  // resource (case-insensitive, to catch `VAULT:`) AND there are three or more
+  // segments (an attempt at `vault:<name>:<verb>`). The unnamed two-segment
+  // forms (`vault:read|write|admin`) and a bare `vault` are out of remit.
+  const firstSegment = segments[0] ?? "";
+  if (firstSegment.toLowerCase() !== "vault" || segments.length < 3) {
+    return true;
+  }
+  return VAULT_SCOPED_RE.test(scope);
+}
+
 /** 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. */
@@ -172,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);
+}