@openparachute/hub 0.3.0-rc.1 → 0.5.1

package/README.md

@@ -36,12 +36,13 @@ parachute status
 #    OpenCode, Cursor, Zed, Cline, your own agent) at:
 #      http://127.0.0.1:1940/vault/default/mcp
 
-# 6. Expose beyond localhost — Tailscale Funnel or Cloudflare Tunnel.
-#    Polishing for broad launch, but live today for early testers:
-parachute expose --help
+# 6. Expose across your tailnet — HTTPS, MagicDNS, only your devices.
+#    The supported exposure shape today; public-internet exposure is
+#    exploratory (see "Public exposure" below).
+parachute expose tailnet
 ```
 
-Tear down with `parachute expose tailnet off` or `parachute expose public off`. Layers are independent — `off` only affects the layer you name.
+Tear down with `parachute expose tailnet off`. The public layer (`expose public off`) tears down independently — `off` only affects the layer you name.
 
 ## Service lifecycle
 
@@ -87,13 +88,18 @@ parachute migrate --yes           # unattended
 
 Anything swept goes to `~/.parachute/.archive-<YYYY-MM-DD>/` with its original name — nothing is deleted. Recognized entries (per-service dirs, `services.json`, `expose-state.json`, `well-known/`) are left in place, and so is anything starting with a dot (so `.env` and prior `.archive-*` dirs are safe).
 
-## Three layers of addressability
+## Two supported layers (plus an exploratory third)
 
 Each additive; each can be turned off without affecting the layer below.
 
 - **Local** — services on loopback. Zero config. Browsers treat `localhost` as a secure context, so OAuth, PKCE, and Web Crypto all just work out of the box.
-- **Tailnet** — `parachute expose tailnet` wraps `tailscale serve` for every registered service. HTTPS via Tailscale's MagicDNS cert. Only machines on your tailnet can reach the URL.
-- **Public** — `parachute expose public` routes each handler through `tailscale funnel` so the same URLs become reachable from the public internet. At launch, Funnel is the only supported backend; Caddy + your-own-domain and cloudflared tunnels are planned post-launch.
+- **Tailnet** — `parachute expose tailnet` wraps `tailscale serve` for every registered service. HTTPS via Tailscale's MagicDNS cert. Only machines on your tailnet can reach the URL. **This is the documented shape for the hub today.** Tailnet is already authenticated at the network layer, every user's tailnet is their own, and the OAuth + module access work happening in the hub is being designed against this shape first.
+
+### Public exposure (exploratory)
+
+`parachute expose public` exists for early testers. It routes each handler through `tailscale funnel` (or, with `--cloudflare`, a named Cloudflare tunnel) so the same URLs become reachable from the public internet. The code path is live and the flag still works, but the public-internet posture (DNS, cross-internet OAuth, Funnel quirks) hasn't been hardened the way tailnet has — expect rough edges.
+
+When the hub's OAuth issuer + per-module scope enforcement land, public will re-enter the documented narrative as "now safe." Until then, prefer tailnet.
 
 Under the hood, tailnet mode uses `tailscale serve` and public mode uses `tailscale funnel`; both write into the same node-level serve config. The CLI records which layer is live so that `expose <other-layer> off` is a no-op rather than a surprise teardown of the active layer.
 
@@ -142,11 +148,9 @@ The `/.well-known/parachute.json` document is an always-present descriptor — f
 
 Why path-routing and not subdomain-per-service? Two reasons:
 
-1. **Tailscale Funnel HTTPS is capped at three ports per node** (443, 8443, 10000). Pinning every service to 443 behind a path means you can install any number of services without ever hitting that cap.
+1. **Tailscale Funnel HTTPS is capped at three ports per node** (443, 8443, 10000). Pinning every service to 443 behind a path means you can install any number of services without ever hitting that cap. (Funnel is the public-exposure backend; the cap shapes the tailnet-mode design too, since both modes share one serve config.)
 2. **Subdomain-per-service requires the Tailscale Services feature** (virtual-IP advertisement per service), which is more than a MagicDNS wildcard — it needs admin-side setup that's out of scope for a one-command install. When it's a launch-grade path, we'll add `parachute expose tailnet --mode subdomain`.
 
-Funnel has bandwidth quotas on Tailscale's free tier. See [tailscale.com/kb/1223/funnel](https://tailscale.com/kb/1223/funnel) for current limits; for heavy traffic, the post-launch Caddy / cloudflared modes will be the answer.
-
 ## Ports
 
 Parachute services reserve a block of loopback ports in the canonical range **1939–1949**. One range, one firewall rule, no surprises.
@@ -250,14 +254,12 @@ parachute expose tailnet
 # Also confirm the discovery document:
 curl -s https://parachute.<tailnet>.ts.net/.well-known/parachute.json | jq .
 
-# Flip to public (Funnel)
-parachute expose public
-# Open the same URL in a browser NOT on your tailnet — phone on cell, say.
-
 # Tear down
-parachute expose public off
+parachute expose tailnet off
 ```
 
+Public-internet exposure (`parachute expose public`) is exploratory — see "Public exposure" above. The flag still works for early testers; the supported smoke is tailnet.
+
 ## Subcommand reference
 
 Run `parachute --help` for the top-level list, and `parachute <subcommand> --help` for details on any individual command.
@@ -269,8 +271,8 @@ parachute start   [service]       start services in the background
 parachute stop    [service]       stop services (SIGTERM → 10s → SIGKILL)
 parachute restart [service]       stop + start
 parachute logs <service> [-f]     print/tail service logs
-parachute expose tailnet [off]    HTTPS across your tailnet
-parachute expose public  [off]    HTTPS on the public internet (Funnel)
+parachute expose tailnet [off]    HTTPS across your tailnet (supported)
+parachute expose public  [off]    HTTPS on the public internet (exploratory)
 parachute migrate [--dry-run]     archive legacy files at ecosystem root
 parachute vault <args...>         dispatch to parachute-vault
 ```

package/package.json

@@ -1,25 +1,32 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.3.0-rc.1",
+  "version": "0.5.1",
   "description": "parachute — the local hub for the Parachute ecosystem (discovery, ports, lifecycle, soon OAuth).",
   "license": "AGPL-3.0",
+  "publishConfig": {
+    "access": "public"
+  },
   "type": "module",
   "module": "src/cli.ts",
   "bin": {
     "parachute": "src/cli.ts"
   },
-  "files": ["src", "README.md", "LICENSE"],
+  "workspaces": ["packages/*"],
+  "files": ["src", "web/ui/dist", "README.md", "LICENSE"],
   "repository": {
     "type": "git",
     "url": "https://github.com/ParachuteComputer/parachute-hub.git"
   },
   "scripts": {
     "start": "bun src/cli.ts",
-    "test": "bun test",
+    "test": "bun test ./src",
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
     "format": "biome format --write .",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "build:spa": "cd web/ui && bun install --frozen-lockfile && bun run build",
+    "postinstall": "if [ -d web/ui ]; then bun run build:spa; fi",
+    "prepack": "bun run build:spa"
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.4",
@@ -27,5 +34,9 @@
   },
   "peerDependencies": {
     "typescript": "^5"
+  },
+  "dependencies": {
+    "@node-rs/argon2": "^2.0.2",
+    "jose": "^6.2.2"
   }
 }

package/src/__tests__/admin-auth.test.ts

@@ -0,0 +1,197 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  AdminAuthError,
+  adminAuthErrorResponse,
+  extractBearerToken,
+  requireScope,
+} from "../admin-auth.ts";
+import { hubDbPath, openHubDb } from "../hub-db.ts";
+import { signAccessToken } from "../jwt-sign.ts";
+import { rotateSigningKey } from "../signing-keys.ts";
+
+const ISSUER = "http://127.0.0.1:1939";
+
+interface Harness {
+  dir: string;
+  cleanup: () => void;
+}
+
+function makeHarness(): Harness {
+  const dir = mkdtempSync(join(tmpdir(), "phub-admin-auth-"));
+  return { dir, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+}
+
+async function mintToken(
+  db: ReturnType<typeof openHubDb>,
+  scopes: string[],
+  opts: { audience?: string; issuer?: string } = {},
+): Promise<string> {
+  const { token } = await signAccessToken(db, {
+    sub: "user-test",
+    scopes,
+    audience: opts.audience ?? "operator",
+    clientId: "test-client",
+    issuer: opts.issuer ?? ISSUER,
+  });
+  return token;
+}
+
+function reqWithAuth(authHeader: string | null): Request {
+  const headers = new Headers();
+  if (authHeader !== null) headers.set("authorization", authHeader);
+  return new Request("http://127.0.0.1:1939/test", { method: "POST", headers });
+}
+
+describe("extractBearerToken", () => {
+  test("returns the token from a well-formed header", () => {
+    const r = reqWithAuth("Bearer abc.def.ghi");
+    expect(extractBearerToken(r)).toBe("abc.def.ghi");
+  });
+
+  test("accepts lowercase scheme", () => {
+    const r = reqWithAuth("bearer abc.def.ghi");
+    expect(extractBearerToken(r)).toBe("abc.def.ghi");
+  });
+
+  test("throws 401 when header missing", () => {
+    const r = reqWithAuth(null);
+    expect(() => extractBearerToken(r)).toThrow(AdminAuthError);
+    try {
+      extractBearerToken(r);
+    } catch (err) {
+      expect((err as AdminAuthError).status).toBe(401);
+    }
+  });
+
+  test("throws 401 when scheme is not Bearer", () => {
+    const r = reqWithAuth("Basic dXNlcjpwYXNz");
+    expect(() => extractBearerToken(r)).toThrow(AdminAuthError);
+  });
+});
+
+describe("requireScope", () => {
+  test("returns context for a token with the required scope", async () => {
+    const h = makeHarness();
+    try {
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        rotateSigningKey(db);
+        const token = await mintToken(db, ["parachute:host:admin", "vault:admin"]);
+        const ctx = await requireScope(
+          db,
+          reqWithAuth(`Bearer ${token}`),
+          "parachute:host:admin",
+          ISSUER,
+        );
+        expect(ctx.sub).toBe("user-test");
+        expect(ctx.scopes).toContain("parachute:host:admin");
+        expect(ctx.clientId).toBe("test-client");
+        expect(ctx.audience).toBe("operator");
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("rejects 403 when token lacks the required scope", async () => {
+    const h = makeHarness();
+    try {
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        rotateSigningKey(db);
+        const token = await mintToken(db, ["vault:read"]);
+        let caught: AdminAuthError | null = null;
+        try {
+          await requireScope(db, reqWithAuth(`Bearer ${token}`), "parachute:host:admin", ISSUER);
+        } catch (err) {
+          caught = err as AdminAuthError;
+        }
+        expect(caught).not.toBeNull();
+        expect(caught?.status).toBe(403);
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("rejects 401 when issuer mismatches", async () => {
+    const h = makeHarness();
+    try {
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        rotateSigningKey(db);
+        const token = await mintToken(db, ["parachute:host:admin"], {
+          issuer: "http://127.0.0.1:9999",
+        });
+        let caught: AdminAuthError | null = null;
+        try {
+          await requireScope(db, reqWithAuth(`Bearer ${token}`), "parachute:host:admin", ISSUER);
+        } catch (err) {
+          caught = err as AdminAuthError;
+        }
+        expect(caught?.status).toBe(401);
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("rejects 401 when token is unverifiable garbage", async () => {
+    const h = makeHarness();
+    try {
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        rotateSigningKey(db);
+        let caught: AdminAuthError | null = null;
+        try {
+          await requireScope(
+            db,
+            reqWithAuth("Bearer not-a-real-jwt"),
+            "parachute:host:admin",
+            ISSUER,
+          );
+        } catch (err) {
+          caught = err as AdminAuthError;
+        }
+        expect(caught?.status).toBe(401);
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+});
+
+describe("adminAuthErrorResponse", () => {
+  test("403 → insufficient_scope with WWW-Authenticate", async () => {
+    const res = adminAuthErrorResponse(new AdminAuthError(403, "needs admin"));
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toBe("insufficient_scope");
+    expect(res.headers.get("www-authenticate") ?? "").toContain("insufficient_scope");
+  });
+
+  test("401 → invalid_token", async () => {
+    const res = adminAuthErrorResponse(new AdminAuthError(401, "bad sig"));
+    expect(res.status).toBe(401);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toBe("invalid_token");
+  });
+
+  test("non-AdminAuthError → 500 server_error", async () => {
+    const res = adminAuthErrorResponse(new Error("boom"));
+    expect(res.status).toBe(500);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toBe("server_error");
+  });
+});

package/src/__tests__/admin-config.test.ts

@@ -0,0 +1,281 @@
+import { describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  configPathFor,
+  discoverConfigurableModules,
+  readModuleConfig,
+  validateAndCoerce,
+  writeModuleConfig,
+} from "../admin-config.ts";
+import type { ConfigSchema, ModuleManifest } from "../module-manifest.ts";
+import type { ServicesManifest } from "../services-manifest.ts";
+
+function tmp(): string {
+  return mkdtempSync(join(tmpdir(), "admin-config-"));
+}
+
+const VAULT_SCHEMA: ConfigSchema = {
+  type: "object",
+  required: ["transcribe_provider"],
+  properties: {
+    transcribe_provider: {
+      type: "string",
+      description: "Speech-to-text backend.",
+      enum: ["openai", "deepgram", "groq"],
+      default: "openai",
+    },
+    max_tags_per_note: { type: "integer", default: 10 },
+    public: { type: "boolean", default: false },
+  },
+};
+
+const VAULT_MANIFEST: ModuleManifest = {
+  name: "vault",
+  manifestName: "parachute-vault",
+  displayName: "Vault",
+  kind: "api",
+  port: 1940,
+  paths: ["/vault"],
+  health: "/health",
+  configSchema: VAULT_SCHEMA,
+};
+
+const NOTES_MANIFEST: ModuleManifest = {
+  name: "notes",
+  manifestName: "parachute-notes",
+  displayName: "Notes",
+  kind: "frontend",
+  port: 1941,
+  paths: ["/"],
+  health: "/health",
+  // No configSchema — should be skipped.
+};
+
+function services(...entries: { name: string; installDir?: string }[]): ServicesManifest {
+  return {
+    services: entries.map((e) => ({
+      name: e.name,
+      port: 1940,
+      paths: ["/"],
+      health: "/health",
+      version: "0.0.0",
+      ...(e.installDir ? { installDir: e.installDir } : {}),
+    })),
+  };
+}
+
+describe("discoverConfigurableModules", () => {
+  test("includes only modules with a configSchema", async () => {
+    const dir = tmp();
+    try {
+      const result = await discoverConfigurableModules({
+        loadServicesManifest: () =>
+          services(
+            { name: "vault", installDir: "/fake/vault" },
+            { name: "notes", installDir: "/fake/notes" },
+          ),
+        configDir: dir,
+        readManifest: async (installDir) => {
+          if (installDir === "/fake/vault") return VAULT_MANIFEST;
+          if (installDir === "/fake/notes") return NOTES_MANIFEST;
+          return null;
+        },
+      });
+      expect(result.map((m) => m.name)).toEqual(["vault"]);
+      const first = result[0]!;
+      expect(first.schema).toBe(VAULT_SCHEMA);
+      expect(first.configPath).toBe(configPathFor(dir, "vault"));
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("skips entries without an installDir", async () => {
+    const result = await discoverConfigurableModules({
+      loadServicesManifest: () => services({ name: "vault" }),
+      configDir: tmp(),
+      readManifest: async () => VAULT_MANIFEST,
+    });
+    expect(result).toEqual([]);
+  });
+
+  test("skips entries whose manifest fails to read (returns null)", async () => {
+    const result = await discoverConfigurableModules({
+      loadServicesManifest: () => services({ name: "vault", installDir: "/missing" }),
+      configDir: tmp(),
+      readManifest: async () => null,
+    });
+    expect(result).toEqual([]);
+  });
+
+  test("doesn't take down the portal when one manifest throws", async () => {
+    const result = await discoverConfigurableModules({
+      loadServicesManifest: () =>
+        services(
+          { name: "vault", installDir: "/fake/vault" },
+          { name: "rogue", installDir: "/fake/rogue" },
+        ),
+      configDir: tmp(),
+      readManifest: async (installDir) => {
+        if (installDir === "/fake/vault") return VAULT_MANIFEST;
+        throw new Error("malformed module.json");
+      },
+    });
+    expect(result.map((m) => m.name)).toEqual(["vault"]);
+  });
+
+  test("sorts results by displayName", async () => {
+    const aManifest: ModuleManifest = { ...VAULT_MANIFEST, name: "alpha", displayName: "Alpha" };
+    const zManifest: ModuleManifest = { ...VAULT_MANIFEST, name: "omega", displayName: "Omega" };
+    const result = await discoverConfigurableModules({
+      loadServicesManifest: () =>
+        services({ name: "omega", installDir: "/o" }, { name: "alpha", installDir: "/a" }),
+      configDir: tmp(),
+      readManifest: async (d) => (d === "/o" ? zManifest : aManifest),
+    });
+    expect(result.map((m) => m.name)).toEqual(["alpha", "omega"]);
+  });
+});
+
+describe("validateAndCoerce", () => {
+  test("coerces strings, integers, numbers, booleans", () => {
+    const r = validateAndCoerce(
+      {
+        transcribe_provider: "deepgram",
+        max_tags_per_note: "42",
+        public: true,
+      },
+      VAULT_SCHEMA,
+    );
+    expect(r.ok).toBe(true);
+    expect(r.data).toEqual({
+      transcribe_provider: "deepgram",
+      max_tags_per_note: 42,
+      public: true,
+    });
+  });
+
+  test("rejects an integer that is not an integer", () => {
+    const r = validateAndCoerce(
+      { transcribe_provider: "openai", max_tags_per_note: "3.14", public: false },
+      VAULT_SCHEMA,
+    );
+    expect(r.ok).toBe(false);
+    expect(r.errors.max_tags_per_note).toBe("must be an integer");
+  });
+
+  test("rejects values outside the enum", () => {
+    const r = validateAndCoerce(
+      { transcribe_provider: "whisper", max_tags_per_note: "10", public: false },
+      VAULT_SCHEMA,
+    );
+    expect(r.ok).toBe(false);
+    expect(r.errors.transcribe_provider).toContain("must be one of");
+  });
+
+  test("rejects required fields when missing", () => {
+    const r = validateAndCoerce({ public: false }, VAULT_SCHEMA);
+    expect(r.ok).toBe(false);
+    expect(r.errors.transcribe_provider).toBe("required");
+  });
+
+  test("missing optional non-boolean fields are omitted from output", () => {
+    const r = validateAndCoerce({ transcribe_provider: "openai", public: false }, VAULT_SCHEMA);
+    expect(r.ok).toBe(true);
+    expect(r.data).toEqual({ transcribe_provider: "openai", public: false });
+    expect("max_tags_per_note" in (r.data ?? {})).toBe(false);
+  });
+
+  test("missing booleans default to false rather than failing required", () => {
+    const required: ConfigSchema = {
+      type: "object",
+      required: ["public"],
+      properties: { public: { type: "boolean" } },
+    };
+    const r = validateAndCoerce({}, required);
+    expect(r.ok).toBe(true);
+    expect(r.data).toEqual({ public: false });
+  });
+
+  test("number coercion accepts decimals", () => {
+    const schema: ConfigSchema = {
+      type: "object",
+      properties: { ratio: { type: "number" } },
+    };
+    expect(validateAndCoerce({ ratio: "0.25" }, schema).data).toEqual({ ratio: 0.25 });
+    expect(validateAndCoerce({ ratio: "garbage" }, schema).errors.ratio).toBe("must be a number");
+  });
+
+  test("string values pass through verbatim", () => {
+    const schema: ConfigSchema = {
+      type: "object",
+      properties: { motto: { type: "string" } },
+    };
+    const r = validateAndCoerce({ motto: "  whitespace preserved  " }, schema);
+    expect(r.data?.motto).toBe("  whitespace preserved  ");
+  });
+});
+
+describe("readModuleConfig + writeModuleConfig", () => {
+  test("returns {} when the file does not exist", () => {
+    const dir = tmp();
+    try {
+      expect(readModuleConfig(join(dir, "missing.json"))).toEqual({ data: {} });
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("round-trips a config object atomically", () => {
+    const dir = tmp();
+    try {
+      const path = join(dir, "vault", "config.json");
+      writeModuleConfig(path, { transcribe_provider: "openai", max_tags_per_note: 10 });
+      expect(existsSync(path)).toBe(true);
+      const { data, parseError } = readModuleConfig(path);
+      expect(parseError).toBeUndefined();
+      expect(data).toEqual({ transcribe_provider: "openai", max_tags_per_note: 10 });
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("surfaces a parse error without erroring", () => {
+    const dir = tmp();
+    try {
+      const path = join(dir, "config.json");
+      writeFileSync(path, "{not valid json");
+      const r = readModuleConfig(path);
+      expect(r.data).toEqual({});
+      expect(r.parseError).toBeDefined();
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("surfaces a parse error when the file is a JSON array, not object", () => {
+    const dir = tmp();
+    try {
+      const path = join(dir, "config.json");
+      writeFileSync(path, "[]");
+      const r = readModuleConfig(path);
+      expect(r.data).toEqual({});
+      expect(r.parseError).toContain("must contain a JSON object");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("trailing newline preserved on write", () => {
+    const dir = tmp();
+    try {
+      const path = join(dir, "config.json");
+      writeModuleConfig(path, { x: 1 });
+      expect(readFileSync(path, "utf8").endsWith("\n")).toBe(true);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});