@openparachute/hub 0.5.14-rc.8 → 0.6.0

package/src/api-account.ts

@@ -55,12 +55,15 @@ import { CSRF_FIELD_NAME, ensureCsrfToken, verifyCsrfToken } from "./csrf.ts";
 import { changePasswordRateLimiter } from "./rate-limit.ts";
 import { isHttpsRequest } from "./request-protocol.ts";
 import { findActiveSession } from "./sessions.ts";
+import { isTotpEnrolled } from "./two-factor-store.ts";
 import {
   PASSWORD_MAX_LEN,
   UserNotFoundError,
+  type VaultVerb,
   getUserById,
   isFirstAdmin,
   validatePassword,
+  vaultVerbsForUserVault,
   verifyPassword,
 } from "./users.ts";
 
@@ -489,6 +492,15 @@ export function handleAccountHomeGet(req: Request, deps: AccountHomeDeps): Respo
   const adminFlag = isFirstAdmin(deps.db, user.id);
   const csrf = ensureCsrfToken(req);
   const extra: Record<string, string> = csrf.setCookie ? { "set-cookie": csrf.setCookie } : {};
+  // Per-vault mintable verbs for the "mint an access token" affordance on each
+  // tile. Reads the assignment role (today always write → ["read", "write"])
+  // so the UI only ever offers a verb the POST handler would accept. Empty for
+  // the admin / no-vault branches (no assigned vaults to iterate).
+  const mintableVerbs: Record<string, VaultVerb[]> = {};
+  for (const v of user.assignedVaults) {
+    const verbs = vaultVerbsForUserVault(deps.db, user.id, v);
+    if (verbs && verbs.length > 0) mintableVerbs[v] = verbs;
+  }
   return htmlResponse(
     renderAccountHome({
       username: user.username,
@@ -497,6 +509,8 @@ export function handleAccountHomeGet(req: Request, deps: AccountHomeDeps): Respo
       hubOrigin: deps.hubOrigin,
       isFirstAdmin: adminFlag,
       csrfToken: csrf.token,
+      twoFactorEnabled: isTotpEnrolled(deps.db, user.id),
+      mintableVerbs,
     }),
     200,
     extra,

package/src/api-mint-token.ts

@@ -8,10 +8,31 @@
  *   - the future admin SPA when the operator wants to mint a one-shot
  *     scope-narrow token without dropping to a terminal.
  *
- * Auth: `Authorization: Bearer <token>` where `token`'s `scope` claim
- * contains `parachute:host:auth`. The operator's local operator.token
- * (admin scope-set) covers this; a narrow `--scope-set=auth` operator
- * token also covers this.
+ * Auth — capability attenuation: any bearer may mint a token whose authority
+ * is a SUBSET of its own. A requested scope `s` is grantable (`canGrant`) iff:
+ *
+ *   1. `s` is requestable AND the bearer holds `parachute:host:auth`
+ *      — host:auth mints any requestable scope (vault/scribe verbs, etc.).
+ *   2. `s` is `vault:<N>:admin` AND the bearer holds `parachute:host:admin`
+ *      — box-wide admin attenuates to one named vault's admin.
+ *   3. `s` is `vault:<N>:<verb>` (verb ∈ read/write/admin) AND the bearer
+ *      holds `vault:<N>:admin` for the SAME `<N>` — a vault-admin attenuates
+ *      to any same-vault subset, including an equal-level admin.
+ *
+ * Otherwise `s` is refused (400 `invalid_scope`). This single rule subsumes
+ * the former two-part guard: the old hard `parachute:host:auth` gate is now
+ * rule 1, and PR-A's `host:admin → vault:<name>:admin` carve-out (hub#449) is
+ * now rule 2. Rule 3 is new — it lets a `vault:<name>:admin` bearer mint
+ * same-vault sub-tokens (the canonical headless path to per-vault admin,
+ * replacing deprecated `pvt_*` — vault#282 — and the path the SPA tokens
+ * page uses via session → /admin/host-admin-token → here). Cross-vault and
+ * host-authority escalation are always blocked: a `vault:work:admin` bearer
+ * can never mint `vault:other:*` or any `parachute:host:*`.
+ *
+ * Entry gate: the bearer must hold at least one minting authority —
+ * `parachute:host:auth`, `parachute:host:admin`, or some `vault:<*>:admin`.
+ * A bearer with none (e.g. a read-only token) gets 403 `insufficient_scope`
+ * before any per-scope check; it cannot mint anything.
  *
  * Why a separate endpoint instead of extending /admin/host-admin-token:
  * that endpoint is session-cookie-gated for the SPA's needs and only
@@ -26,14 +47,38 @@
 import type { Database } from "bun:sqlite";
 import { inferAudience } from "./jwt-audience.ts";
 import { recordTokenMint, signAccessToken, validateAccessToken } from "./jwt-sign.ts";
-import { isNonRequestableScope } from "./scope-explanations.ts";
+import {
+  MINT_HOST_ADMIN_SCOPE,
+  MINT_HOST_AUTH_SCOPE,
+  canGrant,
+  hasMintingAuthority,
+} from "./scope-attenuation.ts";
+import {
+  isVaultAdminScope,
+  isWellFormedOrNonVaultScope,
+  vaultScopeName,
+} from "./scope-explanations.ts";
+
+// Re-export `canGrant` so existing importers (and the symmetric revoke path)
+// have a single name to reach for; the implementation lives in the shared
+// `scope-attenuation.ts` module alongside `hasMintingAuthority`.
+export { canGrant } from "./scope-attenuation.ts";
 
 /** Default lifetime when --expires-in / `expires_in` is omitted. Matches the CLI. */
 export const API_MINT_TOKEN_DEFAULT_TTL_SECONDS = 90 * 24 * 60 * 60;
 /** Hard cap. Matches the CLI's --expires-in upper bound. */
 export const API_MINT_TOKEN_MAX_TTL_SECONDS = 365 * 24 * 60 * 60;
-/** Scope required on the bearer token to call this endpoint. */
-export const API_MINT_TOKEN_REQUIRED_SCOPE = "parachute:host:auth";
+/**
+ * Bearer scope that authorises minting any *requestable* scope (rule 1 of the
+ * attenuation model). Re-exported alias of the shared `MINT_HOST_AUTH_SCOPE`
+ * for back-compat with existing importers.
+ */
+export const API_MINT_TOKEN_HOST_AUTH_SCOPE = MINT_HOST_AUTH_SCOPE;
+/**
+ * Bearer scope that authorises minting `vault:<name>:admin` (rule 2).
+ * Re-exported alias of the shared `MINT_HOST_ADMIN_SCOPE`.
+ */
+export const API_MINT_TOKEN_VAULT_ADMIN_BEARER_SCOPE = MINT_HOST_ADMIN_SCOPE;
 /** client_id stamped on minted tokens. Matches the CLI flow's value. */
 export const API_MINT_TOKEN_CLIENT_ID = "parachute-hub";
 
@@ -87,12 +132,17 @@ export async function handleApiMintToken(req: Request, deps: ApiMintTokenDeps):
     return jsonError(401, "unauthenticated", `bearer token invalid — ${msg}`);
   }
 
-  // 3. Scope gate.
-  if (!bearerScopes.includes(API_MINT_TOKEN_REQUIRED_SCOPE)) {
+  // 3. Entry gate — the bearer must hold at least one minting authority
+  //    (`parachute:host:auth`, `parachute:host:admin`, or some
+  //    `vault:<*>:admin`). A bearer with none can mint nothing under the
+  //    attenuation model, so we 403 before per-scope checks. Per-scope
+  //    grantability (which authority covers which scope) is enforced below
+  //    via `canGrant`.
+  if (!hasMintingAuthority(bearerScopes)) {
     return jsonError(
       403,
       "insufficient_scope",
-      `bearer token lacks ${API_MINT_TOKEN_REQUIRED_SCOPE}`,
+      `bearer token holds no minting authority (need ${API_MINT_TOKEN_HOST_AUTH_SCOPE}, ${API_MINT_TOKEN_VAULT_ADMIN_BEARER_SCOPE}, or vault:<name>:admin)`,
     );
   }
 
@@ -117,19 +167,40 @@ export async function handleApiMintToken(req: Request, deps: ApiMintTokenDeps):
     return jsonError(400, "invalid_request", "scope must contain at least one scope");
   }
 
-  // Privilege-diffusion guard: mint paths cannot themselves mint tokens
-  // carrying non-requestable scopes (parachute:host:admin, the host:*
-  // narrow scopes, vault:<name>:admin). Holder of `parachute:host:auth`
-  // can mint vault/scribe/agent verb scopes for downstream services, but
-  // cannot mint another `:auth` (or any other non-requestable) without
-  // forced re-auth via the operator.token rotation path. Same set the
-  // public OAuth flow already rejects.
-  const blocked = scopes.filter((s) => isNonRequestableScope(s));
+  // Shape guard (defensive hygiene — adversarial audit 2026-05-28): reject any
+  // scope that is shaped like a *named* per-vault scope but malformed —
+  // `vault:work:ADMIN` (uppercase verb), `vault::admin` (empty name),
+  // `vault:work:read:admin` (extra segment), `VAULT:work:admin` (uppercase
+  // resource). These slip past `isNonRequestableScope`'s strict regexes, so
+  // `canGrant` rule 1 would admit them as "requestable" and mint a junk
+  // registry row. They grant zero access today (the vault consumer's
+  // `decomposeVaultScope` rejects all four), so this is NOT exploitable now —
+  // the check is a backstop against a future consumer-normalization regression
+  // plus registry hygiene. It's an input-shape check, orthogonal to authority,
+  // so it runs for ALL callers before any `canGrant` attenuation. Non-vault
+  // scopes and the unnamed `vault:<verb>` forms are unaffected.
+  const malformed = scopes.filter((s) => !isWellFormedOrNonVaultScope(s));
+  if (malformed.length > 0) {
+    return jsonError(
+      400,
+      "invalid_scope",
+      `malformed vault scope ${malformed.join(", ")}; expected vault:<name>:<read|write|admin>`,
+    );
+  }
+
+  // Capability-attenuation guard: every requested scope must be a subset of
+  // the bearer's own authority under `canGrant` (rules in the file docstring).
+  // A `parachute:host:auth` bearer mints any requestable scope; a
+  // `parachute:host:admin` bearer additionally mints `vault:<name>:admin`; a
+  // `vault:<name>:admin` bearer mints same-vault subsets only. Anything else
+  // — host:* escalation, cross-vault, a non-requestable with no covering
+  // authority — is blocked. One blocked scope rejects the whole request.
+  const blocked = scopes.filter((s) => !canGrant(bearerScopes, s));
   if (blocked.length > 0) {
     return jsonError(
       400,
       "invalid_scope",
-      `scope ${blocked.join(", ")} is not requestable via mint-token; use OAuth flow or operator rotation`,
+      `scope ${blocked.join(", ")} is not grantable by this bearer; use OAuth flow or operator rotation`,
     );
   }
 
@@ -183,6 +254,40 @@ export async function handleApiMintToken(req: Request, deps: ApiMintTokenDeps):
     permissionsCanonical = JSON.stringify(permissionsClaim);
   }
 
+  // Derive the `vault_scope` pin. Collect the set of vault names `<N>` from
+  // every requested `vault:<N>:<verb>` scope that was authorized via a
+  // vault-scoped authority — rule 2 (host:admin → vault:<N>:admin) or rule 3
+  // (vault:<N>:admin → same-vault subset). These are the vault-scoped mints,
+  // so we pin the token to those vault(s): it can ONLY ever be used against
+  // them (defense-in-depth + least privilege), matching the canonical
+  // session-path mint in `admin-vault-admin-token.ts`.
+  //
+  // Pure `parachute:host:auth` requestable mints (a `vault:<N>:read/write`
+  // granted by rule 1 with no covering vault-admin authority) stay UNpinned
+  // (`[]`) — the "no per-user restriction" sentinel; the scope string +
+  // audience are the authorization-bearing gate there, as before. We
+  // distinguish by checking the bearer's own vault-scoped authority: a vault
+  // name is pinned only when the bearer held `vault:<N>:admin` (rule 3) or
+  // host:admin and the scope is admin (rule 2).
+  //
+  // Note: `audience` is single-valued and `inferAudience` is first-wins, so a
+  // multi-vault request gets `aud=vault.<first>` and only authenticates
+  // against that vault. Mint one token per vault for the multi-vault case.
+  // The canonical consumers (mcp-install, SPA tokens page) request a single
+  // vault.
+  const bearerHasHostAdmin = bearerScopes.includes(API_MINT_TOKEN_VAULT_ADMIN_BEARER_SCOPE);
+  const vaultScopePinSet = new Set<string>();
+  for (const s of scopes) {
+    const name = vaultScopeName(s);
+    if (name === null) continue;
+    const grantedByVaultAdminBearer = bearerScopes.includes(`vault:${name}:admin`); // rule 3
+    const grantedByHostAdminForAdmin = isVaultAdminScope(s) && bearerHasHostAdmin; // rule 2
+    if (grantedByVaultAdminBearer || grantedByHostAdminForAdmin) {
+      vaultScopePinSet.add(name);
+    }
+  }
+  const vaultScopePin = [...vaultScopePinSet];
+
   // 6. Mint + register.
   const minted = await signAccessToken(deps.db, {
     sub: subject,
@@ -192,11 +297,14 @@ export async function handleApiMintToken(req: Request, deps: ApiMintTokenDeps):
     issuer: deps.issuer,
     ttlSeconds,
     // Operator-driven CLI/API mint — the bearer already cleared the
-    // `parachute:host:auth` privilege gate, so there's no per-user vault
-    // pin to enforce. Empty `vault_scope` is the "no restriction"
-    // sentinel; the `scopes` themselves remain authorization-bearing as
-    // before.
-    vaultScope: [],
+    // attenuation guard. `vault_scope` is `[]` (no restriction) for any
+    // verb scope granted by rule 1, or the named vault(s) for vault-scoped
+    // mints authorized via rule 2 / rule 3 (see above). The pin tracks the
+    // grant rule, not the bearer: a host:admin bearer minting
+    // `vault:work:write` goes through rule 1 (write is requestable), so it
+    // ALSO gets `vault_scope:[]` — only its `vault:work:admin` mints (rule 2)
+    // are pinned.
+    vaultScope: vaultScopePin,
     ...(permissionsClaim !== undefined ? { extraClaims: { permissions: permissionsClaim } } : {}),
     ...(deps.now !== undefined ? { now: deps.now } : {}),
   });

package/src/api-modules-ops.ts

@@ -35,6 +35,7 @@
 import type { Database } from "bun:sqlite";
 import { randomUUID } from "node:crypto";
 import { dirname } from "node:path";
+import { MissingDependencyError, type MissingDependencyWire } from "@openparachute/depcheck";
 import { CURATED_MODULES, type CuratedModuleShort } from "./api-modules.ts";
 import { isLinked as defaultIsLinked } from "./bun-link.ts";
 import { PARACHUTE_INSTALL_CHANNEL_ENV } from "./commands/install.ts";
@@ -49,11 +50,7 @@ import {
   getSpec,
   synthesizeManifestForKnownModule,
 } from "./service-spec.ts";
-import {
-  findService,
-  readManifestLenient,
-  removeService,
-} from "./services-manifest.ts";
+import { findService, readManifestLenient, removeService } from "./services-manifest.ts";
 import type { ModuleState, SpawnRequest, Supervisor } from "./supervisor.ts";
 import { WELL_KNOWN_PATH, type regenerateWellKnown } from "./well-known.ts";
 
@@ -81,6 +78,15 @@ export interface Operation {
   log: string[];
   /** Error message when status is `failed`. Mirrored from the underlying throw. */
   error?: string;
+  /**
+   * Structured error detail when the failure is a known typed error — today
+   * only `MissingDependencyError.toWire()` (a missing external binary like
+   * `bun` / `git` during install). The operations-polling SPA switches on
+   * `error_detail.error_type === "missing_dependency"` to render a dedicated
+   * install card; the plain `error` string is the fallback for everything
+   * else. Wire shape matches `@openparachute/depcheck`'s `MissingDependencyWire`.
+   */
+  error_detail?: MissingDependencyWire;
   startedAt: string;
   finishedAt?: string;
 }
@@ -89,7 +95,11 @@ export interface OperationsRegistry {
   create(kind: OperationKind, short: string): Operation;
   get(id: string): Operation | undefined;
   /** Append a log line + (optionally) advance status. */
-  update(id: string, patch: Partial<Pick<Operation, "status" | "error">>, logLine?: string): void;
+  update(
+    id: string,
+    patch: Partial<Pick<Operation, "status" | "error" | "error_detail">>,
+    logLine?: string,
+  ): void;
 }
 
 /**
@@ -122,11 +132,16 @@ class InMemoryOperationsRegistry implements OperationsRegistry {
     return this.ops.get(id);
   }
 
-  update(id: string, patch: Partial<Pick<Operation, "status" | "error">>, logLine?: string): void {
+  update(
+    id: string,
+    patch: Partial<Pick<Operation, "status" | "error" | "error_detail">>,
+    logLine?: string,
+  ): void {
     const op = this.ops.get(id);
     if (!op) return;
     if (patch.status) op.status = patch.status;
     if (patch.error !== undefined) op.error = patch.error;
+    if (patch.error_detail !== undefined) op.error_detail = patch.error_detail;
     if (logLine) op.log.push(logLine);
     if (patch.status === "succeeded" || patch.status === "failed") {
       op.finishedAt = this.clock().toISOString();
@@ -520,13 +535,37 @@ export async function handleInstall(
   // immediately + the work runs in the background. Errors get logged
   // to the operation; nothing throws back to the request handler.
   void runInstall(op.id, short, spec, deps, bodyChannel).catch((err) => {
-    const msg = err instanceof Error ? err.message : String(err);
-    registry.update(op.id, { status: "failed", error: msg }, `install failed: ${msg}`);
+    failOperation(registry, op.id, "install", err);
   });
 
   return acceptedOp(op.id);
 }
 
+/**
+ * Mark an async op failed, attaching the structured `error_detail` wire when
+ * the underlying throw is a `MissingDependencyError` (a missing external
+ * binary like `bun` / `git` during install). The operations-polling SPA reads
+ * `error_detail` to render the dedicated install card; the plain `error`
+ * string is the fallback for every other failure.
+ */
+function failOperation(
+  registry: OperationsRegistry,
+  opId: string,
+  verb: string,
+  err: unknown,
+): void {
+  const msg = err instanceof Error ? err.message : String(err);
+  if (err instanceof MissingDependencyError) {
+    registry.update(
+      opId,
+      { status: "failed", error: msg, error_detail: err.toWire() },
+      `${verb} failed: ${err.binary} not installed`,
+    );
+    return;
+  }
+  registry.update(opId, { status: "failed", error: msg }, `${verb} failed: ${msg}`);
+}
+
 /**
  * Internal install runner. Exported so non-API callers (the first-boot
  * wizard at `/admin/setup`, hub#259) can drive the same install →
@@ -722,8 +761,7 @@ export async function handleUpgrade(
   const spec = specFor(short);
 
   void runUpgrade(op.id, short, spec, deps).catch((err) => {
-    const msg = err instanceof Error ? err.message : String(err);
-    registry.update(op.id, { status: "failed", error: msg }, `upgrade failed: ${msg}`);
+    failOperation(registry, op.id, "upgrade", err);
   });
   return acceptedOp(op.id);
 }

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 });
   }

package/src/api-users.ts

@@ -336,7 +336,16 @@ export async function handleCreateUser(req: Request, deps: ApiUsersDeps): Promis
   }
 }
 
-/** DELETE /api/users/:id — hard-delete + token revocation + session/grant cleanup. */
+/**
+ * DELETE /api/users/:id — hard-delete + token revocation + session/grant
+ * cleanup.
+ *
+ * Success returns `200 { ok: true, revocation_lag_seconds: 60 }` (was a bare
+ * 204 pre-consistency-fix) so the SPA can warn that the deleted user's
+ * tokens linger ~60s on resource-server revocation caches — same surface
+ * the reset-password path carries. The race-tolerant "row already gone"
+ * path stays a bodyless 204 (nothing was revoked here, no lag to report).
+ */
 export async function handleDeleteUser(
   req: Request,
   userId: string,
@@ -390,11 +399,28 @@ export async function handleDeleteUser(
   if (!removed) {
     // Race: row deleted by a concurrent request. Operator's intent
     // (no such user) is already satisfied — same shape as the grant-
-    // revoke race in `admin-grants.ts`.
+    // revoke race in `admin-grants.ts`. No tokens were revoked by THIS
+    // call, so there's no revocation lag to warn about; keep the bodyless
+    // 204 for the race path.
     return new Response(null, { status: 204 });
   }
   console.log(`user deleted: id=${userId} username=${target.username}`);
-  return new Response(null, { status: 204 });
+  // `revocation_lag_seconds`: same consistency fix the reset-password path
+  // got (smoke 2026-05-27 finding 3). Deleting a user revokes their tokens
+  // in hub's DB immediately, but resource servers (vault, scribe, …) cache
+  // the revocation list via scope-guard's `REVOCATION_CACHE_TTL_MS = 60_000`
+  // — a deleted user's tokens linger for up to ~60s on those caches. Surface
+  // that so the admin isn't surprised when a just-deleted user's client can
+  // still read for a minute (relevant in the stolen-device / compromise
+  // threat model). 200 + body instead of the old bare 204 so the SPA can
+  // render the warning banner.
+  return new Response(
+    JSON.stringify({ ok: true, revocation_lag_seconds: REVOCATION_LAG_SECONDS }),
+    {
+      status: 200,
+      headers: { "content-type": "application/json", "cache-control": "no-store" },
+    },
+  );
 }
 
 /**