@openparachute/hub 0.5.9-rc.6 → 0.5.10-rc.2

package/package.json

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

package/src/__tests__/hub-server.test.ts

@@ -9,6 +9,7 @@ import { findServiceUpstream, findVaultUpstream, hubFetch, layerOf } from "../hu
 import { pidPath } from "../process-state.ts";
 import { type ServiceEntry, writeManifest } from "../services-manifest.ts";
 import { rotateSigningKey } from "../signing-keys.ts";
+import { createUser } from "../users.ts";
 
 interface Harness {
   dir: string;
@@ -846,21 +847,31 @@ describe("hubFetch routing", () => {
     }
   });
 
-  test("/oauth/authorize without configured db returns 503", async () => {
+  test("/oauth/authorize without configured db returns 503 JSON", async () => {
     const h = makeHarness();
     try {
       const res = await hubFetch(h.dir)(req("/oauth/authorize?client_id=x"));
       expect(res.status).toBe(503);
+      const body = (await res.json()) as { error: string; error_description: string };
+      expect(body.error).toBe("service_unavailable");
+      expect(body.error_description).toBe("hub db not configured");
     } finally {
       h.cleanup();
     }
   });
 
-  test("every DB-dependent route returns 503 when getDb is absent (closes #139)", async () => {
+  test("every DB-dependent route returns 503 when getDb is absent (closes #139, JSON shape closes #227)", async () => {
     const h = makeHarness();
     try {
       const fetch = hubFetch(h.dir);
+      // Every DB-dependent guard returns the same JSON 503 shape
+      // (`service_unavailable`) so consumers don't branch on content-type to
+      // extract the message. The pattern was already canonical on
+      // /api/auth/* (hub#215, #226) and was extended to all guards in
+      // hub#227.
       const cases: Array<[string, RequestInit]> = [
+        ["/oauth/authorize?client_id=x", { method: "GET" }],
+        ["/oauth/authorize/approve", { method: "POST" }],
         ["/oauth/token", { method: "POST" }],
         ["/oauth/register", { method: "POST" }],
         ["/oauth/revoke", { method: "POST" }],
@@ -871,10 +882,23 @@ describe("hubFetch routing", () => {
         ["/login", { method: "POST" }],
         ["/logout", { method: "POST" }],
         ["/admin/host-admin-token", { method: "GET" }],
+        ["/admin/vault-admin-token/demo", { method: "GET" }],
+        ["/api/me", { method: "GET" }],
+        ["/api/auth/mint-token", { method: "POST" }],
+        ["/api/auth/revoke-token", { method: "POST" }],
+        ["/api/auth/tokens", { method: "GET" }],
+        ["/api/grants", { method: "GET" }],
+        ["/api/grants/client-x", { method: "DELETE" }],
+        ["/api/oauth/clients/client-x", { method: "GET" }],
+        ["/api/oauth/clients/client-x/approve", { method: "POST" }],
       ];
       for (const [path, init] of cases) {
         const res = await fetch(req(path, init));
         expect(res.status).toBe(503);
+        expect(res.headers.get("content-type")?.toLowerCase()).toContain("application/json");
+        const body = (await res.json()) as { error: string; error_description: string };
+        expect(body.error).toBe("service_unavailable");
+        expect(body.error_description).toBe("hub db not configured");
       }
     } finally {
       h.cleanup();
@@ -886,6 +910,11 @@ describe("hubFetch routing", () => {
     try {
       const db = openHubDb(hubDbPath(h.dir));
       try {
+        // Seed an admin so the pre-admin setup gate (hub#258) doesn't
+        // 503 the request before the OAuth method-allow check runs.
+        // OAuth routing semantics are what this test pins; the setup
+        // gate has its own coverage in src/__tests__/setup-gate.test.ts.
+        await createUser(db, "owner", "pw");
         const res = await hubFetch(h.dir, { getDb: () => db })(
           req("/oauth/token", { method: "GET" }),
         );
@@ -903,6 +932,7 @@ describe("hubFetch routing", () => {
     try {
       const db = openHubDb(hubDbPath(h.dir));
       try {
+        await createUser(db, "owner", "pw");
         const res = await hubFetch(h.dir, {
           getDb: () => db,
           issuer: "https://hub.example",
@@ -924,6 +954,162 @@ describe("hubFetch routing", () => {
     }
   });
 
+  // Platform health check (hub#258). Returns 200 JSON regardless of DB
+  // state — Render et al. poll this every few seconds and a transient DB
+  // open shouldn't cascade into a restart loop. The body advertises the
+  // running version so a deploy verifier can confirm the rolled-out
+  // image is the one it expected.
+  test("/health returns 200 JSON without invoking the db", async () => {
+    const h = makeHarness();
+    try {
+      const res = await hubFetch(h.dir, {
+        getDb: () => {
+          throw new Error("getDb must not be called by /health");
+        },
+      })(req("/health"));
+      expect(res.status).toBe(200);
+      expect(res.headers.get("content-type")).toContain("application/json");
+      expect(res.headers.get("cache-control")).toBe("no-store");
+      const body = (await res.json()) as Record<string, unknown>;
+      expect(body.status).toBe("ok");
+      expect(body.service).toBe("parachute-hub");
+      expect(typeof body.version).toBe("string");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  // First-boot setup placeholder (hub#258). When no admin exists the page
+  // is the bootstrap onboarding surface; once an admin exists it 301s to
+  // /login so a stale bookmark still lands somewhere useful.
+  test("/admin/setup renders placeholder HTML when no admin exists", async () => {
+    const h = makeHarness();
+    try {
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        const res = await hubFetch(h.dir, { getDb: () => db })(req("/admin/setup"));
+        expect(res.status).toBe(200);
+        expect(res.headers.get("content-type")).toContain("text/html");
+        const body = await res.text();
+        expect(body).toContain("first-boot setup");
+        expect(body).toContain("PARACHUTE_INITIAL_ADMIN_USERNAME");
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("/admin/setup 301s to /login when an admin already exists", async () => {
+    const h = makeHarness();
+    try {
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        await createUser(db, "owner", "pw");
+        const res = await hubFetch(h.dir, { getDb: () => db })(req("/admin/setup"));
+        expect(res.status).toBe(301);
+        expect(res.headers.get("location")).toBe("/login");
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  // Pre-admin lockout (hub#258). When no admin row exists, operator-
+  // facing surfaces (admin/api/login) 503 with a JSON body pointing at
+  // /admin/setup. Public surfaces (health, well-known, /, oauth, vault,
+  // /admin/setup itself) stay open so the container is reachable and
+  // OAuth third parties aren't held hostage by admin onboarding.
+  test("pre-admin lockout: /admin/vaults returns 503 setup_required", async () => {
+    const h = makeHarness();
+    try {
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        const res = await hubFetch(h.dir, { getDb: () => db })(req("/admin/vaults"));
+        expect(res.status).toBe(503);
+        const body = (await res.json()) as Record<string, unknown>;
+        expect(body.error).toBe("setup_required");
+        expect(body.setup_url).toBe("/admin/setup");
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("pre-admin lockout: /api/me returns 503 setup_required", async () => {
+    const h = makeHarness();
+    try {
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        const res = await hubFetch(h.dir, { getDb: () => db })(req("/api/me"));
+        expect(res.status).toBe(503);
+        const body = (await res.json()) as Record<string, unknown>;
+        expect(body.error).toBe("setup_required");
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("pre-admin lockout: /login is gated, /admin/setup + /health + well-known stay open", async () => {
+    const h = makeHarness();
+    try {
+      writeFileSync(join(h.dir, "hub.html"), "<html>discovery</html>");
+      writeManifest({ services: [] }, h.manifestPath);
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        const handler = hubFetch(h.dir, { getDb: () => db, manifestPath: h.manifestPath });
+        // /login gated
+        const loginRes = await handler(req("/login"));
+        expect(loginRes.status).toBe(503);
+        // /admin/setup open
+        const setupRes = await handler(req("/admin/setup"));
+        expect(setupRes.status).toBe(200);
+        // /health open
+        const healthRes = await handler(req("/health"));
+        expect(healthRes.status).toBe(200);
+        // / open
+        const rootRes = await handler(req("/"));
+        expect(rootRes.status).toBe(200);
+        // /.well-known/parachute.json open
+        const wkRes = await handler(req("/.well-known/parachute.json"));
+        expect(wkRes.status).toBe(200);
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("pre-admin lockout falls away once an admin exists", async () => {
+    const h = makeHarness();
+    try {
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        // Before: /api/me 503s under the lockout.
+        const before = await hubFetch(h.dir, { getDb: () => db })(req("/api/me"));
+        expect(before.status).toBe(503);
+        // After seeding an admin: dispatch resumes normal handling.
+        await createUser(db, "owner", "pw");
+        const after = await hubFetch(h.dir, { getDb: () => db })(req("/api/me"));
+        // /api/me with no session returns `hasSession: false` 200, not 503.
+        expect(after.status).toBe(200);
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
   test("live Bun.serve round-trip: / and /.well-known resolve", async () => {
     const h = makeHarness();
     try {

package/src/__tests__/oauth-handlers.test.ts

@@ -3205,6 +3205,115 @@ describe("refresh-token rotation + /oauth/revoke (#73)", () => {
 // to the auth-code redirect. Strict superset (incremental scope) and
 // revoked grants still show consent.
 describe("handleAuthorizeGet — skip consent when scope already granted (#75)", () => {
+  // hub#236 — pin the full silent-approve flow end-to-end in one test.
+  // The per-branch tests below this one cover individual branches (subset,
+  // superset, revoke, unnamed-vault, re-registered-client); this test
+  // walks the operator-visible state machine in a single body so a
+  // regression at any step surfaces immediately, and the JSDoc on
+  // handleAuthorizeGet's silent-approve flow (1-5) has a single load-
+  // bearing test to point at.
+  test("first-use consent → silent-approve → novel-scope re-prompts (full silent-approve flow, #236)", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const user = await createUser(db, "owner", "pw");
+      const session = createSession(db, { userId: user.id });
+      const reg = registerClient(db, { redirectUris: ["https://app.example/cb"] });
+      const { challenge } = makePkce();
+      const sessionCookie = buildSessionCookie(session.id, 86400);
+
+      // Step 1: first use — no grant exists; consent screen renders.
+      const firstReq = new Request(
+        authorizeUrl({
+          client_id: reg.client.clientId,
+          redirect_uri: "https://app.example/cb",
+          response_type: "code",
+          scope: "vault:default:read",
+          code_challenge: challenge,
+          code_challenge_method: "S256",
+          state: "step1",
+        }),
+        { headers: { cookie: sessionCookie } },
+      );
+      const firstRes = handleAuthorizeGet(db, firstReq, { issuer: ISSUER });
+      expect(firstRes.status).toBe(200);
+      expect(firstRes.headers.get("content-type")).toContain("text/html");
+
+      // Step 1b: user approves via the consent form — grant gets recorded.
+      const consentRes = await handleAuthorizePost(
+        db,
+        new Request(`${ISSUER}/oauth/authorize`, {
+          method: "POST",
+          body: new URLSearchParams({
+            __action: "consent",
+            __csrf: TEST_CSRF,
+            approve: "yes",
+            client_id: reg.client.clientId,
+            redirect_uri: "https://app.example/cb",
+            response_type: "code",
+            scope: "vault:default:read",
+            code_challenge: challenge,
+            code_challenge_method: "S256",
+          }),
+          headers: {
+            "content-type": "application/x-www-form-urlencoded",
+            cookie: `${CSRF_COOKIE}; ${sessionCookie}`,
+          },
+        }),
+        { issuer: ISSUER },
+      );
+      expect(consentRes.status).toBe(302);
+
+      // Step 2: subsequent use, same scopes — silent-approve fires.
+      // Authoritative assertion: 302 redirect with auth code, NOT a 200
+      // HTML consent screen. This is the operator-visible payoff.
+      const secondReq = new Request(
+        authorizeUrl({
+          client_id: reg.client.clientId,
+          redirect_uri: "https://app.example/cb",
+          response_type: "code",
+          scope: "vault:default:read",
+          code_challenge: challenge,
+          code_challenge_method: "S256",
+          state: "step2",
+        }),
+        { headers: { cookie: sessionCookie } },
+      );
+      const secondRes = handleAuthorizeGet(db, secondReq, { issuer: ISSUER });
+      expect(secondRes.status).toBe(302);
+      const secondLoc = new URL(secondRes.headers.get("location") ?? "");
+      expect(secondLoc.origin + secondLoc.pathname).toBe("https://app.example/cb");
+      expect(secondLoc.searchParams.get("code")?.length).toBeGreaterThan(20);
+      expect(secondLoc.searchParams.get("state")).toBe("step2");
+
+      // Step 3: subsequent use, novel scope NOT in the grant — gate must
+      // NOT fire; consent re-renders with the new scope explicit. This is
+      // the load-bearing security property: silent-approve must not
+      // silently approve scopes the user never consented to.
+      const novelReq = new Request(
+        authorizeUrl({
+          client_id: reg.client.clientId,
+          redirect_uri: "https://app.example/cb",
+          response_type: "code",
+          // Adds scribe:transcribe to the original vault:default:read.
+          scope: "vault:default:read scribe:transcribe",
+          code_challenge: challenge,
+          code_challenge_method: "S256",
+          state: "step3",
+        }),
+        { headers: { cookie: sessionCookie } },
+      );
+      const novelRes = handleAuthorizeGet(db, novelReq, { issuer: ISSUER });
+      expect(novelRes.status).toBe(200);
+      expect(novelRes.headers.get("content-type")).toContain("text/html");
+      const novelBody = await novelRes.text();
+      // The new scope appears on the consent page — the user must approve
+      // it explicitly.
+      expect(novelBody).toContain("scribe:transcribe");
+    } finally {
+      cleanup();
+    }
+  });
+
   test("first approval records grant; second flow with same scopes skips consent", async () => {
     const { db, cleanup } = await makeDb();
     try {

package/src/__tests__/operator-token.test.ts

@@ -297,7 +297,7 @@ describe("useOperatorTokenWithAutoRotate (#213)", () => {
           issuer: TEST_ISSUER,
         });
         expect(used).not.toBeNull();
-        expect(used?.refreshed).toBe(false);
+        expect(used?.status.kind).toBe("fresh");
         expect(used?.rotated).toBeUndefined();
         expect(used?.token).toBe(issued.token);
       } finally {
@@ -328,7 +328,7 @@ describe("useOperatorTokenWithAutoRotate (#213)", () => {
           issuer: TEST_ISSUER,
         });
         expect(used).not.toBeNull();
-        expect(used?.refreshed).toBe(true);
+        expect(used?.status.kind).toBe("rotated");
         expect(used?.rotated?.scopeSet).toBe("start");
         // The on-disk token is now the rotated one.
         const onDisk = await readOperatorTokenFile(h.dir);
@@ -370,7 +370,10 @@ describe("useOperatorTokenWithAutoRotate (#213)", () => {
           issuer: TEST_ISSUER,
         });
         expect(used).not.toBeNull();
-        expect(used?.refreshed).toBe(false);
+        expect(used?.status.kind).toBe("skipped");
+        if (used?.status.kind === "skipped") {
+          expect(used.status.reason).toBe("aud-mismatch");
+        }
         expect(used?.rotated).toBeUndefined();
         expect(used?.token).toBe(signed.token);
         // On-disk file unchanged.
@@ -384,6 +387,51 @@ describe("useOperatorTokenWithAutoRotate (#213)", () => {
     }
   });
 
+  // hub#224 — when a JWT carries the operator audience + short TTL but
+  // lacks a recognized `pa_scope_set` claim, the helper now refuses to
+  // auto-rotate. Pre-hardening the fallback widened to admin; the test
+  // pins the new "skipped, no-scope-set" outcome.
+  test("does NOT auto-rotate an aud=operator token that lacks pa_scope_set (no silent widening)", async () => {
+    const h = makeHarness();
+    try {
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        rotateSigningKey(db);
+        // aud=operator + 1h TTL + NO pa_scope_set claim. Pre-#224 this would
+        // fall back to OPERATOR_TOKEN_DEFAULT_SCOPE_SET (admin) on rotation
+        // — a silent widening of a token of unknown provenance.
+        const signed = await signAccessToken(db, {
+          sub: "user-abc",
+          scopes: ["scribe:transcribe"],
+          audience: OPERATOR_TOKEN_AUDIENCE,
+          clientId: OPERATOR_TOKEN_CLIENT_ID,
+          issuer: TEST_ISSUER,
+          ttlSeconds: 3600,
+        });
+        await writeOperatorTokenFile(signed.token, h.dir);
+
+        const used = await useOperatorTokenWithAutoRotate(db, {
+          configDir: h.dir,
+          issuer: TEST_ISSUER,
+        });
+        expect(used).not.toBeNull();
+        expect(used?.status.kind).toBe("skipped");
+        if (used?.status.kind === "skipped") {
+          expect(used.status.reason).toBe("no-scope-set");
+        }
+        expect(used?.rotated).toBeUndefined();
+        expect(used?.token).toBe(signed.token);
+        // On-disk file unchanged — no widening occurred.
+        const onDisk = await readOperatorTokenFile(h.dir);
+        expect(onDisk).toBe(signed.token);
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
   test("returns null when no operator token file exists", async () => {
     const h = makeHarness();
     try {
@@ -488,7 +536,7 @@ describe("mintOperatorToken registry write (#212)", () => {
           configDir: h.dir,
           issuer: TEST_ISSUER,
         });
-        expect(used?.refreshed).toBe(true);
+        expect(used?.status.kind).toBe("rotated");
         // The rotated token has a new jti.
         const newJti = used!.payload.jti as string;
         expect(newJti).not.toBe(original.jti);

package/src/__tests__/serve.test.ts

@@ -0,0 +1,100 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { seedInitialAdminIfNeeded } from "../commands/serve.ts";
+import { openHubDb } from "../hub-db.ts";
+import { userCount } from "../users.ts";
+
+describe("seedInitialAdminIfNeeded", () => {
+  let dir: string;
+  let dbPath: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "parachute-serve-"));
+    dbPath = join(dir, "hub.db");
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("returns 'needs-setup' on fresh state with no env vars", async () => {
+    const db = openHubDb(dbPath);
+    const result = await seedInitialAdminIfNeeded(db, {}, () => {});
+    expect(result).toBe("needs-setup");
+    expect(userCount(db)).toBe(0);
+  });
+
+  test("seeds an admin from PARACHUTE_INITIAL_ADMIN_* on fresh state", async () => {
+    const db = openHubDb(dbPath);
+    const log = mock<(line: string) => void>(() => {});
+    const result = await seedInitialAdminIfNeeded(
+      db,
+      {
+        PARACHUTE_INITIAL_ADMIN_USERNAME: "ops",
+        PARACHUTE_INITIAL_ADMIN_PASSWORD: "correct horse battery staple",
+      },
+      log,
+    );
+    expect(result).toBe("seeded");
+    expect(userCount(db)).toBe(1);
+    // The log line carries the username so operators can grep container
+    // logs to verify the seed fired.
+    expect(log).toHaveBeenCalledTimes(1);
+    expect(log.mock.calls[0]?.[0] ?? "").toContain("seeded initial admin");
+    expect(log.mock.calls[0]?.[0] ?? "").toContain("ops");
+  });
+
+  test("returns 'exists' when an admin already exists, even with env vars set", async () => {
+    // Seed once.
+    const db = openHubDb(dbPath);
+    await seedInitialAdminIfNeeded(
+      db,
+      {
+        PARACHUTE_INITIAL_ADMIN_USERNAME: "ops",
+        PARACHUTE_INITIAL_ADMIN_PASSWORD: "first-pw",
+      },
+      () => {},
+    );
+
+    // Same env on a second boot must NOT clobber the existing admin —
+    // the seed is first-boot only. (Container restart with the env still
+    // set from the Render dashboard is the canonical second-boot.)
+    const result = await seedInitialAdminIfNeeded(
+      db,
+      {
+        PARACHUTE_INITIAL_ADMIN_USERNAME: "ops",
+        PARACHUTE_INITIAL_ADMIN_PASSWORD: "different-pw",
+      },
+      () => {},
+    );
+    expect(result).toBe("exists");
+    expect(userCount(db)).toBe(1);
+  });
+
+  test("treats whitespace-only username as missing (needs-setup)", async () => {
+    const db = openHubDb(dbPath);
+    const result = await seedInitialAdminIfNeeded(
+      db,
+      {
+        PARACHUTE_INITIAL_ADMIN_USERNAME: "   ",
+        PARACHUTE_INITIAL_ADMIN_PASSWORD: "pw",
+      },
+      () => {},
+    );
+    expect(result).toBe("needs-setup");
+    expect(userCount(db)).toBe(0);
+  });
+
+  test("requires both username and password — half-set env is needs-setup", async () => {
+    const db = openHubDb(dbPath);
+    const result = await seedInitialAdminIfNeeded(
+      db,
+      { PARACHUTE_INITIAL_ADMIN_USERNAME: "ops" },
+      () => {},
+    );
+    expect(result).toBe("needs-setup");
+    expect(userCount(db)).toBe(0);
+  });
+});