@openparachute/hub 0.5.0 → 0.5.2

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/__tests__/module-manifest.test.ts

@@ -130,6 +130,19 @@ describe("validateModuleManifest", () => {
     const m = validateModuleManifest(VALID, "x");
     expect(m.managementUrl).toBeUndefined();
   });
+
+  test("stripPrefix accepts boolean true and false; rejects non-boolean", () => {
+    expect(validateModuleManifest({ ...VALID, stripPrefix: true }, "x").stripPrefix).toBe(true);
+    expect(validateModuleManifest({ ...VALID, stripPrefix: false }, "x").stripPrefix).toBe(false);
+    expect(() => validateModuleManifest({ ...VALID, stripPrefix: "yes" }, "x")).toThrow(
+      /stripPrefix/,
+    );
+  });
+
+  test("stripPrefix absent stays absent", () => {
+    const m = validateModuleManifest(VALID, "x");
+    expect(m.stripPrefix).toBeUndefined();
+  });
 });
 
 describe("readModuleManifest", () => {

package/src/__tests__/services-manifest.test.ts

@@ -196,6 +196,32 @@ describe("services-manifest", () => {
       cleanup();
     }
   });
+
+  test("round-trips optional stripPrefix (true and false)", () => {
+    const { path, cleanup } = makeTempPath();
+    try {
+      const stripping: ServiceEntry = { ...vault, stripPrefix: true };
+      upsertService(stripping, path);
+      expect(readManifest(path).services[0]).toEqual(stripping);
+
+      const explicitFalse: ServiceEntry = { ...vault, stripPrefix: false };
+      upsertService(explicitFalse, path);
+      expect(readManifest(path).services[0]).toEqual(explicitFalse);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("rejects non-boolean stripPrefix", () => {
+    const { path, cleanup } = makeTempPath();
+    try {
+      expect(() =>
+        upsertService({ ...vault, stripPrefix: "yes" as unknown as boolean }, path),
+      ).toThrow(/stripPrefix/);
+    } finally {
+      cleanup();
+    }
+  });
 });
 
 describe("claw → agent migration", () => {

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