@openparachute/hub 0.3.0-rc.1 → 0.5.0

package/src/__tests__/well-known.test.ts

@@ -92,7 +92,7 @@ describe("vaultInstanceName", () => {
 });
 
 describe("buildWellKnown", () => {
-  test("vaults is always an array, other services are flat entries, services[] includes all", () => {
+  test("every kind is a plural array; services[] includes all (#92)", () => {
     const doc = buildWellKnown({
       services: [vault, notes, scribe],
       canonicalOrigin: "https://parachute.taildf9ce2.ts.net",
@@ -104,14 +104,18 @@ describe("buildWellKnown", () => {
         version: "0.2.4",
       },
     ]);
-    expect(doc.notes).toEqual({
-      url: "https://parachute.taildf9ce2.ts.net/notes",
-      version: "0.0.1",
-    });
-    expect(doc.scribe).toEqual({
-      url: "https://parachute.taildf9ce2.ts.net/scribe",
-      version: "0.1.0",
-    });
+    expect(doc.notes).toEqual([
+      {
+        url: "https://parachute.taildf9ce2.ts.net/notes",
+        version: "0.0.1",
+      },
+    ]);
+    expect(doc.scribe).toEqual([
+      {
+        url: "https://parachute.taildf9ce2.ts.net/scribe",
+        version: "0.1.0",
+      },
+    ]);
     expect(doc.services.map((s) => s.name)).toEqual([
       "parachute-vault",
       "parachute-notes",
@@ -119,6 +123,18 @@ describe("buildWellKnown", () => {
     ]);
   });
 
+  test("multiple installs of the same kind both land in the array (#92)", () => {
+    const work: ServiceEntry = { ...notes, paths: ["/notes-work"], port: 5174 };
+    const doc = buildWellKnown({
+      services: [notes, work],
+      canonicalOrigin: "https://x.example",
+    });
+    expect(doc.notes).toEqual([
+      { url: "https://x.example/notes", version: "0.0.1" },
+      { url: "https://x.example/notes-work", version: "0.0.1" },
+    ]);
+  });
+
   test("services[] entries include infoUrl pointing at /.parachute/info", () => {
     const doc = buildWellKnown({
       services: [vault, notes],
@@ -158,7 +174,7 @@ describe("buildWellKnown", () => {
     });
     expect(doc.vaults).toEqual([]);
     expect(doc.services).toHaveLength(1);
-    expect(doc.notes).toEqual({ url: "https://x.example/notes", version: "0.0.1" });
+    expect(doc.notes).toEqual([{ url: "https://x.example/notes", version: "0.0.1" }]);
   });
 
   test("multiple vault instances all land in the vaults array", () => {
@@ -177,6 +193,63 @@ describe("buildWellKnown", () => {
     expect(doc.vaults.map((v) => v.name).sort()).toEqual(["default", "work"]);
   });
 
+  test("single vault ServiceEntry with multiple paths emits one entry per path (closes #141)", () => {
+    // Reflects the post-#179/vault#208 manifest shape: one parachute-vault
+    // backend hosts every vault instance, expressed as one ServiceEntry with
+    // multiple paths.
+    const multi: ServiceEntry = {
+      ...vault,
+      paths: ["/vault/default", "/vault/techne"],
+    };
+    const doc = buildWellKnown({
+      services: [multi],
+      canonicalOrigin: "https://x.example",
+    });
+    expect(doc.vaults).toEqual([
+      { name: "default", url: "https://x.example/vault/default", version: "0.2.4" },
+      { name: "techne", url: "https://x.example/vault/techne", version: "0.2.4" },
+    ]);
+    // services[] mirrors the per-path expansion so the hub page and any
+    // generic consumer iterate every instance.
+    expect(doc.services).toEqual([
+      {
+        name: "parachute-vault",
+        url: "https://x.example/vault/default",
+        path: "/vault/default",
+        version: "0.2.4",
+        infoUrl: "https://x.example/vault/default/.parachute/info",
+      },
+      {
+        name: "parachute-vault",
+        url: "https://x.example/vault/techne",
+        path: "/vault/techne",
+        version: "0.2.4",
+        infoUrl: "https://x.example/vault/techne/.parachute/info",
+      },
+    ]);
+  });
+
+  test("multi-path vault entry is independent of multi-ServiceEntry shape (#141)", () => {
+    // A user could plausibly mix shapes: one multi-path bare `parachute-vault`
+    // plus a separately-installed `parachute-vault-archive`. All instances
+    // should surface.
+    const multi: ServiceEntry = {
+      ...vault,
+      paths: ["/vault/default", "/vault/techne"],
+    };
+    const archive: ServiceEntry = {
+      ...vault,
+      name: "parachute-vault-archive",
+      paths: ["/vault/archive"],
+      port: 1942,
+    };
+    const doc = buildWellKnown({
+      services: [multi, archive],
+      canonicalOrigin: "https://x.example",
+    });
+    expect(doc.vaults.map((v) => v.name).sort()).toEqual(["archive", "default", "techne"]);
+  });
+
   test("handles canonicalOrigin with trailing slash", () => {
     const doc = buildWellKnown({
       services: [vault],
@@ -185,6 +258,50 @@ describe("buildWellKnown", () => {
     expect(doc.vaults[0]?.url).toBe("https://parachute.taildf9ce2.ts.net/vault/default");
   });
 
+  test("managementUrl rides through when the resolver returns one", () => {
+    const doc = buildWellKnown({
+      services: [vault],
+      canonicalOrigin: "https://x.example",
+      managementUrlFor: () => "/admin",
+    });
+    expect(doc.vaults[0]?.managementUrl).toBe("/admin");
+  });
+
+  test("managementUrl absent when the resolver returns undefined", () => {
+    const doc = buildWellKnown({
+      services: [vault],
+      canonicalOrigin: "https://x.example",
+      managementUrlFor: () => undefined,
+    });
+    expect(doc.vaults[0]).not.toHaveProperty("managementUrl");
+  });
+
+  test("managementUrl is per-entry — multi-instance vaults can differ", () => {
+    const work: ServiceEntry = {
+      ...vault,
+      name: "parachute-vault-work",
+      paths: ["/vault/work"],
+      port: 1941,
+    };
+    const doc = buildWellKnown({
+      services: [vault, work],
+      canonicalOrigin: "https://x.example",
+      managementUrlFor: (e) => (e.name === "parachute-vault-work" ? "/admin" : undefined),
+    });
+    const byName = new Map(doc.vaults.map((v) => [v.name, v.managementUrl]));
+    expect(byName.get("default")).toBeUndefined();
+    expect(byName.get("work")).toBe("/admin");
+  });
+
+  test("managementUrl is not emitted on non-vault services", () => {
+    const doc = buildWellKnown({
+      services: [notes],
+      canonicalOrigin: "https://x.example",
+      managementUrlFor: () => "/admin",
+    });
+    expect(doc.notes).toEqual([{ url: "https://x.example/notes", version: "0.0.1" }]);
+  });
+
   test("falls back to / for empty paths", () => {
     const entry: ServiceEntry = { ...vault, paths: [] };
     const doc = buildWellKnown({

package/src/admin-auth.ts

@@ -0,0 +1,126 @@
+/**
+ * Bearer-token auth for hub-native admin endpoints (POST /vaults, future
+ * `/admin/*` routes). The hub validates its own JWTs against local signing
+ * keys — no JWKS round-trip — and asserts the presented token carries the
+ * required scope.
+ *
+ * Why this exists: until now the hub has been a *pure issuer* with no
+ * authenticated endpoints of its own. Phase 1 of the vault-config-and-scopes
+ * design adds POST /vaults, which mints+config-writes through privileged
+ * code paths. That call needs an admin scope, and its first reader is
+ * `parachute:host:admin` (the cross-vault provisioning capability).
+ *
+ * Errors are HTTP-shaped: `AdminAuthError(status, message)` so the route
+ * handler can `throw` and the boundary translates straight to a Response.
+ */
+import type { Database } from "bun:sqlite";
+import { validateAccessToken } from "./jwt-sign.ts";
+
+export interface AdminAuthContext {
+  /** JWT `sub` — the hub user id. */
+  sub: string;
+  /** Parsed `scope` claim. */
+  scopes: string[];
+  /** `client_id` claim, if present (operator token vs OAuth client). */
+  clientId: string | undefined;
+  /** `aud` claim, if present. Surfaced for logs / future cross-aud rules. */
+  audience: string | undefined;
+}
+
+export class AdminAuthError extends Error {
+  override name = "AdminAuthError";
+  status: number;
+  constructor(status: number, message: string) {
+    super(message);
+    this.status = status;
+  }
+}
+
+/**
+ * Pull a Bearer token from `Authorization: Bearer <token>`. Throws
+ * `AdminAuthError(401)` when missing / malformed. Match is case-insensitive
+ * on the scheme (some clients send "bearer" lowercase) but the token itself
+ * is the raw JWT string.
+ */
+export function extractBearerToken(req: Request): string {
+  const header = req.headers.get("authorization");
+  if (!header) {
+    throw new AdminAuthError(401, "missing Authorization header");
+  }
+  const match = header.match(/^Bearer\s+(.+)$/i);
+  if (!match || !match[1]) {
+    throw new AdminAuthError(401, "Authorization header must be 'Bearer <token>'");
+  }
+  return match[1].trim();
+}
+
+/**
+ * Validate a presented bearer token against the hub's local signing keys
+ * and check it carries `requiredScope`. Returns surfaced claims on success;
+ * throws `AdminAuthError` (401 or 403) otherwise.
+ *
+ * `expectedIssuer` MUST be the hub's own origin — the same value baked into
+ * tokens we sign. Defense in depth: even though we can only verify our own
+ * keys, the `iss` mismatch reject keeps cross-issuer confusion impossible.
+ */
+export async function requireScope(
+  db: Database,
+  req: Request,
+  requiredScope: string,
+  expectedIssuer: string,
+): Promise<AdminAuthContext> {
+  const token = extractBearerToken(req);
+
+  let validated: Awaited<ReturnType<typeof validateAccessToken>>;
+  try {
+    validated = await validateAccessToken(db, token, expectedIssuer);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new AdminAuthError(401, `invalid token: ${msg}`);
+  }
+
+  const sub = typeof validated.payload.sub === "string" ? validated.payload.sub : null;
+  if (!sub) throw new AdminAuthError(401, "token missing required `sub` claim");
+
+  const scopeClaim = (validated.payload as { scope?: unknown }).scope;
+  const scopes =
+    typeof scopeClaim === "string" ? scopeClaim.split(/\s+/).filter((s) => s.length > 0) : [];
+
+  if (!scopes.includes(requiredScope)) {
+    throw new AdminAuthError(403, `token missing required scope: ${requiredScope}`);
+  }
+
+  const clientIdRaw = (validated.payload as { client_id?: unknown }).client_id;
+  const clientId = typeof clientIdRaw === "string" ? clientIdRaw : undefined;
+  const aud = typeof validated.payload.aud === "string" ? validated.payload.aud : undefined;
+
+  return { sub, scopes, clientId, audience: aud };
+}
+
+/**
+ * Translate an AdminAuthError to an RFC-6750-style JSON Response.
+ * Convenience for route handlers that want to do
+ * `try { ctx = await requireScope(...) } catch (err) { return adminAuthErrorResponse(err); }`.
+ */
+export function adminAuthErrorResponse(err: unknown): Response {
+  if (err instanceof AdminAuthError) {
+    return new Response(
+      JSON.stringify({
+        error: err.status === 403 ? "insufficient_scope" : "invalid_token",
+        error_description: err.message,
+      }),
+      {
+        status: err.status,
+        headers: {
+          "content-type": "application/json",
+          "www-authenticate": `Bearer error="${err.status === 403 ? "insufficient_scope" : "invalid_token"}", error_description="${err.message.replace(/"/g, "'")}"`,
+        },
+      },
+    );
+  }
+  const msg = err instanceof Error ? err.message : String(err);
+  return new Response(JSON.stringify({ error: "server_error", error_description: msg }), {
+    status: 500,
+    headers: { "content-type": "application/json" },
+  });
+}