@openparachute/hub 0.5.2 → 0.5.9-rc.6

package/src/commands/auth.ts

@@ -26,12 +26,23 @@ import { HUB_DEFAULT_PORT, readHubPort } from "../hub-control.ts";
 import { openHubDb } from "../hub-db.ts";
 import { deriveHubOrigin } from "../hub-origin.ts";
 import { inferAudience } from "../jwt-audience.ts";
-import { signAccessToken, validateAccessToken } from "../jwt-sign.ts";
+import {
+  findTokenRowByJti,
+  recordTokenMint,
+  revokeTokenByJti,
+  signAccessToken,
+  tokenRowIdentity,
+} from "../jwt-sign.ts";
 import {
   OPERATOR_TOKEN_CLIENT_ID,
+  OPERATOR_TOKEN_SCOPE_SET_NAMES,
+  type OperatorScopeSet,
+  OperatorTokenExpiredError,
+  isOperatorScopeSet,
   issueOperatorToken,
-  readOperatorTokenFile,
+  useOperatorTokenWithAutoRotate,
 } from "../operator-token.ts";
+import { isNonRequestableScope } from "../scope-explanations.ts";
 import { rotateSigningKey } from "../signing-keys.ts";
 import {
   SingleUserModeError,
@@ -61,6 +72,7 @@ const HUB_LOCAL_SUBCOMMANDS = new Set([
   "list-users",
   "rotate-operator",
   "mint-token",
+  "revoke-token",
   "pending-clients",
   "approve-client",
   "list-grants",
@@ -79,10 +91,20 @@ Usage:
   parachute auth 2fa disable           Disable 2FA (requires password)
   parachute auth 2fa backup-codes      Regenerate backup codes
   parachute auth rotate-key            Rotate the hub's JWT signing key
-  parachute auth rotate-operator       Mint a fresh ~/.parachute/operator.token
-  parachute auth mint-token --scope <scope> [--aud <aud>] [--ttl <duration>] [--sub <sub>]
+  parachute auth rotate-operator [--scope-set <set>]
+                                       Mint a fresh ~/.parachute/operator.token
+                                       (set = install|start|expose|auth|vault|admin,
+                                       default admin)
+  parachute auth mint-token --scope <scope> [--aud <aud>] [--expires-in <seconds>]
+                                            [--sub <sub>] [--permissions <json>]
                                        Mint a scope-narrow JWT against the
-                                       operator's identity (stdout = JWT)
+                                       operator's identity (stdout = JWT).
+                                       --ttl <duration> is the deprecated
+                                       alias (use --expires-in seconds).
+  parachute auth revoke-token <jti>    Mark a registry-row token revoked
+                                       by jti. Idempotent: a re-revoke
+                                       prints the existing revoked_at and
+                                       exits 0.
   parachute auth pending-clients       List OAuth clients awaiting approval
   parachute auth approve-client <id>   Approve a pending OAuth client
   parachute auth list-grants [--username <name>]
@@ -112,16 +134,59 @@ hours so cached client copies keep validating until their TTL expires.
 rotate-operator mints a fresh long-lived operator token at
 ~/.parachute/operator.token (mode 0600). Local CLI tools read this file
 as their bearer when calling on-box services. set-password also writes
-the file on first-run / password reset.
+the file on first-run / password reset. Default lifetime is 90d (was
+365d through 0.5.7); CLI flows that read the token within 7d of expiry
+auto-rotate it in place, so weekly users never see an expiry surprise.
+
+--scope-set chooses how broad the new token is:
+  install  — install/upgrade modules (vault:read for new-vault discovery)
+  start    — lifecycle modules (start/stop/restart/status)
+  expose   — bring tailnet / public exposure layers up and down
+  auth     — mint hub-issued tokens, manage user accounts
+  vault    — administer vaults (create / configure / delete)
+  admin    — superset of all above; pre-#213 default and current default
+
+Phase 1 of #213 ships the vocabulary + flag; Phase 2 (separate follow-up)
+wires per-command enforcement so an \`install\`-only token can't, say, run
+\`parachute expose public\`. Until then, --scope-set is a tool the cautious
+operator can opt into without breaking anyone.
 
 mint-token issues a single scope-narrow JWT against the operator's
 identity, signed with the same key as OAuth-issued tokens. Pipeable:
 \`parachute auth mint-token --scope scribe:transcribe | pbcopy\`. The
 audience defaults via the same inference rule the OAuth flow uses
 (named \`vault:<name>:<verb>\` → \`vault.<name>\`, otherwise the first
-colon-prefixed scope's namespace, fallback \`hub\`). TTL defaults to 90d,
-caps at 365d. Requires a valid ~/.parachute/operator.token (run
-\`parachute auth set-password\` or \`rotate-operator\` first).
+colon-prefixed scope's namespace, fallback \`hub\`). Lifetime defaults
+to 90d, caps at 365d.
+
+--scope accepts space-separated multi-scope (e.g.
+\`--scope "vault:default:read agent:wovenboulder:invoke"\`).
+
+--expires-in is the canonical lifetime flag — integer seconds (e.g.
+\`--expires-in 86400\` for 1 day). The legacy \`--ttl\` flag accepts a
+duration suffix (\`90d\` / \`24h\` / \`30m\` / \`60s\`) and is supported as
+a deprecated alias; passing it emits a one-line stderr deprecation
+notice. \`--ttl\` will be removed in 0.6.0.
+
+--permissions accepts a JSON object encoding fine-grained constraints
+beyond OAuth scope (e.g.
+\`--permissions '{"vault":{"default":{"write_tags":["health"]}}}'\`).
+Carried in the JWT as the \`permissions\` claim per the convergence
+section of the auth-architecture research doc.
+
+Every mint writes a row to the hub's token registry (one source of
+truth for revocation, admin UI introspection). Requires a valid
+~/.parachute/operator.token (run \`parachute auth set-password\` or
+\`rotate-operator\` first).
+
+revoke-token flips \`revoked_at\` on a registry row by jti. The
+revocation list endpoint
+(\`/.well-known/parachute-revocation.json\`) picks the change up on
+its next 60s poll; resource servers (vault / scribe / agent) on
+scope-guard 0.2.0+ then reject the JWT. Idempotent: re-revoking an
+already-revoked jti prints the existing revoked_at and exits 0.
+Requires \`parachute:host:auth\` on the operator token (the \`auth\`
+or \`admin\` scope-set).
 
 pending-clients + approve-client gate /oauth/register against operator
 approval (closes #74). Self-served DCR registrations land as 'pending'
@@ -392,7 +457,46 @@ async function runSetPassword(args: readonly string[], deps: AuthDeps): Promise<
   }
 }
 
-async function runRotateOperator(deps: AuthDeps): Promise<number> {
+interface RotateOperatorFlags {
+  scopeSet?: OperatorScopeSet;
+  error?: string;
+}
+
+function parseRotateOperatorFlags(args: readonly string[]): RotateOperatorFlags {
+  let scopeSet: OperatorScopeSet | undefined;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--scope-set") {
+      const v = args[++i];
+      if (!v) return { error: "--scope-set requires a value" };
+      if (!isOperatorScopeSet(v)) {
+        return {
+          error: `--scope-set must be one of ${OPERATOR_TOKEN_SCOPE_SET_NAMES.join("|")}, got "${v}"`,
+        };
+      }
+      scopeSet = v;
+    } else if (a?.startsWith("--scope-set=")) {
+      const v = a.slice("--scope-set=".length);
+      if (!v) return { error: "--scope-set requires a value" };
+      if (!isOperatorScopeSet(v)) {
+        return {
+          error: `--scope-set must be one of ${OPERATOR_TOKEN_SCOPE_SET_NAMES.join("|")}, got "${v}"`,
+        };
+      }
+      scopeSet = v;
+    } else {
+      return { error: `unknown flag "${a}"` };
+    }
+  }
+  return scopeSet !== undefined ? { scopeSet } : {};
+}
+
+async function runRotateOperator(args: readonly string[], deps: AuthDeps): Promise<number> {
+  const flags = parseRotateOperatorFlags(args);
+  if (flags.error) {
+    console.error(`parachute auth rotate-operator: ${flags.error}`);
+    return 1;
+  }
   const db = deps.dbPath ? openHubDb(deps.dbPath) : openHubDb();
   try {
     const users = listUsers(db);
@@ -406,9 +510,11 @@ async function runRotateOperator(deps: AuthDeps): Promise<number> {
     const issued = await issueOperatorToken(db, owner.id, {
       dir: deps.configDir,
       issuer: resolveHubIssuer(deps.hubOrigin, deps.configDir ?? CONFIG_DIR),
+      ...(flags.scopeSet !== undefined ? { scopeSet: flags.scopeSet } : {}),
     });
     console.log("Rotated operator token.");
     console.log(`  user:       ${owner.username}`);
+    console.log(`  scope_set:  ${issued.scopeSet}`);
     console.log(`  path:       ${issued.path}`);
     console.log(`  expires_at: ${issued.expiresAt}`);
     console.log(
@@ -594,7 +700,11 @@ interface MintTokenFlags {
   scope?: string;
   aud?: string;
   ttl?: string;
+  expiresIn?: string;
   sub?: string;
+  permissions?: string;
+  /** True when --ttl was used (deprecated alias). Triggers a one-line stderr warning. */
+  ttlDeprecationSeen?: boolean;
   error?: string;
 }
 
@@ -602,7 +712,10 @@ function parseMintTokenFlags(args: readonly string[]): MintTokenFlags {
   let scope: string | undefined;
   let aud: string | undefined;
   let ttl: string | undefined;
+  let expiresIn: string | undefined;
   let sub: string | undefined;
+  let permissions: string | undefined;
+  let ttlDeprecationSeen = false;
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
     if (a === "--scope") {
@@ -623,9 +736,18 @@ function parseMintTokenFlags(args: readonly string[]): MintTokenFlags {
       const v = args[++i];
       if (!v) return { error: "--ttl requires a value" };
       ttl = v;
+      ttlDeprecationSeen = true;
     } else if (a?.startsWith("--ttl=")) {
       ttl = a.slice("--ttl=".length);
       if (!ttl) return { error: "--ttl requires a value" };
+      ttlDeprecationSeen = true;
+    } else if (a === "--expires-in") {
+      const v = args[++i];
+      if (!v) return { error: "--expires-in requires a value" };
+      expiresIn = v;
+    } else if (a?.startsWith("--expires-in=")) {
+      expiresIn = a.slice("--expires-in=".length);
+      if (!expiresIn) return { error: "--expires-in requires a value" };
     } else if (a === "--sub") {
       const v = args[++i];
       if (!v) return { error: "--sub requires a value" };
@@ -633,11 +755,21 @@ function parseMintTokenFlags(args: readonly string[]): MintTokenFlags {
     } else if (a?.startsWith("--sub=")) {
       sub = a.slice("--sub=".length);
       if (!sub) return { error: "--sub requires a value" };
+    } else if (a === "--permissions") {
+      const v = args[++i];
+      if (!v) return { error: "--permissions requires a value" };
+      permissions = v;
+    } else if (a?.startsWith("--permissions=")) {
+      permissions = a.slice("--permissions=".length);
+      if (!permissions) return { error: "--permissions requires a value" };
     } else {
       return { error: `unknown flag "${a}"` };
     }
   }
-  return { scope, aud, ttl, sub };
+  if (ttl !== undefined && expiresIn !== undefined) {
+    return { error: "pass --expires-in OR --ttl, not both (--ttl is the deprecated alias)" };
+  }
+  return { scope, aud, ttl, expiresIn, sub, permissions, ttlDeprecationSeen };
 }
 
 const MINT_TOKEN_TTL_DEFAULT_SECONDS = 90 * 24 * 60 * 60;
@@ -645,9 +777,9 @@ const MINT_TOKEN_TTL_MAX_SECONDS = 365 * 24 * 60 * 60;
 
 /**
  * Parse a Go-ish duration string: integer + one of d/h/m/s. Caps at 365d.
- * `90d` → 7776000. We don't honor Go's stdlib `time.ParseDuration` exactly
- * (no `d` there), so this is a small custom parser to keep the operator
- * surface obvious.
+ * `90d` → 7776000. Used by the deprecated --ttl alias. The canonical
+ * --expires-in flag takes a raw integer seconds value (per OAuth's
+ * `expires_in` claim semantics — see `parseExpiresIn`).
  */
 function parseTtl(input: string): { seconds: number } | { error: string } {
   const m = /^(\d+)(d|h|m|s)$/.exec(input);
@@ -663,6 +795,29 @@ function parseTtl(input: string): { seconds: number } | { error: string } {
   return { seconds };
 }
 
+/**
+ * Parse the canonical --expires-in flag value as an integer seconds count.
+ * Matches OAuth's `expires_in` claim semantics — the JWT `exp` is
+ * `iat + expires_in`. Caps at 365d like the deprecated --ttl path.
+ */
+function parseExpiresIn(input: string): { seconds: number } | { error: string } {
+  if (!/^\d+$/.test(input)) {
+    return {
+      error: `invalid --expires-in "${input}" — expected an integer seconds count (e.g. 86400 = 1 day)`,
+    };
+  }
+  const seconds = Number.parseInt(input, 10);
+  if (!Number.isFinite(seconds) || seconds <= 0) {
+    return { error: `invalid --expires-in "${input}" — must be > 0` };
+  }
+  if (seconds > MINT_TOKEN_TTL_MAX_SECONDS) {
+    return {
+      error: `--expires-in "${input}" exceeds 365d cap (${MINT_TOKEN_TTL_MAX_SECONDS} seconds)`,
+    };
+  }
+  return { seconds };
+}
+
 async function runMintToken(args: readonly string[], deps: AuthDeps): Promise<number> {
   const flags = parseMintTokenFlags(args);
   if (flags.error) {
@@ -672,7 +827,7 @@ async function runMintToken(args: readonly string[], deps: AuthDeps): Promise<nu
   if (!flags.scope) {
     console.error("parachute auth mint-token: --scope is required");
     console.error(
-      "usage: parachute auth mint-token --scope <scope> [--aud <aud>] [--ttl <duration>] [--sub <sub>]",
+      "usage: parachute auth mint-token --scope <scope> [--aud <aud>] [--expires-in <seconds>] [--sub <sub>] [--permissions <json>]",
     );
     return 1;
   }
@@ -683,8 +838,51 @@ async function runMintToken(args: readonly string[], deps: AuthDeps): Promise<nu
     return 1;
   }
 
+  // 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));
+  if (blocked.length > 0) {
+    console.error(
+      `parachute auth mint-token: scope ${blocked.join(", ")} is not requestable via mint-token; use OAuth flow or operator rotation`,
+    );
+    return 1;
+  }
+
+  let permissions: string | undefined;
+  if (flags.permissions !== undefined) {
+    try {
+      // Parse to validate well-formedness — round-trip through JSON.stringify
+      // so we hand the JWT a canonicalized payload (no operator-introduced
+      // whitespace, no comments, no trailing commas).
+      const parsed = JSON.parse(flags.permissions) as unknown;
+      if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        console.error(
+          'parachute auth mint-token: --permissions must be a JSON object (e.g. \'{"vault":{"default":{"write_tags":["health"]}}}\')',
+        );
+        return 1;
+      }
+      permissions = JSON.stringify(parsed);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(`parachute auth mint-token: --permissions is not valid JSON — ${msg}`);
+      return 1;
+    }
+  }
+
   let ttlSeconds = MINT_TOKEN_TTL_DEFAULT_SECONDS;
-  if (flags.ttl) {
+  if (flags.expiresIn) {
+    const parsed = parseExpiresIn(flags.expiresIn);
+    if ("error" in parsed) {
+      console.error(`parachute auth mint-token: ${parsed.error}`);
+      return 1;
+    }
+    ttlSeconds = parsed.seconds;
+  } else if (flags.ttl) {
     const parsed = parseTtl(flags.ttl);
     if ("error" in parsed) {
       console.error(`parachute auth mint-token: ${parsed.error}`);
@@ -692,49 +890,25 @@ async function runMintToken(args: readonly string[], deps: AuthDeps): Promise<nu
     }
     ttlSeconds = parsed.seconds;
   }
-
-  const configDir = deps.configDir ?? CONFIG_DIR;
-  const operatorToken = await readOperatorTokenFile(configDir);
-  if (!operatorToken) {
+  if (flags.ttlDeprecationSeen) {
     console.error(
-      "parachute auth mint-token: no operator token found at ~/.parachute/operator.token",
+      "parachute auth mint-token: --ttl is deprecated; use --expires-in <seconds> instead (will be removed in 0.6.0)",
     );
-    console.error(
-      "run `parachute auth set-password` (first run) or `parachute auth rotate-operator` to mint one",
-    );
-    return 1;
   }
 
+  const configDir = deps.configDir ?? CONFIG_DIR;
   const issuer = resolveHubIssuer(deps.hubOrigin, configDir);
 
   const db = deps.dbPath ? openHubDb(deps.dbPath) : openHubDb();
   try {
-    let operatorSub: string;
+    let used: Awaited<ReturnType<typeof useOperatorTokenWithAutoRotate>>;
     try {
-      const validated = await validateAccessToken(db, operatorToken, issuer);
-      const sub = validated.payload.sub;
-      if (typeof sub !== "string" || sub.length === 0) {
-        console.error("parachute auth mint-token: operator token has no sub claim");
-        return 1;
-      }
-      // Scope gate: a valid signature + non-expired JWT at this path is not
-      // sufficient — the token must carry operator-equivalent scope. Without
-      // this, a narrowly-scoped JWT stashed at ~/.parachute/operator.token
-      // would be treated as operator-bearer and mint arbitrary tokens
-      // (privilege escalation: narrow → arbitrary). Only set-password and
-      // rotate-operator legitimately write to this path; both seed the full
-      // OPERATOR_TOKEN_SCOPES set, so hub:admin is the right gate.
-      const tokenScope =
-        typeof validated.payload.scope === "string"
-          ? validated.payload.scope.split(/\s+/).filter((s) => s.length > 0)
-          : [];
-      if (!tokenScope.includes("hub:admin")) {
-        console.error("parachute auth mint-token: operator token lacks hub:admin scope");
-        console.error("run `parachute auth rotate-operator` to mint a fresh one");
+      used = await useOperatorTokenWithAutoRotate(db, { configDir, issuer });
+    } catch (err) {
+      if (err instanceof OperatorTokenExpiredError) {
+        console.error(`parachute auth mint-token: ${err.message}`);
         return 1;
       }
-      operatorSub = sub;
-    } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       console.error(`parachute auth mint-token: operator token invalid — ${msg}`);
       console.error(
@@ -742,18 +916,79 @@ async function runMintToken(args: readonly string[], deps: AuthDeps): Promise<nu
       );
       return 1;
     }
+    if (!used) {
+      console.error(
+        "parachute auth mint-token: no operator token found at ~/.parachute/operator.token",
+      );
+      console.error(
+        "run `parachute auth set-password` (first run) or `parachute auth rotate-operator` to mint one",
+      );
+      return 1;
+    }
+    if (used.rotated) {
+      console.error(
+        `parachute auth mint-token: operator token within 7d of expiry — auto-rotated to ${used.rotated.expiresAt} (scope_set=${used.rotated.scopeSet})`,
+      );
+    }
+    const operatorSub = used.payload.sub;
+    if (typeof operatorSub !== "string" || operatorSub.length === 0) {
+      console.error("parachute auth mint-token: operator token has no sub claim");
+      return 1;
+    }
+    // Scope gate: a valid signature + non-expired JWT at this path is not
+    // sufficient — the token must carry mint-token authority. Without this,
+    // a narrowly-scoped JWT stashed at ~/.parachute/operator.token would be
+    // treated as operator-bearer and mint arbitrary tokens (privilege
+    // escalation: narrow → arbitrary). Only set-password and rotate-operator
+    // legitimately write to this path.
+    //
+    // Gate is `parachute:host:auth` (was `hub:admin` through 0.5.8-rc.4 — see
+    // hub#222). Both the `admin` scope-set (which includes `:host:auth` as a
+    // superset) and the `auth` scope-set (which IS `:host:auth`) qualify; the
+    // `auth` scope-set was always meant to gate auth surfaces per the #214
+    // design, but the CLI mint-token gate was historically narrower than the
+    // HTTP equivalent. This brings the two surfaces into alignment.
+    const tokenScope =
+      typeof used.payload.scope === "string"
+        ? used.payload.scope.split(/\s+/).filter((s) => s.length > 0)
+        : [];
+    if (!tokenScope.includes("parachute:host:auth")) {
+      console.error("parachute auth mint-token: operator token lacks parachute:host:auth scope");
+      console.error(
+        "narrowed scope-sets without `auth` (install/start/expose/vault) can't mint follow-on tokens — run `parachute auth rotate-operator --scope-set auth` (or `admin`) for a token that can",
+      );
+      return 1;
+    }
 
     const audience = flags.aud ?? inferAudience(scopes);
-    const sub = flags.sub ?? operatorSub;
+    const subjectForMint = flags.sub ?? operatorSub;
+    const permissionsClaim = permissions !== undefined ? JSON.parse(permissions) : undefined;
 
     const minted = await signAccessToken(db, {
-      sub,
+      sub: subjectForMint,
       scopes,
       audience,
       clientId: OPERATOR_TOKEN_CLIENT_ID,
       issuer,
       ttlSeconds,
+      ...(permissionsClaim !== undefined ? { extraClaims: { permissions: permissionsClaim } } : {}),
+    });
+
+    // Write a registry row (hub#212 Phase 1). Powers the revocation list
+    // endpoint and admin UI introspection. Per design: CLI-mint rows have
+    // user_id NULL; the subject column carries the chosen mint subject
+    // (--sub overrides operator-sub). The JWT is its own access token,
+    // not a refresh token, so refresh_token_hash + family_id stay NULL.
+    recordTokenMint(db, {
+      jti: minted.jti,
+      createdVia: "cli_mint",
+      subject: subjectForMint,
+      clientId: OPERATOR_TOKEN_CLIENT_ID,
+      scopes,
+      expiresAt: minted.expiresAt,
+      ...(permissions !== undefined ? { permissions } : {}),
     });
+
     console.log(minted.token);
     return 0;
   } finally {
@@ -761,6 +996,119 @@ async function runMintToken(args: readonly string[], deps: AuthDeps): Promise<nu
   }
 }
 
+async function runRevokeToken(args: readonly string[], deps: AuthDeps): Promise<number> {
+  // Single positional: the jti. No flags. (If we grow flags later — say,
+  // --reason for an audit string — they can join here without disrupting
+  // the positional contract.)
+  const positionals = args.filter((a) => !a.startsWith("--"));
+  const flags = args.filter((a) => a.startsWith("--"));
+  if (flags.length > 0) {
+    console.error(
+      `parachute auth revoke-token: unexpected flag "${flags[0]}" (this command takes a jti positional only)`,
+    );
+    return 1;
+  }
+  if (positionals.length === 0) {
+    console.error("parachute auth revoke-token: missing jti argument");
+    console.error("usage: parachute auth revoke-token <jti>");
+    return 1;
+  }
+  if (positionals.length > 1) {
+    console.error(
+      `parachute auth revoke-token: unexpected argument "${positionals[1]}" (only one jti at a time)`,
+    );
+    return 1;
+  }
+  const jti = positionals[0]!;
+
+  const configDir = deps.configDir ?? CONFIG_DIR;
+  const issuer = resolveHubIssuer(deps.hubOrigin, configDir);
+
+  const db = deps.dbPath ? openHubDb(deps.dbPath) : openHubDb();
+  try {
+    let used: Awaited<ReturnType<typeof useOperatorTokenWithAutoRotate>>;
+    try {
+      used = await useOperatorTokenWithAutoRotate(db, { configDir, issuer });
+    } catch (err) {
+      if (err instanceof OperatorTokenExpiredError) {
+        console.error(`parachute auth revoke-token: ${err.message}`);
+        return 1;
+      }
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(`parachute auth revoke-token: operator token invalid — ${msg}`);
+      console.error(
+        "run `parachute auth rotate-operator` to mint a fresh one, or check that the hub origin matches",
+      );
+      return 1;
+    }
+    if (!used) {
+      console.error(
+        "parachute auth revoke-token: no operator token found at ~/.parachute/operator.token",
+      );
+      console.error(
+        "run `parachute auth set-password` (first run) or `parachute auth rotate-operator` to mint one",
+      );
+      return 1;
+    }
+    if (used.rotated) {
+      console.error(
+        `parachute auth revoke-token: operator token within 7d of expiry — auto-rotated to ${used.rotated.expiresAt} (scope_set=${used.rotated.scopeSet})`,
+      );
+    }
+    // Scope gate: same as the HTTP /api/auth/revoke-token endpoint will use
+    // (and the same as /api/auth/mint-token uses today). Mirrors the
+    // privilege-shape of mint — both surfaces hand the operator power that
+    // a narrow non-auth scope-set token shouldn't carry. The `auth`
+    // scope-set covers this; so does `admin` (superset).
+    const tokenScope =
+      typeof used.payload.scope === "string"
+        ? used.payload.scope.split(/\s+/).filter((s) => s.length > 0)
+        : [];
+    if (!tokenScope.includes("parachute:host:auth")) {
+      console.error("parachute auth revoke-token: operator token lacks parachute:host:auth scope");
+      console.error(
+        "narrowed scope-sets without `auth` (install/start/expose/vault) can't revoke tokens — run `parachute auth rotate-operator --scope-set auth` (or `admin`) for a token that can",
+      );
+      return 1;
+    }
+
+    const row = findTokenRowByJti(db, jti);
+    if (!row) {
+      console.error(`parachute auth revoke-token: no token with jti ${jti} found in registry`);
+      return 1;
+    }
+    if (row.revokedAt) {
+      // Idempotent re-revoke. Surface the existing timestamp so an operator
+      // who's not sure whether the previous attempt landed gets a clear
+      // confirmation it did.
+      console.log(`already revoked at ${row.revokedAt}: jti=${jti}`);
+      return 0;
+    }
+    const ok = revokeTokenByJti(db, jti, new Date());
+    if (!ok) {
+      // Race: row existed, then disappeared or got revoked between our
+      // lookups. Surface as not-found rather than silently succeeding —
+      // the operator should know nothing changed under their hand.
+      console.error(
+        `parachute auth revoke-token: jti ${jti} could not be revoked (race or concurrent change)`,
+      );
+      return 1;
+    }
+    // Use the canonical `tokenRowIdentity` helper rather than reading
+    // userId/subject inline. The label is `identity=` (not `subject=`)
+    // because for OAuth-issued rows `userId` is the user UUID and the
+    // `subject` column is NULL; calling that field "subject" in the
+    // output would mislabel the UUID for any operator grepping on it.
+    // `identity=` matches what the helper returns regardless of row type.
+    console.log(
+      `revoked: jti=${jti}, identity=${tokenRowIdentity(row)}, scope=${row.scopes.join(" ") || "(none)"}`,
+    );
+    return 0;
+  } finally {
+    db.close();
+  }
+}
+
 function runListUsers(deps: AuthDeps): number {
   const db = deps.dbPath ? openHubDb(deps.dbPath) : openHubDb();
   try {
@@ -824,7 +1172,7 @@ export async function auth(args: readonly string[], deps: AuthDeps | Runner = {}
     }
     if (sub === "rotate-operator") {
       try {
-        return await runRotateOperator(normalized);
+        return await runRotateOperator(args.slice(1), normalized);
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         console.error(`parachute auth rotate-operator: ${msg}`);
@@ -840,6 +1188,15 @@ export async function auth(args: readonly string[], deps: AuthDeps | Runner = {}
         return 1;
       }
     }
+    if (sub === "revoke-token") {
+      try {
+        return await runRevokeToken(args.slice(1), normalized);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`parachute auth revoke-token: ${msg}`);
+        return 1;
+      }
+    }
     if (sub === "pending-clients") {
       try {
         return runPendingClients(normalized);