@openparachute/hub 0.5.0 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "parachute — the local hub for the Parachute ecosystem (discovery, ports, lifecycle, soon OAuth).",
   "license": "AGPL-3.0",
   "publishConfig": {

package/src/__tests__/auth.test.ts

@@ -6,11 +6,13 @@ import { registerClient } from "../clients.ts";
 import { type AuthDeps, type Runner, auth, authHelp } from "../commands/auth.ts";
 import { findGrant, recordGrant } from "../grants.ts";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
-import { validateAccessToken } from "../jwt-sign.ts";
+import { signAccessToken, validateAccessToken } from "../jwt-sign.ts";
 import {
   OPERATOR_TOKEN_AUDIENCE,
+  OPERATOR_TOKEN_CLIENT_ID,
   OPERATOR_TOKEN_SCOPES,
   readOperatorTokenFile,
+  writeOperatorTokenFile,
 } from "../operator-token.ts";
 import { createUser, listUsers, verifyPassword } from "../users.ts";
 
@@ -794,3 +796,352 @@ describe("parachute auth list-grants / revoke-grant", () => {
     }
   });
 });
+
+// closes #179 — scope-narrow JWT minting against operator identity, for
+// agent-secret injection and other on-box callers that want a tight bearer.
+describe("parachute auth mint-token", () => {
+  test("missing --scope is a usage error", async () => {
+    const tmp = makeTmp();
+    try {
+      const { code, stderr } = await captureOutput(() =>
+        auth(["mint-token"], { dbPath: tmp.dbPath, configDir: tmp.dir }),
+      );
+      expect(code).toBe(1);
+      expect(stderr).toContain("--scope is required");
+    } finally {
+      tmp.cleanup();
+    }
+  });
+
+  test("no operator.token on disk is an actionable error", async () => {
+    const tmp = makeTmp();
+    try {
+      const { code, stderr } = await captureOutput(() =>
+        auth(["mint-token", "--scope", "scribe:transcribe"], {
+          dbPath: tmp.dbPath,
+          configDir: tmp.dir,
+        }),
+      );
+      expect(code).toBe(1);
+      expect(stderr).toContain("operator.token");
+      expect(stderr).toContain("rotate-operator");
+    } finally {
+      tmp.cleanup();
+    }
+  });
+
+  test("scope-only mint emits a JWT signed by the active key, audience inferred", async () => {
+    const tmp = makeTmp();
+    try {
+      const deps: AuthDeps = {
+        dbPath: tmp.dbPath,
+        configDir: tmp.dir,
+        isInteractive: () => false,
+      };
+      await captureOutput(() => auth(["set-password", "--password", "pw"], deps));
+      const { code, stdout } = await captureOutput(() =>
+        auth(["mint-token", "--scope", "scribe:transcribe"], deps),
+      );
+      expect(code).toBe(0);
+      const token = stdout.trim();
+      expect(token.split(".").length).toBe(3);
+      // Strict purity: stdout is exactly the token + trailing newline,
+      // nothing extra. Pipes (`| pbcopy`, `| jq`) depend on this.
+      expect(stdout).toBe(`${token}\n`);
+      const db = openHubDb(tmp.dbPath);
+      try {
+        const validated = await validateAccessToken(db, token);
+        expect(validated.payload.aud).toBe("scribe");
+        expect(validated.payload.scope).toBe("scribe:transcribe");
+        const users = listUsers(db);
+        expect(validated.payload.sub).toBe(users[0]?.id);
+      } finally {
+        db.close();
+      }
+    } finally {
+      tmp.cleanup();
+    }
+  });
+
+  test("operator token without hub:admin scope is rejected (no token emitted)", async () => {
+    const tmp = makeTmp();
+    try {
+      const deps: AuthDeps = {
+        dbPath: tmp.dbPath,
+        configDir: tmp.dir,
+        isInteractive: () => false,
+      };
+      // Bootstrap: set-password to seed the user + signing key.
+      await captureOutput(() => auth(["set-password", "--password", "pw"], deps));
+      // Now overwrite operator.token with a valid-signature, valid-expiry
+      // JWT that lacks hub:admin — simulating someone stashing a narrow
+      // token at the operator path.
+      const db = openHubDb(tmp.dbPath);
+      let narrow: string;
+      try {
+        const owner = listUsers(db)[0]!;
+        const signed = await signAccessToken(db, {
+          sub: owner.id,
+          scopes: ["scribe:transcribe"],
+          audience: "scribe",
+          clientId: OPERATOR_TOKEN_CLIENT_ID,
+          issuer: "http://127.0.0.1:1939",
+          ttlSeconds: 3600,
+        });
+        narrow = signed.token;
+      } finally {
+        db.close();
+      }
+      await writeOperatorTokenFile(narrow, tmp.dir);
+
+      const { code, stdout, stderr } = await captureOutput(() =>
+        auth(["mint-token", "--scope", "scribe:transcribe"], deps),
+      );
+      expect(code).toBe(1);
+      expect(stderr).toContain("lacks hub:admin scope");
+      expect(stderr).toContain("rotate-operator");
+      // Purity: no token written to stdout.
+      expect(stdout).toBe("");
+    } finally {
+      tmp.cleanup();
+    }
+  });
+
+  test("named vault scope infers aud=vault.<name>", async () => {
+    const tmp = makeTmp();
+    try {
+      const deps: AuthDeps = {
+        dbPath: tmp.dbPath,
+        configDir: tmp.dir,
+        isInteractive: () => false,
+      };
+      await captureOutput(() => auth(["set-password", "--password", "pw"], deps));
+      const { code, stdout } = await captureOutput(() =>
+        auth(["mint-token", "--scope", "vault:work:read"], deps),
+      );
+      expect(code).toBe(0);
+      const token = stdout.trim();
+      const db = openHubDb(tmp.dbPath);
+      try {
+        const validated = await validateAccessToken(db, token);
+        expect(validated.payload.aud).toBe("vault.work");
+      } finally {
+        db.close();
+      }
+    } finally {
+      tmp.cleanup();
+    }
+  });
+
+  test("--aud override beats inference", async () => {
+    const tmp = makeTmp();
+    try {
+      const deps: AuthDeps = {
+        dbPath: tmp.dbPath,
+        configDir: tmp.dir,
+        isInteractive: () => false,
+      };
+      await captureOutput(() => auth(["set-password", "--password", "pw"], deps));
+      const { code, stdout } = await captureOutput(() =>
+        auth(["mint-token", "--scope", "vault:work:read", "--aud", "custom-resource"], deps),
+      );
+      expect(code).toBe(0);
+      const token = stdout.trim();
+      const db = openHubDb(tmp.dbPath);
+      try {
+        const validated = await validateAccessToken(db, token);
+        expect(validated.payload.aud).toBe("custom-resource");
+      } finally {
+        db.close();
+      }
+    } finally {
+      tmp.cleanup();
+    }
+  });
+
+  test("--ttl honored; expiry math matches", async () => {
+    const tmp = makeTmp();
+    try {
+      const deps: AuthDeps = {
+        dbPath: tmp.dbPath,
+        configDir: tmp.dir,
+        isInteractive: () => false,
+      };
+      await captureOutput(() => auth(["set-password", "--password", "pw"], deps));
+      const { code, stdout } = await captureOutput(() =>
+        auth(["mint-token", "--scope", "scribe:transcribe", "--ttl", "1h"], deps),
+      );
+      expect(code).toBe(0);
+      const token = stdout.trim();
+      const db = openHubDb(tmp.dbPath);
+      try {
+        const validated = await validateAccessToken(db, token);
+        const exp = validated.payload.exp;
+        const iat = validated.payload.iat;
+        if (typeof exp !== "number" || typeof iat !== "number") {
+          throw new Error("expected numeric exp+iat");
+        }
+        expect(exp - iat).toBe(3600);
+      } finally {
+        db.close();
+      }
+    } finally {
+      tmp.cleanup();
+    }
+  });
+
+  test("--ttl=365d is accepted (boundary)", async () => {
+    const tmp = makeTmp();
+    try {
+      const deps: AuthDeps = {
+        dbPath: tmp.dbPath,
+        configDir: tmp.dir,
+        isInteractive: () => false,
+      };
+      await captureOutput(() => auth(["set-password", "--password", "pw"], deps));
+      const { code, stdout } = await captureOutput(() =>
+        auth(["mint-token", "--scope", "scribe:transcribe", "--ttl", "365d"], deps),
+      );
+      expect(code).toBe(0);
+      const token = stdout.trim();
+      const db = openHubDb(tmp.dbPath);
+      try {
+        const validated = await validateAccessToken(db, token);
+        const exp = validated.payload.exp;
+        const iat = validated.payload.iat;
+        if (typeof exp !== "number" || typeof iat !== "number") {
+          throw new Error("expected numeric exp+iat");
+        }
+        expect(exp - iat).toBe(365 * 24 * 60 * 60);
+      } finally {
+        db.close();
+      }
+    } finally {
+      tmp.cleanup();
+    }
+  });
+
+  test("--ttl=0s is rejected (must be > 0)", async () => {
+    const tmp = makeTmp();
+    try {
+      const deps: AuthDeps = {
+        dbPath: tmp.dbPath,
+        configDir: tmp.dir,
+        isInteractive: () => false,
+      };
+      await captureOutput(() => auth(["set-password", "--password", "pw"], deps));
+      const { code, stderr } = await captureOutput(() =>
+        auth(["mint-token", "--scope", "scribe:transcribe", "--ttl", "0s"], deps),
+      );
+      expect(code).toBe(1);
+      expect(stderr).toContain("must be > 0");
+    } finally {
+      tmp.cleanup();
+    }
+  });
+
+  test("--ttl > 365d errors", async () => {
+    const tmp = makeTmp();
+    try {
+      const deps: AuthDeps = {
+        dbPath: tmp.dbPath,
+        configDir: tmp.dir,
+        isInteractive: () => false,
+      };
+      await captureOutput(() => auth(["set-password", "--password", "pw"], deps));
+      const { code, stderr } = await captureOutput(() =>
+        auth(["mint-token", "--scope", "scribe:transcribe", "--ttl", "400d"], deps),
+      );
+      expect(code).toBe(1);
+      expect(stderr).toContain("365d cap");
+    } finally {
+      tmp.cleanup();
+    }
+  });
+
+  test("--ttl with invalid format errors", async () => {
+    const tmp = makeTmp();
+    try {
+      const deps: AuthDeps = {
+        dbPath: tmp.dbPath,
+        configDir: tmp.dir,
+        isInteractive: () => false,
+      };
+      await captureOutput(() => auth(["set-password", "--password", "pw"], deps));
+      const { code, stderr } = await captureOutput(() =>
+        auth(["mint-token", "--scope", "scribe:transcribe", "--ttl", "1week"], deps),
+      );
+      expect(code).toBe(1);
+      expect(stderr).toContain("invalid --ttl");
+    } finally {
+      tmp.cleanup();
+    }
+  });
+
+  test("multiple scopes (space-separated) carried verbatim into the JWT", async () => {
+    const tmp = makeTmp();
+    try {
+      const deps: AuthDeps = {
+        dbPath: tmp.dbPath,
+        configDir: tmp.dir,
+        isInteractive: () => false,
+      };
+      await captureOutput(() => auth(["set-password", "--password", "pw"], deps));
+      const { code, stdout } = await captureOutput(() =>
+        auth(["mint-token", "--scope", "vault:work:read scribe:transcribe"], deps),
+      );
+      expect(code).toBe(0);
+      const token = stdout.trim();
+      const db = openHubDb(tmp.dbPath);
+      try {
+        const validated = await validateAccessToken(db, token);
+        expect(validated.payload.scope).toBe("vault:work:read scribe:transcribe");
+        // Named vault scope wins for audience inference.
+        expect(validated.payload.aud).toBe("vault.work");
+      } finally {
+        db.close();
+      }
+    } finally {
+      tmp.cleanup();
+    }
+  });
+
+  test("--sub override emits the JWT with that subject", async () => {
+    const tmp = makeTmp();
+    try {
+      const deps: AuthDeps = {
+        dbPath: tmp.dbPath,
+        configDir: tmp.dir,
+        isInteractive: () => false,
+      };
+      await captureOutput(() => auth(["set-password", "--password", "pw"], deps));
+      const { code, stdout } = await captureOutput(() =>
+        auth(["mint-token", "--scope", "scribe:transcribe", "--sub", "agent:scribe-runner"], deps),
+      );
+      expect(code).toBe(0);
+      const token = stdout.trim();
+      const db = openHubDb(tmp.dbPath);
+      try {
+        const validated = await validateAccessToken(db, token);
+        expect(validated.payload.sub).toBe("agent:scribe-runner");
+      } finally {
+        db.close();
+      }
+    } finally {
+      tmp.cleanup();
+    }
+  });
+
+  test("unknown flag errors", async () => {
+    const tmp = makeTmp();
+    try {
+      const { code, stderr } = await captureOutput(() =>
+        auth(["mint-token", "--lol"], { dbPath: tmp.dbPath, configDir: tmp.dir }),
+      );
+      expect(code).toBe(1);
+      expect(stderr).toContain("unknown flag");
+    } finally {
+      tmp.cleanup();
+    }
+  });
+});

package/src/__tests__/lifecycle.test.ts

@@ -517,9 +517,13 @@ describe("parachute start", () => {
     }
   });
 
-  test("third-party with no installDir errors as unknown service", async () => {
-    // A row whose name isn't a known short name AND has no installDir is
-    // unmanageable — we have no way to find a spec for it.
+  test("start: installDir-less third-party row surfaces an actionable error", async () => {
+    // A services.json row whose name isn't first-party AND has no installDir
+    // can't yield a startCmd. Pre-fix this hit the generic "unknown service"
+    // path (misleading — the row exists, just with stale shape). Post-fix
+    // resolveTargets returns the entry with spec=undefined and start prints
+    // an actionable message that points at the real fix (re-install or
+    // upgrade-the-module).
     const h = makeHarness();
     try {
       upsertService(
@@ -539,7 +543,30 @@ describe("parachute start", () => {
         log: (l) => lines.push(l),
       });
       expect(code).toBe(1);
-      expect(lines.join("\n")).toMatch(/unknown service "mystery"/);
+      const out = lines.join("\n");
+      expect(out).toMatch(/services\.json entry has no installDir/);
+      expect(out).toMatch(/parachute install <path-to-mystery>/);
+      expect(out).not.toMatch(/unknown service/);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("start: name absent from services.json still errors as unknown service", async () => {
+    // The genuinely-unknown path: no first-party fallback, no row in
+    // services.json. Distinguish from the above (row exists but lacks
+    // installDir) so the error message is right-shaped for each.
+    const h = makeHarness();
+    try {
+      seedVault(h.manifestPath);
+      const lines: string[] = [];
+      const code = await start("ghost", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        log: (l) => lines.push(l),
+      });
+      expect(code).toBe(1);
+      expect(lines.join("\n")).toMatch(/unknown service "ghost"/);
     } finally {
       h.cleanup();
     }
@@ -721,6 +748,45 @@ describe("parachute stop", () => {
       h.cleanup();
     }
   });
+
+  test("third-party row without installDir: stops via pidfile", async () => {
+    // Graceful-degradation path: an installed-but-stale third-party row
+    // (no installDir field — pre-installDir-contract self-registration)
+    // should still be stoppable. stop only needs the short name to find
+    // the pidfile; spec resolution isn't on the critical path for stop.
+    const h = makeHarness();
+    try {
+      upsertService(
+        {
+          name: "mystery",
+          port: 1944,
+          paths: ["/mystery"],
+          health: "/mystery/health",
+          version: "0.0.1",
+        },
+        h.manifestPath,
+      );
+      writePid("mystery", 4242, h.configDir);
+      const killed: Array<[number, string | number]> = [];
+      let aliveCall = 0;
+      const code = await stop("mystery", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        kill: (pid, sig) => killed.push([pid, sig]),
+        alive: () => {
+          aliveCall++;
+          return aliveCall === 1;
+        },
+        sleep: async () => {},
+        log: () => {},
+      });
+      expect(code).toBe(0);
+      expect(killed).toEqual([[4242, "SIGTERM"]]);
+      expect(readPid("mystery", h.configDir)).toBeUndefined();
+    } finally {
+      h.cleanup();
+    }
+  });
 });
 
 describe("parachute restart", () => {
@@ -822,6 +888,37 @@ describe("parachute logs", () => {
       h.cleanup();
     }
   });
+
+  test("third-party row without installDir: tails by short name", async () => {
+    // Graceful-degradation path: log file is keyed by short name, written by
+    // start. installDir is irrelevant for tailing — the entry just needs to
+    // exist in services.json.
+    const h = makeHarness();
+    try {
+      upsertService(
+        {
+          name: "mystery",
+          port: 1944,
+          paths: ["/mystery"],
+          health: "/mystery/health",
+          version: "0.0.1",
+        },
+        h.manifestPath,
+      );
+      const p = ensureLogPath("mystery", h.configDir);
+      writeFileSync(p, "mystery line 1\nmystery line 2\n");
+      const lines: string[] = [];
+      const code = await logs("mystery", {
+        configDir: h.configDir,
+        manifestPath: h.manifestPath,
+        log: (l) => lines.push(l),
+      });
+      expect(code).toBe(0);
+      expect(lines).toEqual(["mystery line 1", "mystery line 2"]);
+    } finally {
+      h.cleanup();
+    }
+  });
 });
 
 describe("process-group lifecycle (hub#88)", () => {

package/src/commands/auth.ts

@@ -25,7 +25,13 @@ import { listGrantsForUser, revokeGrant } from "../grants.ts";
 import { HUB_DEFAULT_PORT, readHubPort } from "../hub-control.ts";
 import { openHubDb } from "../hub-db.ts";
 import { deriveHubOrigin } from "../hub-origin.ts";
-import { issueOperatorToken } from "../operator-token.ts";
+import { inferAudience } from "../jwt-audience.ts";
+import { signAccessToken, validateAccessToken } from "../jwt-sign.ts";
+import {
+  OPERATOR_TOKEN_CLIENT_ID,
+  issueOperatorToken,
+  readOperatorTokenFile,
+} from "../operator-token.ts";
 import { rotateSigningKey } from "../signing-keys.ts";
 import {
   SingleUserModeError,
@@ -54,6 +60,7 @@ const HUB_LOCAL_SUBCOMMANDS = new Set([
   "set-password",
   "list-users",
   "rotate-operator",
+  "mint-token",
   "pending-clients",
   "approve-client",
   "list-grants",
@@ -73,6 +80,9 @@ Usage:
   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>]
+                                       Mint a scope-narrow JWT against the
+                                       operator's identity (stdout = JWT)
   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>]
@@ -104,6 +114,15 @@ rotate-operator mints a fresh long-lived operator token at
 as their bearer when calling on-box services. set-password also writes
 the file on first-run / password reset.
 
+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).
+
 pending-clients + approve-client gate /oauth/register against operator
 approval (closes #74). Self-served DCR registrations land as 'pending'
 and cannot OAuth until you run \`parachute auth approve-client <id>\`.
@@ -571,6 +590,177 @@ function runRevokeGrant(args: readonly string[], deps: AuthDeps): number {
   }
 }
 
+interface MintTokenFlags {
+  scope?: string;
+  aud?: string;
+  ttl?: string;
+  sub?: string;
+  error?: string;
+}
+
+function parseMintTokenFlags(args: readonly string[]): MintTokenFlags {
+  let scope: string | undefined;
+  let aud: string | undefined;
+  let ttl: string | undefined;
+  let sub: string | undefined;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--scope") {
+      const v = args[++i];
+      if (!v) return { error: "--scope requires a value" };
+      scope = v;
+    } else if (a?.startsWith("--scope=")) {
+      scope = a.slice("--scope=".length);
+      if (!scope) return { error: "--scope requires a value" };
+    } else if (a === "--aud") {
+      const v = args[++i];
+      if (!v) return { error: "--aud requires a value" };
+      aud = v;
+    } else if (a?.startsWith("--aud=")) {
+      aud = a.slice("--aud=".length);
+      if (!aud) return { error: "--aud requires a value" };
+    } else if (a === "--ttl") {
+      const v = args[++i];
+      if (!v) return { error: "--ttl requires a value" };
+      ttl = v;
+    } else if (a?.startsWith("--ttl=")) {
+      ttl = a.slice("--ttl=".length);
+      if (!ttl) return { error: "--ttl requires a value" };
+    } else if (a === "--sub") {
+      const v = args[++i];
+      if (!v) return { error: "--sub requires a value" };
+      sub = v;
+    } else if (a?.startsWith("--sub=")) {
+      sub = a.slice("--sub=".length);
+      if (!sub) return { error: "--sub requires a value" };
+    } else {
+      return { error: `unknown flag "${a}"` };
+    }
+  }
+  return { scope, aud, ttl, sub };
+}
+
+const MINT_TOKEN_TTL_DEFAULT_SECONDS = 90 * 24 * 60 * 60;
+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.
+ */
+function parseTtl(input: string): { seconds: number } | { error: string } {
+  const m = /^(\d+)(d|h|m|s)$/.exec(input);
+  if (!m) return { error: `invalid --ttl "${input}" — expected e.g. 90d, 24h, 30m, 60s` };
+  const n = Number.parseInt(m[1]!, 10);
+  if (!Number.isFinite(n) || n <= 0) return { error: `invalid --ttl "${input}" — must be > 0` };
+  const unit = m[2]!;
+  const mult = unit === "d" ? 86400 : unit === "h" ? 3600 : unit === "m" ? 60 : 1;
+  const seconds = n * mult;
+  if (seconds > MINT_TOKEN_TTL_MAX_SECONDS) {
+    return { error: `--ttl "${input}" exceeds 365d cap` };
+  }
+  return { seconds };
+}
+
+async function runMintToken(args: readonly string[], deps: AuthDeps): Promise<number> {
+  const flags = parseMintTokenFlags(args);
+  if (flags.error) {
+    console.error(`parachute auth mint-token: ${flags.error}`);
+    return 1;
+  }
+  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>]",
+    );
+    return 1;
+  }
+
+  const scopes = flags.scope.split(/\s+/).filter((s) => s.length > 0);
+  if (scopes.length === 0) {
+    console.error("parachute auth mint-token: --scope must contain at least one scope");
+    return 1;
+  }
+
+  let ttlSeconds = MINT_TOKEN_TTL_DEFAULT_SECONDS;
+  if (flags.ttl) {
+    const parsed = parseTtl(flags.ttl);
+    if ("error" in parsed) {
+      console.error(`parachute auth mint-token: ${parsed.error}`);
+      return 1;
+    }
+    ttlSeconds = parsed.seconds;
+  }
+
+  const configDir = deps.configDir ?? CONFIG_DIR;
+  const operatorToken = await readOperatorTokenFile(configDir);
+  if (!operatorToken) {
+    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;
+  }
+
+  const issuer = resolveHubIssuer(deps.hubOrigin, configDir);
+
+  const db = deps.dbPath ? openHubDb(deps.dbPath) : openHubDb();
+  try {
+    let operatorSub: string;
+    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");
+        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(
+        "run `parachute auth rotate-operator` to mint a fresh one, or check that the hub origin matches",
+      );
+      return 1;
+    }
+
+    const audience = flags.aud ?? inferAudience(scopes);
+    const sub = flags.sub ?? operatorSub;
+
+    const minted = await signAccessToken(db, {
+      sub,
+      scopes,
+      audience,
+      clientId: OPERATOR_TOKEN_CLIENT_ID,
+      issuer,
+      ttlSeconds,
+    });
+    console.log(minted.token);
+    return 0;
+  } finally {
+    db.close();
+  }
+}
+
 function runListUsers(deps: AuthDeps): number {
   const db = deps.dbPath ? openHubDb(deps.dbPath) : openHubDb();
   try {
@@ -641,6 +831,15 @@ export async function auth(args: readonly string[], deps: AuthDeps | Runner = {}
         return 1;
       }
     }
+    if (sub === "mint-token") {
+      try {
+        return await runMintToken(args.slice(1), normalized);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`parachute auth mint-token: ${msg}`);
+        return 1;
+      }
+    }
     if (sub === "pending-clients") {
       try {
         return runPendingClients(normalized);

package/src/commands/lifecycle.ts

@@ -214,8 +214,10 @@ interface ResolvedTarget {
    * Lifecycle spec resolved at request time. First-party comes from
    * `getSpec(short)`; third-party comes from
    * `getSpecFromInstallDir(entry.installDir, ...)`. May be undefined when
-   * a row has neither — lifecycle prints "lifecycle not yet supported"
-   * for that service rather than crashing the whole sweep.
+   * a row has neither — `start` prints the actionable "no installDir"
+   * re-install message for an installDir-less third-party row, or
+   * "lifecycle not yet supported" otherwise; `stop`/`logs` keep working
+   * via pidfile/logfile semantics keyed by `short`.
    */
   spec: ServiceSpec | undefined;
 }
@@ -248,6 +250,13 @@ async function specForEntry(
  * `module.json` (which is what install copied to `entry.name` for
  * third-party). First-party are addressed by their short name (vault,
  * notes, …) and matched via `shortNameForManifest`.
+ *
+ * Named-path detail: a third-party row whose name matches but lacks
+ * `installDir` resolves to the entry with `spec: undefined` (rather than
+ * an "unknown service" error). `stop`/`logs` handle the spec-less case
+ * via pidfile/logfile semantics; `start` surfaces an actionable
+ * re-install hint downstream. The genuinely-unknown path (no first-party
+ * fallback AND no row in services.json) still errors as `unknown service`.
  */
 async function resolveTargets(
   svc: string | undefined,
@@ -268,13 +277,19 @@ async function resolveTargets(
       }
       return { targets: [{ short: svc, entry, spec: firstPartySpec }] };
     }
-    // Third-party: match a services.json row by name. Third-party rows
-    // carry `installDir`; without it we have no way to resolve a spec.
+    // Third-party: match a services.json row by name. Rows with `installDir`
+    // resolve a full spec from the on-disk module.json. Rows without it are
+    // still managed (stop/logs use pidfile/logfile semantics keyed by short
+    // name), but with `spec: undefined` — `start` will surface an
+    // installDir-specific error downstream rather than reject up front.
     const entry = manifest.services.find((s) => s.name === svc);
-    if (entry?.installDir) {
-      const { spec, error } = await specForEntry(svc, entry);
-      if (error) return { error: `${svc}: invalid module.json — ${error}` };
-      return { targets: [{ short: svc, entry, spec }] };
+    if (entry) {
+      if (entry.installDir) {
+        const { spec, error } = await specForEntry(svc, entry);
+        if (error) return { error: `${svc}: invalid module.json — ${error}` };
+        return { targets: [{ short: svc, entry, spec }] };
+      }
+      return { targets: [{ short: svc, entry, spec: undefined }] };
     }
     return {
       error: `unknown service "${svc}". known: ${knownServices().join(", ")}`,
@@ -323,7 +338,17 @@ export async function start(svc: string | undefined, opts: LifecycleOpts = {}):
 
     const cmd = spec?.startCmd?.(entry);
     if (!cmd || cmd.length === 0) {
-      r.log(`${short}: lifecycle not yet supported for this service.`);
+      // Distinguish the missing-installDir case from "spec resolved but has
+      // no startCmd" — the former is fixable by re-registering the module,
+      // the latter is a hub-level limitation. Third-party rows hit the first
+      // branch when their self-registration predates the installDir contract.
+      if (!getSpec(short) && !entry.installDir) {
+        r.log(
+          `${short}: services.json entry has no installDir, so the start command can't be resolved. Re-run \`parachute install <path-to-${short}>\` to refresh its registration, or upgrade the module to a version that self-registers with installDir.`,
+        );
+      } else {
+        r.log(`${short}: lifecycle not yet supported for this service.`);
+      }
       failures++;
       continue;
     }
@@ -487,13 +512,14 @@ export async function logs(svc: string, opts: LogsOpts = {}): Promise<number> {
 
   // logs only needs a valid short name to find the log file. First-party
   // wins via the spec lookup; third-party rows match by `entry.name`; the
-  // internal hub is a known short outside of services.json. We don't need
-  // the full spec here — we just need to confirm the name maps to
-  // something the CLI manages.
+  // internal hub is a known short outside of services.json. installDir is
+  // irrelevant here — the log file is keyed by short name and exists once
+  // the service has run, regardless of how it was registered. We just need
+  // to confirm the name maps to something the CLI manages.
   const isFirstParty = getSpec(svc) !== undefined;
   if (!isFirstParty && svc !== HUB_SVC) {
     const entry = readManifest(manifestPath).services.find((s) => s.name === svc);
-    if (!entry?.installDir) {
+    if (!entry) {
       log(`unknown service "${svc}". known: ${[HUB_SVC, ...knownServices()].join(", ")}`);
       return 1;
     }

package/src/jwt-audience.ts

@@ -0,0 +1,40 @@
+/**
+ * Audience derivation for hub-issued JWTs. Used by both:
+ *   - `/oauth/token` (auth_code redemption + refresh rotation)
+ *   - `parachute auth mint-token` (CLI shortcut for scope-narrow tokens)
+ *
+ * Per the vault-config-and-scopes design (Phase 1+2):
+ *   - A named `vault:<name>:<verb>` → `vault.<name>` (RFC 8707-style resource
+ *     binding; vault enforces this strict-equality against the URL-derived
+ *     vault name).
+ *   - An unnamed `<service>:<verb>` → `<service>` (legacy shape; vault's
+ *     strict-check rejects unnamed `vault:*` audiences, so the consent
+ *     picker rewrites those before this is reached).
+ *   - Fallback: `hub` (no namespaced scope).
+ *
+ * Named vault scopes win over unnamed ones — an OAuth flow that mixes
+ * `vault:work:read` + `scribe:transcribe` audiences is grounded on the vault
+ * (the more sensitive resource), and tokens are issued per-flow anyway.
+ *
+ * Hoisted from `oauth-handlers.ts` so CLI mints and OAuth mints can't diverge
+ * on audience semantics — a divergence here means tokens minted via CLI fail
+ * audience strict-check at the resource server even though scopes match.
+ */
+
+export const VAULT_VERBS = new Set(["read", "write", "admin"]);
+
+export function inferAudience(scopes: readonly string[]): string {
+  for (const s of scopes) {
+    const parts = s.split(":");
+    const name = parts[1];
+    const verb = parts[2];
+    if (parts.length === 3 && parts[0] === "vault" && name && verb && VAULT_VERBS.has(verb)) {
+      return `vault.${name}`;
+    }
+  }
+  for (const s of scopes) {
+    const colon = s.indexOf(":");
+    if (colon > 0) return s.slice(0, colon);
+  }
+  return "hub";
+}

package/src/oauth-handlers.ts

@@ -43,6 +43,7 @@ import {
 } from "./clients.ts";
 import { CSRF_FIELD_NAME, ensureCsrfToken, verifyCsrfToken } from "./csrf.ts";
 import { isCoveredByGrant, recordGrant } from "./grants.ts";
+import { VAULT_VERBS, inferAudience } from "./jwt-audience.ts";
 import {
   ACCESS_TOKEN_TTL_SECONDS,
   RefreshTokenInsertError,
@@ -69,8 +70,6 @@ import {
 import { getUserByUsername, verifyPassword } from "./users.ts";
 import { isVaultEntry, shortName, vaultInstanceNameFor } from "./well-known.ts";
 
-const VAULT_VERBS = new Set(["read", "write", "admin"]);
-
 /** Verbs whose unnamed `vault:<verb>` form needs picker disambiguation. */
 function unnamedVaultVerbs(scopes: string[]): string[] {
   const verbs: string[] = [];
@@ -1056,36 +1055,6 @@ function mapAuthCodeError(err: unknown): Response {
   return jsonResponse({ error: "server_error", error_description: msg }, 500);
 }
 
-/**
- * Picks the JWT `aud` claim based on the requested scopes. Per the
- * vault-config-and-scopes design (Phase 1+2):
- *   - A named `vault:<name>:<verb>` → `vault.<name>` (RFC 8707-style resource
- *     binding; vault enforces this strict-equality against the URL-derived
- *     vault name).
- *   - An unnamed `<service>:<verb>` → `<service>` (legacy shape; vault's
- *     strict-check rejects unnamed `vault:*` audiences, so the consent
- *     picker rewrites those before this is reached).
- *
- * Named vault scopes win over unnamed ones — an OAuth flow that mixes
- * `vault:work:read` + `scribe:transcribe` audiences is grounded on the vault
- * (the more sensitive resource), and tokens are issued per-flow anyway.
- */
-function inferAudience(scopes: string[]): string {
-  for (const s of scopes) {
-    const parts = s.split(":");
-    const name = parts[1];
-    const verb = parts[2];
-    if (parts.length === 3 && parts[0] === "vault" && name && verb && VAULT_VERBS.has(verb)) {
-      return `vault.${name}`;
-    }
-  }
-  for (const s of scopes) {
-    const colon = s.indexOf(":");
-    if (colon > 0) return s.slice(0, colon);
-  }
-  return "hub";
-}
-
 // --- /oauth/register -------------------------------------------------------
 
 interface RegisterRequestBody {